From e506d76e6a0817d0a6fac7dcfff5fd573c584054 Mon Sep 17 00:00:00 2001
From: Joakim <joakim@jnss.me>
Date: Tue, 6 Jan 2026 15:39:29 +0100
Subject: [PATCH] docs: add Authentik OAuth2 setup guide for opal-web

---
 docs/authentik-setup.md | 122 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/authentik-setup.md

diff --git a/docs/authentik-setup.md b/docs/authentik-setup.md
new file mode 100644
index 0000000..673d4d6
--- /dev/null
+++ b/docs/authentik-setup.md
@@ -0,0 +1,122 @@
+# 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.