# 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:

```bash
# 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.