stack/docs/plans/authentik-sso-setup.md

Authentik SSO Setup

Create the Authentik application

1. In Authentik, create an OAuth2/OpenID Provider.
2. Create an Application and link it to that provider.
3. Copy the generated client ID and client secret.

Required environment variables

Set these values for the gateway/auth runtime:

AUTHENTIK_CLIENT_ID=your-client-id
AUTHENTIK_CLIENT_SECRET=your-client-secret
AUTHENTIK_ISSUER=https://authentik.example.com

AUTHENTIK_ISSUER should be the Authentik base URL, for example https://authentik.example.com.

Redirect URI

Configure this redirect URI in the Authentik provider/application:

{BETTER_AUTH_URL}/api/auth/callback/authentik

Example:

https://mosaic.example.com/api/auth/callback/authentik

Test the flow

1. Start the gateway with BETTER_AUTH_URL and the Authentik environment variables set.
2. Open the Mosaic login flow and choose the Authentik provider.
3. Complete the Authentik login.
4. Confirm the browser returns to Mosaic and a session is created successfully.