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

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