Phase 1 done

docs/AUTHENTIK_SETUP.md

@@ -0,0 +1,159 @@
+# Authentik Setup Guide for Kaboot
+
+This guide walks through configuring Authentik as the OAuth2/OIDC identity provider for Kaboot.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Kaboot stack running (`docker compose up -d`)
+- Access to `http://localhost:9000`
+
+## Step 1: Initial Authentik Setup
+
+1. Navigate to `http://localhost:9000/if/flow/initial-setup/`
+   - **Important**: Include the trailing slash `/`
+
+2. Create the admin account:
+   - Email: Your email address
+   - Password: Choose a strong password
+
+3. Log in with the credentials you just created
+
+## Step 2: Create the Kaboot Application
+
+1. In the Authentik admin interface, go to **Applications** > **Applications**
+
+2. Click **Create with provider**
+
+3. **Application Settings**:
+   | Field | Value |
+   |-------|-------|
+   | Name | `Kaboot` |
+   | Slug | `kaboot` |
+   | Launch URL | `http://localhost:5173` |
+
+4. Click **Next**
+
+## Step 3: Configure OAuth2/OIDC Provider
+
+1. Select **OAuth2/OIDC** as the Provider Type
+
+2. Click **Next**
+
+3. **Provider Configuration**:
+   | Field | Value |
+   |-------|-------|
+   | Name | `Kaboot OAuth2` |
+   | Authorization flow | `default-provider-authorization-implicit-consent` |
+   | Client type | `Public` |
+   | Client ID | `kaboot-spa` |
+
+4. **Redirect URIs** (one per line):
+   ```
+   http://localhost:5173/callback
+   http://localhost:5173/silent-renew.html
+   http://localhost:5173
+   ```
+
+5. **Advanced Settings**:
+   | Field | Value |
+   |-------|-------|
+   | Subject mode | `Based on the User's hashed ID` |
+   | Include claims in id_token | `Yes` |
+   | Issuer mode | `Each provider has a different issuer` |
+
+6. **Scopes** - Ensure these are selected:
+   - `openid`
+   - `profile`
+   - `email`
+   - `offline_access` (for refresh tokens)
+
+7. Click **Submit**
+
+## Step 4: Verify OIDC Endpoints
+
+After creation, go to **Applications** > **Providers** > **Kaboot OAuth2**
+
+Note these endpoints (you'll need them for frontend configuration):
+
+| Endpoint | URL |
+|----------|-----|
+| Issuer | `http://localhost:9000/application/o/kaboot/` |
+| Authorization | `http://localhost:9000/application/o/authorize/` |
+| Token | `http://localhost:9000/application/o/token/` |
+| UserInfo | `http://localhost:9000/application/o/userinfo/` |
+| JWKS | `http://localhost:9000/application/o/kaboot/jwks/` |
+
+## Step 5: Test the Configuration
+
+1. Open the OpenID Configuration URL in your browser:
+   ```
+   http://localhost:9000/application/o/kaboot/.well-known/openid-configuration
+   ```
+
+2. You should see a JSON response with all OIDC endpoints
+
+## Step 6: Create a Test User (Optional)
+
+1. Go to **Directory** > **Users**
+
+2. Click **Create**
+
+3. Fill in user details:
+   - Username: `testuser`
+   - Name: `Test User`
+   - Email: `test@example.com`
+
+4. After creation, click on the user and go to the **Credentials** tab
+
+5. Click **Set password** to create a password
+
+## Environment Variables
+
+Ensure your `.env` file has the correct OIDC configuration:
+
+```bash
+OIDC_ISSUER=http://localhost:9000/application/o/kaboot/
+OIDC_JWKS_URI=http://localhost:9000/application/o/kaboot/jwks/
+```
+
+For the frontend OIDC config (`src/config/oidc.ts`):
+
+```typescript
+export const oidcConfig = {
+  authority: 'http://localhost:9000/application/o/kaboot/',
+  client_id: 'kaboot-spa',
+  redirect_uri: `${window.location.origin}/callback`,
+  // ... rest of config
+};
+```
+
+## Troubleshooting
+
+### "Invalid redirect URI" error
+- Ensure all redirect URIs are added exactly as configured in the provider
+- Check for trailing slashes - they must match exactly
+
+### "Client not found" error
+- Verify the Client ID matches `kaboot-spa`
+- Ensure the application is enabled (not archived)
+
+### CORS errors
+- Authentik handles CORS automatically for configured redirect URIs
+- Ensure your frontend origin (`http://localhost:5173`) is in the redirect URIs
+
+### Token validation fails on backend
+- Verify `OIDC_ISSUER` and `OIDC_JWKS_URI` are correct
+- The backend must be able to reach Authentik at `http://authentik-server:9000` (Docker network)
+
+## Production Notes
+
+For production deployment:
+
+1. Use HTTPS everywhere
+2. Update all URLs from `localhost` to your domain
+3. Update redirect URIs in Authentik
+4. Update frontend OIDC config with production URLs
+5. Update `.env` with production OIDC endpoints
+6. Consider enabling Authentik error reporting
+7. Configure email settings in Authentik for password recovery