authentik¶

This page connects Specivo to authentik. Read Single sign-on first for the concepts and what each Specivo setting does. The steps were checked against authentik 2026.8: sign-in, accounts created on first sign-in, group mapping, sign-out at authentik, back-channel logout and the session check all work.

Sample values: Specivo at https://specivo.example.com (APP_URL), authentik at https://authentik.example.com, application slug specivo, provider slug authentik.

1. Create the provider and the application in authentik¶

In the authentik admin interface, go to Applications → Applications and press New Application. The wizard creates the application and its provider together. You can also create the provider first under Applications → Providers and then an application that uses it.

Application

• Name: Specivo. Slug: specivo. The slug becomes part of the issuer.

Provider: OAuth2/OpenID Provider

• Authorization Flow: default-provider-authorization-implicit-consent skips the consent screen. Choose the explicit consent flow if you want people to confirm each time.
• Under Protocol settings:
  • Client Type: Confidential.
  • Client ID: specivo, or the generated one. Client Secret: copy the generated one.
  • Grant Types: tick Authorization Code and Refresh token, and nothing else. The form ticks almost every grant type by default; Specivo needs none of the others. Without Authorization Code (for example a provider created through the API or a blueprint without grant_types) authentik refuses every sign-in, and people see sso_idp_error. Without Refresh token authentik still hands out refresh tokens but refuses them later, so Specivo cannot check sessions at authentik (the session check); Test connection then says the provider refused the refresh token. In the API and in blueprints the values are authorization_code and refresh_token.
  • Redirect URIs/Origins: add https://specivo.example.com/auth/oidc/authentik/callback/ with matching mode Strict and type Authorization. Add https://specivo.example.com/login/?logged_out=1 with matching mode Strict and type Post Logout (logout in the API and in blueprints): that is the address Specivo returns to after sign-out. No regular expressions or wildcards.
  • Signing Key: choose a certificate key pair, for example the built-in authentik Self-signed Certificate. This is required. Without a signing key authentik signs tokens with the client secret (HS256), and Specivo rejects those. With a key they are RS256.
• Under Advanced flow settings, set the Invalidation Flow to default-invalidation-flow (named Logout). It is what runs when Specivo sends someone to authentik to sign out (see Logout). The preselected default-provider-invalidation-flow only tells the person they left the application and keeps their authentik session open.
• Under Advanced protocol settings:
  • Scopes: keep the default mappings for openid, email, profile and offline_access. The profile mapping is what puts a groups claim in the token; offline_access is what makes authentik issue the refresh token the session check uses.
  • Subject Mode: keep Based on the User's hashed ID (the default).
  • Include claims in id_token: on (the default), so groups and the email arrive in the ID token.
  • Issuer mode: keep Each provider has a different issuer, based on the application slug (the default).

Who may use the application. On the application's Policy Bindings tab, bind the groups or users that may open Specivo. This is authentik's own access control, and it is enforced before Specivo sees anyone. Use Specivo's Required groups as a second layer if you want it.

2. Groups¶

authentik sends the names of the user's groups in the groups claim, as a list of strings, when the application uses the default profile scope mapping. Nothing more is needed. In Specivo the Groups claim is groups (the default). Required groups, Administrator groups and Group mappings use the group names exactly as they are in authentik, for example specivo-users and specivo-admins.

The claim lists all of a person's groups, not only those bound to the application. Name the groups you use in Specivo explicitly. A person in no group gets an empty list, so Required groups refuses them with sso_not_in_required_group.

3. Logout¶

Sign-out at authentik works with the settings above. When a person signs out of Specivo, Specivo sends the browser to the provider's end-session endpoint (https://authentik.example.com/application/o/specivo/end-session/) with the ID token and the post-logout address. authentik runs the invalidation flow, default-invalidation-flow, which ends the authentik session without asking anything, and sends the browser back to https://specivo.example.com/login/?logged_out=1. The post-logout address must be registered with type Post Logout (step 1), or authentik does not send the browser back. With default-provider-invalidation-flow instead, the person returns to Specivo but stays signed in at authentik, and the next Sign in with authentik goes through without a password.

Back-channel logout (optional) ends Specivo sessions when the authentik session ends: when the person signs out at authentik, an administrator ends their sessions, or the user is deactivated or deleted. authentik sends one logout per session, sometimes twice; Specivo handles repeats. Under Protocol settings, set the Logout URI to https://specivo.example.com/auth/oidc/authentik/backchannel-logout/ and the Logout Method to Back-channel. The authentik worker sends these requests, so the worker must be able to reach Specivo at that address. In Specivo, tick Accept back-channel logout from the provider.

4. Add the provider in Specivo¶

Administration → Single sign-on → + New provider:

The issuer ends with a slash and contains the application slug. Copy it from the Issuer shown on the provider's page in authentik rather than typing it: a missing slash makes the issuer differ and the sign-in fails.

Save, press Test connection, tick Enabled and save again. Test connection should report an end-session endpoint and back-channel logout support. After the first sign-in it should also say that sessions are checked at the provider; if it says the provider sent no refresh token, offline_access is missing from Scopes or from the provider's scope mappings. See Single sign-on for accounts, JIT and groups.

Notes for authentik¶

• Email verification. authentik's default email scope mapping always sends email_verified: false. With it, leave This provider really verifies email addresses off: it changes nothing, because Specivo never sees a verified address. In practice this means a person's Specivo email does not follow authentik, automatic linking never applies, accounts created on first sign-in have an unverified email, and Allowed email domains refuses everyone. Use Required groups or authentik's policy bindings to limit who can sign in, and let people connect existing accounts from their profile. Only if authentik's sources really verify email addresses, replace the default email mapping with your own that returns email_verified: true, and then turn the Specivo setting on.
• Language and time zone. The default mappings send neither locale nor zoneinfo. To set a person's language from authentik, add a scope mapping that returns a locale claim and select it on the provider.
• Test users. Try both a person in the groups you map and one who is in none of them, and check that the second is refused (sso_not_in_required_group) if you set required groups.

Offboarding¶

With SCIM provisioning, deactivating or deleting the user in authentik deactivates the Specivo account at once, API keys included. Without it, to take someone's access away:

1. Deactivate the user in authentik (or delete them). authentik refuses their refresh token at once, so their Specivo session ends at its next renewal, within 15 minutes, and with back-channel logout on it ends right away.
2. If you use API keys, either choose End all of their sessions and switch off their API keys for When the provider ends a session (the deactivation's back-channel logout then switches off the keys of a person without a Specivo password), or deactivate the user in Specivo as well (Administration → Users → Deactivate account), which also works for people with a password.

Ending someone's sessions in authentik (the user's Sessions tab) without deactivating them is a sign-out, not an offboarding: their refresh token, issued for offline_access, stays valid, so only back-channel logout ends the Specivo session, and they can sign in again.

If it does not work¶

The full list is in the error table.