gems/docs/authentik-setup.md

Authentik OAuth2 Setup for Opal Task Manager

Overview

This guide walks through setting up OAuth2/OIDC authentication for Opal using Authentik.

Prerequisites

• Authentik instance running at: https://auth.example.com
• Admin access to Authentik
• Opal domain: https://opal.example.com

Step 1: Create OAuth2/OIDC Provider

1. Login to Authentik Admin Interface

   • Navigate to: https://auth.example.com/if/admin/
   • Login with admin credentials

2. Create Provider

   • Go to: Applications → Providers
   • Click: Create
   • Select: OAuth2/OpenID Provider
   • Fill in:
     • Name: Opal OAuth Provider
     • Authorization flow: default-provider-authorization-implicit-consent
     • Client type: Confidential
     • Redirect URIs/Origins (RegEx): (one per line)

       https://opal.example.com/auth/callback
       http://localhost:5173/auth/callback
       

     • Signing Key: (select default key, usually authentik Self-signed Certificate)
     • Scopes: Select: openid, profile, email
   • Click: Create

3. Note Important Values After creation, note these values (you'll need them for backend config):

   • Client ID: (displayed on provider detail page)
   • Client Secret: (click "Copy" icon to reveal and copy)

Step 2: Create Application

1. Navigate to Applications

   • Go to: Applications → Applications
   • Click: Create

2. Fill Application Details

   • Name: Opal Task Manager
   • Slug: opal
   • Provider: Select the provider you just created (Opal OAuth Provider)
   • Launch URL: https://opal.example.com
   • UI settings:
     • Icon: (optional - upload an icon or leave default)
     • Publisher: (optional - e.g., "Your Name")
     • Description: Mobile-first task management application
   • Click: Create

Step 3: (Optional) Configure Access Control

If you want to restrict access to specific users/groups:

1. Create Group (if needed)

   • Go to: Directory → Groups
   • Click: Create
   • Name: opal-users
   • Description: Users allowed to access Opal Task Manager
   • Click: Create
   • Add users to this group

2. Update Application Policy

   • Go back to your application: Applications → Applications → Opal Task Manager
   • Click on Policy / Group / User Bindings tab
   • Create binding for the opal-users group

Step 4: Record Configuration Values

Copy these values to use in the backend configuration:

# OAuth2 Endpoints (Authentik)
OAUTH_ISSUER=https://auth.example.com/application/o/opal/
OAUTH_AUTHORIZE_URL=https://auth.example.com/application/o/authorize/
OAUTH_TOKEN_URL=https://auth.example.com/application/o/token/
OAUTH_USERINFO_URL=https://auth.example.com/application/o/userinfo/

# Client Credentials (from Provider page)
OAUTH_CLIENT_ID=<your_client_id>
OAUTH_CLIENT_SECRET=<your_client_secret>

# Redirect URI
OAUTH_REDIRECT_URI=https://opal.example.com/auth/callback

Step 5: Test OAuth Flow

Before integrating with the backend, you can test the OAuth flow:

1. Authorization URL:

   https://auth.example.com/application/o/authorize/?client_id=<CLIENT_ID>&response_type=code&redirect_uri=https://opal.example.com/auth/callback&scope=openid%20profile%20email
   

2. Visit this URL in browser

3. Login with your Authentik account

4. You should be redirected to https://opal.example.com/auth/callback?code=...

5. The code parameter can be exchanged for tokens (backend will handle this)

Troubleshooting

Error: Invalid redirect URI

• Check that the redirect URI in the provider exactly matches what the app sends
• Make sure there are no trailing slashes

Error: Invalid client

• Verify client ID and secret are correct
• Check that the provider is assigned to the application

Error: User not authorized

• Check policy bindings on the application
• Verify user is in the allowed group (if using group restrictions)

Next Steps

Once Authentik is configured, proceed to Phase 2: Backend OAuth/JWT Implementation to integrate OAuth into the Opal API server.