Repository navigation
oidc authentik
This guide sets up Muximux to sign users in with Authentik. It also shows how to put Authentik group memberships in the ID token (the signed sign-in record that Authentik sends to Muximux). Then the groups are available to admin_groups and per-app allowed_groups.
When you're done, users sign in with their Authentik account. Muximux receives their groups as groups: ["Engineering", "Muximux-Admins"]. Admins see the Settings gear, which opens Settings.
- A running Authentik instance. Any 2024.x release works. Older versions also work, but the UI labels here come from current Authentik.
- An admin account on the Authentik side.
- Muximux on a stable URL (HTTPS recommended).
- In Authentik admin, open Applications > Providers.
- Click Create.
- Select OAuth2/OpenID Provider.
- Click Next.
- Name:
Muximux Provider. -
Authorization flow: pick
default-provider-authorization-implicit-consent(or any flow that suits your consent policy). -
Protocol settings:
- Client type: Confidential
- Client ID: leave the auto-generated value or override (e.g.
muximux). - Client Secret: copy this value. You will paste it into
config.yaml. - Redirect URIs / Origins:
https://muximux.example.com/api/auth/oidc/callback. Use Strict matching mode if available. - Signing Key: pick
authentik Self-signed Certificateunless you've configured your own.
- Under Advanced protocol settings:
- Subject mode:
Based on the User's username(orBased on the User's UPNif your users come from a directory).
- Subject mode:
- Save.
- Open Applications > Applications.
- Click Create.
- Name:
Muximux. Slug:muximux. -
Provider: pick the
Muximux Provideryou just created. - Optional: launch URL
https://muximux.example.com/. - Save.
You can now bind policies to this application to restrict who can sign in. Use Authentik > Applications > muximux > Policy / Group / User Bindings. This works the same way for any OIDC client and does not depend on Muximux.
By default, Authentik includes a groups claim in the userinfo endpoint. The goauthentik.io/providers/oauth2/scope-openid-userinfo property mapping (a rule that adds data to the token) does this. Check for this claim, or add it:
- Open the Muximux Provider (Applications > Providers > Muximux Provider).
- Scroll to Scopes and confirm the following scopes are in the Selected list:
emailopenidprofile
- Open the property mapping list and confirm that a
groupsmapping is selected. If you don't see one, create a new one under Customisation > Property Mappings > Create > Scope Mapping:- Name:
OAuth2 Groups - Scope name:
groups - Expression:
return {"groups": [group.name for group in user.ak_groups.all()]}
- Add
groupsto the provider's scope list.
- Name:
- Save.
You can use the full Authentik group path instead (rare). To do this, use group.path instead of group.name in the expression. Then change your admin_groups to match.
Muximux promotes a user to admin only through a group. Authentik needs a group whose name you list in admin_groups. Reuse a group you already have, or create a new one:
- Open Directory > Groups > Create.
- Name:
Muximux-Admins. - Add members on the Users tab.
auth:
method: oidc
oidc:
enabled: true
issuer_url: https://authentik.example.com/application/o/muximux/
client_id: <client id from Step 1>
client_secret: ${AUTHENTIK_CLIENT_SECRET}
redirect_url: https://muximux.example.com/api/auth/oidc/callback
scopes:
- openid
- profile
- email
- groups
username_claim: preferred_username
email_claim: email
groups_claim: groups
display_name_claim: name
admin_groups:
- Muximux-AdminsThe Authentik issuer_url (the address Muximux uses to find the provider) is application-scoped. That is why it has the /application/o/<application-slug>/ suffix. The trailing slash matters. To be sure, copy the OpenID Configuration Issuer value from the provider's overview page.
Set AUTHENTIK_CLIENT_SECRET in the environment. Restart Muximux.
You can use the Settings page instead of editing config.yaml:
- Open Settings > Security.
- Choose Single sign-on (OIDC).
- For the issuer URL, enter the application-scoped OpenID Configuration Issuer value (
https://authentik.example.com/application/o/muximux/, trailing slash included). - Enter the client ID and secret from the provider.
- Add
groupsto the scopes. - For the groups claim, enter
groups. - Under admin groups, enter your admin group (for example
Muximux-Admins). - Copy the Callback URL (register at the provider) row into the provider. On authentik 2025.8 or later, you can also copy the Back-channel logout URL row (see Sign-out). Earlier versions do not have back-channel logout.
- Press Test connection.
- Press Update Method.
See Authentication for how the form handles the client secret and SSO-only sign-in.
- Visit
https://muximux.example.com/login. - Click Login with SSO.
- Sign in at Authentik. The first time, Authentik can also ask for consent, depending on the flow you chose.
- Approve. Authentik sends you back to Muximux.
- Sign in as a member of
Muximux-Admins. - Confirm that the Settings gear is visible.
- To see the claims that Authentik puts into the ID token, open the provider in Applications > Providers and use its Preview tab. Select the user. The preview shows the claims, including
groups. On the Muximux side, the audit log lineOIDC user logged inshows the role that Muximux gave the user.
authentik supports RP-initiated logout (Muximux sends the user to the provider to sign out). Its OIDC discovery document lists an end_session_endpoint. authentik also supports OIDC back-channel logout (the provider tells Muximux directly that a session ended).
-
Back-channel logout. Edit the OAuth2/OpenID provider (Applications > Providers). Enter
https://muximux.example.com/api/auth/oidc/backchannel-logoutin the Logout URI field. Choose Back-channel as the Logout Method. The authentik documentation lists this feature as available from authentik 2025.8. -
Post-logout redirect. authentik added
post_logout_redirect_urisupport for OAuth2 providers in release 2026.5. In that release, you can give the provider's redirect URIs a logout type. On older releases, or if you cannot find the setting, check the authentik documentation for your version. We could not confirm the exact label. Registerhttps://muximux.example.com/login?logged_out=1(or yourpost_logout_redirect_url) there. If no post-logout redirect URIs are saved on the provider, authentik skips the matching.
Some authentik versions do not send the back-channel logout in every case (see goauthentik/authentik#25826). Then a Muximux session can outlive the authentik session. To cover this, set revalidate_after (see Rechecking the provider session).
See Authentication for what each Muximux option does.
| Symptom | Cause | Fix |
|---|---|---|
invalid_redirect_uri from Authentik |
The redirect URI is not on the provider's allow list. | Add https://muximux.example.com/api/auth/oidc/callback exactly to Redirect URIs / Origins on the provider. |
| Sign-in works but admin promotion doesn't | Either Muximux does not request the groups scope, or the property mapping does not produce groups. |
Confirm scopes: in config.yaml includes groups. Then open the provider's Preview tab in Applications > Providers, select the user, and look for the groups claim. Muximux also reads claims from the userinfo endpoint. If Include claims in id_token is off on the provider, the preview may not show groups, although userinfo returns them. Then check the userinfo response before you change the mapping. |
error: unauthorized_client |
The client type or client authentication setting on the provider doesn't match what Muximux is sending. | Set the provider to Confidential and use the client secret. |
Failed to fetch discovery document in Muximux logs |
Wrong issuer URL. | Use the OpenID Configuration Issuer from the provider overview page; this is the canonical value Muximux should use. |
| Admin works for some users but not others | Some users are in groups whose names contain spaces or special characters that don't match admin_groups exactly. |
Group matching is case-insensitive but otherwise literal. Make sure admin_groups matches the exact name Authentik reports. |
-
Authentication overview for the rest of
auth.oidc. - Other identity providers: Microsoft Entra ID, Keycloak, Pocket ID, Zitadel, Google, Authelia, Cloudflare Access.
Getting Started
Features
- Apps
- HTTP Actions
- Reverse Proxy
- Docker Discovery
- Docker Labels
- Docker Swarm & Compose
- Navigation
- Split View
- Themes
- Keyboard Shortcuts
- Keyboard & Accessibility
- Health Monitoring
- Icons
- Translations
Security
Identity provider guides
Operations