kaboot/docs/AUTHENTIK_SETUP.md

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

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:

   TEST_USERNAME=kaboot-test-service
   TEST_PASSWORD=<paste-app-password-here>
   

8. Verify token generation works:

   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:

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

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