# 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