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

   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