Authentik SSO Setup

Authentik is a modern open-source identity provider — often the self-hosted choice after outgrowing Keycloak or starting fresh.

In Authentik

Create an OAuth2/OpenID Provider

Applications → Providers → Create → OAuth2/OpenID Provider:

Field	Value
Name	`dockmesh`
Authorization flow	default-provider-authorization-explicit-consent
Client type	Confidential
Client ID	(auto-generated, copy it)
Client secret	(auto-generated, copy it)
Redirect URIs	`https://dockmesh.example.com/auth/oidc/callback`
Signing Key	`authentik Self-signed Certificate` (default)

Under Advanced protocol settings:

Scopes: include email, profile, openid, offline_access, and any custom groups scope you define (see below)
Subject mode: Based on the User's hashed ID (stable)
Include claims in id_token: ON

Save.

Create a Groups scope

If you want group-based role mapping, create a custom scope:

Customization → Property Mappings → Create → Scope Mapping:

Field	Value
Name	`groups`
Scope name	`groups`
Expression	`return [group.name for group in user.ak_groups.all()]`

Attach this scope to the dockmesh provider under Advanced protocol settings → Scopes.

Create the Application

Applications → Applications → Create:

Field	Value
Name	`dockmesh`
Slug	`dockmesh`
Provider	`dockmesh` (the provider you just created)
Launch URL	`https://dockmesh.example.com`

Save. Optionally upload an icon for the Authentik dashboard.

Restrict access (optional)

Access policies: require users to be in a specific Authentik group to use the app. Create a policy:

Applications → Applications → dockmesh → Policy / Group / User Bindings → Create binding:

Group: dockmesh Users (or whatever group gates access)

Users not in this group can’t reach dockmesh via SSO.

In dockmesh

Settings → Authentication → OIDC → Add provider:

Field	Value
Display name	`Authentik`
Issuer URL	`https://authentik.example.com/application/o/dockmesh/`
Client ID	(from Authentik)
Client secret	(from Authentik)
Scopes	`openid profile email groups`
Groups claim	`groups`

Click Test — Authentik’s discovery endpoint should respond.

Save.

Group mapping

Settings → Authentication → Group mappings:

Claim value	Role	Scope
`dockmesh-admins`	Admin	all
`dockmesh-ops`	Operator	all
`dockmesh-ops-prod`	Operator	tag=prod
`dockmesh-viewers`	Viewer	all

Group names must match Authentik groups exactly.

dockmesh login page now shows Login with Authentik. Click it → redirects to Authentik → log in → redirects back to dockmesh logged in. First login creates the dockmesh user with the resolved role.

Troubleshooting

“Invalid issuer”:

The issuer URL must match what Authentik’s .well-known/openid-configuration endpoint returns in issuer. Check: curl https://authentik.example.com/application/o/dockmesh/.well-known/openid-configuration
Exact trailing slash matters

User created but no groups in token:

Is the groups scope attached to the provider?
Is the scope mapping expression valid? Test it in Authentik’s scope mapping detail page
Is the scope in dockmesh’s scope list (openid profile email groups)?

Token signature failed:

Clock skew between Authentik and dockmesh > 60s — both should run NTP
If you rotated the signing cert in Authentik, dockmesh caches the JWKS for 1 hour — restart dockmesh to force refresh, or wait