# 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: Enable User Registration (Sign Up)

By default, Authentik only shows a login form. To allow users to sign up, you need to create an enrollment flow and link it.

### Step 4.1: Create the Enrollment Prompt Stage

1. Go to **Flows and Stages** > **Stages**

2. Click **Create**

3. Select **Prompt Stage** and click **Next**

4. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `enrollment-prompt` |

5. In the **Fields** section, move these to the **Selected** side:
   - `default-source-enrollment-field-username` (username)
   - `default-user-settings-field-email` (email)
   - `default-password-change-field-password` (password)
   - `default-password-change-field-password-repeat` (password_repeat)

6. (Optional) In **Validation policies**, select `password-complexity` if you created it in Step 4.2

7. Click **Finish**

### Step 4.2: (Optional) Create Password Complexity Policy

1. Go to **Customisation** > **Policies**

2. Click **Create** and select **Password Policy**

3. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `password-complexity` |
   | Password field | `password` |
   | Minimum length | `8` |
   | Amount of uppercase characters | `1` |
   | Amount of lowercase characters | `1` |
   | Amount of digits | `1` |

4. Click **Finish**

You'll add this to the enrollment prompt stage later.

### Step 4.3: Create a Group for Kaboot Users

1. Go to **Directory** > **Groups**

2. Click **Create**

3. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `kaboot-users` |

4. Click **Create**

### Step 4.4: Create the User Write Stage

1. Go to **Flows and Stages** > **Stages**

2. Click **Create**

3. Select **User Write Stage** and click **Next**

4. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `enrollment-user-write` |
   | User creation mode | `Create users when required` |
   | Create users as inactive | Unchecked |
   | Group | `kaboot-users` |

5. Click **Finish**

### Step 4.5: Create the User Login Stage

1. Go to **Flows and Stages** > **Stages**

2. Click **Create**

3. Select **User Login Stage** and click **Next**

4. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `enrollment-user-login` |
   | Session duration | `hours=24` |
   | Stay signed in offset | `days=30` |
   | Network binding | `No binding` |
   | GeoIP binding | `No binding` |

5. Click **Finish**

### Step 4.6: Create the Enrollment Flow

1. Go to **Flows and Stages** > **Flows**

2. Click **Create**

3. Configure:
   | Field | Value |
   |-------|-------|
   | Name | `Enrollment Flow` |
   | Title | `Sign Up` |
   | Slug | `enrollment-flow` |
   | Designation | `Enrollment` |
   | Authentication | `No requirement` |

4. Click **Create**

5. Click on the newly created `enrollment-flow`

6. Go to the **Stage Bindings** tab

7. Click **Bind existing stage** and add stages in this order:
   | Stage | Order |
   |-------|-------|
   | `enrollment-prompt` | 10 |
   | `enrollment-user-write` | 20 |
   | `enrollment-user-login` | 30 |

### Step 4.7: Bind the Group to the Kaboot Application

1. Go to **Applications** > **Applications** > **Kaboot**

2. Go to the **Policy / Group / User Bindings** tab

3. Click **Bind existing group**

4. Select `kaboot-users`

5. Click **Bind**

Now users in the `kaboot-users` group (which includes all users who sign up) will have access to Kaboot.

### Step 4.8: Link Enrollment Flow to Login

1. Go to **Flows and Stages** > **Stages**

2. Find and click on `default-authentication-identification`

3. Scroll down to **Flow settings**

4. In the **Enrollment flow** dropdown, select `enrollment-flow`

5. Click **Update**

Now when users visit the login page, they'll see a "Need an account? Sign up." link.

### Optional: Add Password Recovery

1. In **Flows and Stages** > **Stages** > `default-authentication-identification`

2. Set **Recovery flow** to `default-recovery-flow` (if it exists)

3. Click **Update**

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

Create a regular user for manual browser testing.

1. Go to **Directory** > **Users**

2. Click **Create**

3. Fill in user details:
   | Field | Value |
   |-------|-------|
   | Username | `kaboottest` |
   | Name | `Kaboot Test` |
   | Email | `kaboottest@test.com` |

4. After creation, click on the user and go to the **Credentials** tab

5. Click **Set password** and set it to `kaboottest`

6. **Bind the user to the Kaboot application**:
   - Go to **Applications** > **Applications** > **Kaboot**
   - Click the **Policy / Group / User Bindings** tab
   - Click **Bind existing user**
   - Select `kaboottest` and click **Bind**

## Step 7: Create a Service Account for API Testing

Create a service account that can obtain tokens programmatically for automated tests.

1. Go to **Directory** > **Users**

2. Click **Create Service Account**

3. Fill in details:
   | Field | Value |
   |-------|-------|
   | Username | `kaboot-test-service` |
   | Create group | Unchecked |

4. Click **Create**

5. **Create an App Password** for the service account:
   - Click on the newly created `kaboot-test-service` user
   - Go to the **App passwords** tab
   - Click **Create App Password**
   - Name it `api-tests`
   - Copy the generated password (you won't see it again!)

6. **Bind the service account to the Kaboot application**:
   - Go to **Applications** > **Applications** > **Kaboot**
   - Click the **Policy / Group / User Bindings** tab
   - Click **Bind existing user**
   - Select `kaboot-test-service` and click **Bind**

7. **Save credentials to `server/.env.test`**:
   ```bash
   TEST_USERNAME=kaboot-test-service
   TEST_PASSWORD=<paste-app-password-here>
   ```

8. **Verify token generation works**:
   ```bash
   cd server
   npm run test:get-token
   ```
   
   You should see "Token obtained successfully" and the access token printed.

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