oidc authentik - mescon/Muximux GitHub Wiki

OIDC: Authentik

This guide sets up Muximux to authenticate against Authentik, including emitting Authentik group memberships in the ID token so they're available to admin_groups and per-app allowed_groups.

The end state: users sign in with their Authentik account, Muximux receives their groups as groups: ["Engineering", "Muximux-Admins"], and admins land on Settings automatically.

Prerequisites

A running Authentik instance (any 2024.x release works; older versions also do, but the UI labels here come from current Authentik).
An admin account on the Authentik side.
Muximux on a stable URL (HTTPS recommended).

Step 1: Create the OAuth2 / OpenID Provider

In Authentik admin, open Applications > Providers and click Create.
Select OAuth2/OpenID Provider and 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'll 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 Certificate unless you've configured your own.
Under Advanced protocol settings:
- Subject mode: Based on the User's username (or Based on the User's UPN if your users come from a directory).
Save.

Step 2: Create the Application

Open Applications > Applications and click Create.
Name: Muximux. Slug: muximux.
Provider: pick the Muximux Provider you just created.
Optional: launch URL https://muximux.example.com/.
Save.

You can now bind policies to this application if you want to restrict who can authenticate (Authentik > Applications > muximux > Policy / Group / User Bindings). This works the same way for any OIDC client and is independent of Muximux.

Step 3: Make Sure Groups Are in the ID Token

By default, Authentik includes a groups claim in the userinfo endpoint via the goauthentik.io/providers/oauth2/scope-openid-userinfo property mapping. Verify or add it:

Open the Muximux Provider (Applications > Providers > Muximux Provider).
Scroll to Scopes and confirm the following scopes are in the Selected list:
- email
- openid
- profile
Open the property mapping list and confirm a groups mapping 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 groups to the provider's scope list.
Save.

If you'd rather use the full Authentik group path (rare), use group.path instead of group.name in the expression and adjust your admin_groups to match.

Step 4: Identify or Create the Admin Group

For Muximux to promote anyone to admin, Authentik needs a group whose name you'll list in admin_groups. Either reuse one you already have or create a new one:

Directory > Groups > Create.
Name: Muximux-Admins.
Add members on the Users tab.

Step 5: Configure Muximux

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

The Authentik issuer_url is application-scoped, hence the /application/o/<application-slug>/ suffix. The trailing slash matters; copy the OpenID Configuration Issuer value from the provider's overview page if you want to be sure.

Set AUTHENTIK_CLIENT_SECRET in the environment. Restart Muximux.

Using Settings

Instead of editing config.yaml, you can open Settings > Security, choose Single sign-on (OIDC), and enter the application-scoped OpenID Configuration Issuer value (https://authentik.example.com/application/o/muximux/, trailing slash included) as the issuer URL, the client ID and secret from the provider, groups added to the scopes, groups as the groups claim, and your admin group (for example Muximux-Admins) under admin groups. Copy the Callback URL (register at the provider) and Back-channel logout URL rows into the provider, press Test connection, then press Update Method. See Authentication for how the form handles the client secret and SSO-only sign-in.

Step 6: Validate

Visit https://muximux.example.com/login and click Login with SSO.
Authentik prompts for sign-in (and consent the first time, depending on the flow you chose). Approving redirects you back to Muximux.
Sign in as a member of Muximux-Admins and confirm the Settings gear is visible.
To inspect what Muximux actually receives: open Authentik admin > Events > Logs after signing in. The Token issued event shows the claims that were placed into the ID token, including groups.

Sign-out

authentik supports RP-initiated logout (its OIDC discovery document lists an end_session_endpoint) and OIDC back-channel logout.

Back-channel logout. Edit the OAuth2/OpenID provider (Applications > Providers), enter https://muximux.example.com/api/auth/oidc/backchannel-logout in the Logout URI field and 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_uri support for OAuth2 providers in release 2026.5, where the provider's redirect URIs can be given a logout type. On older releases, or if you cannot find the setting, check the authentik documentation for your version; the exact label could not be confirmed here. Register https://muximux.example.com/login?logged_out=1 (or your post_logout_redirect_url) there. If no post-logout redirect URIs are saved on the provider, authentik skips the matching.

See Authentication for what each Muximux option does.

Troubleshooting

Symptom	Cause	Fix
`invalid_redirect_uri` from Authentik	Redirect URI 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 the `groups` scope isn't being requested by Muximux, or the property mapping isn't producing groups.	Confirm `scopes:` in `config.yaml` includes `groups`. Then check Events > Logs for the latest `Token issued` event and look for the `groups` claim.
`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.