This guide sets up Muximux to authenticate against a Keycloak realm, with group memberships emitted in the ID token so Muximux can promote users to admin and gate per-app visibility.

The end state: users sign in with their Keycloak account, Muximux receives their group list as groups: ["developers", "Muximux-Admins"], and admins land on the Settings page automatically.

• A running Keycloak instance (any 19.x or newer release works). You need realm-administrator access on the realm Muximux will use.
• Muximux on a stable URL (HTTPS in production, HTTP works for localhost testing).
• The base URL of your Keycloak instance, including the realm path. The full issuer URL for a realm called homelab running at https://auth.example.com is https://auth.example.com/realms/homelab. Note the format; it changed in Keycloak 17 (older versions used /auth/realms/...).

1. Sign in to the Keycloak admin console and select the realm.
2. Open Clients and click Create client.
3. General settings:
   • Client type: OpenID Connect
   • Client ID: muximux
4. Capability config:
   • Client authentication: On (gives you a client secret).
   • Authentication flow: leave Standard flow checked, uncheck the rest.
5. Login settings:
   • Root URL: https://muximux.example.com
   • Valid redirect URIs: https://muximux.example.com/api/auth/oidc/callback
   • Web origins: https://muximux.example.com
6. Save.

Switch to the Credentials tab and copy the Client secret. You'll need it in config.yaml.

Out of the box Keycloak does not include groups in the ID token. Muximux needs them for admin_groups and per-app allowed_groups to work.

1. Open the muximux client and go to Client scopes.
2. Click on muximux-dedicated in the list (the client's dedicated scope).
3. Click Add mapper > By configuration > Group Membership.
4. Fill in:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off (this is the important one; with it on, Keycloak emits /Engineering instead of Engineering and admin_groups won't match what you'd write naturally)
   • Add to ID token: On
   • Add to access token: On
   • Add to userinfo: On
5. Save.

If you want some users to log in as Muximux admins, the group has to exist in Keycloak.

1. Open Groups > Create group.
2. Name: Muximux-Admins (or whatever you'd like to recognize).
3. Add members on the Members tab, or assign the group to users via Users > > Groups.

You can repeat this for any other groups you'd like to use later for per-app filtering, e.g. Engineering, On-Call.

Edit config.yaml:

auth:
  method: oidc
  oidc:
    enabled: true
    issuer_url: https://auth.example.com/realms/homelab
    client_id: muximux
    client_secret: ${KEYCLOAK_CLIENT_SECRET}
    redirect_url: https://muximux.example.com/api/auth/oidc/callback
    scopes:
      - openid
      - profile
      - email
    # Defaults match Keycloak conventions; spelled out here for clarity.
    username_claim: preferred_username
    email_claim: email
    groups_claim: groups
    display_name_claim: name
    admin_groups:
      - Muximux-Admins

Set KEYCLOAK_CLIENT_SECRET in the environment. Restart Muximux.

Instead of editing config.yaml, you can open Settings > Security, choose Single sign-on (OIDC), and enter the realm URL (https://auth.example.com/realms/homelab) as the issuer URL, the client ID from Step 1, the client secret from the client's Credentials tab, 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.

1. Visit https://muximux.example.com/login and click Login with SSO. You should be redirected to Keycloak.
2. After Keycloak sign-in you should land back on the Muximux dashboard.
3. Sign in as a member of Muximux-Admins and confirm the Settings gear appears in the navigation.
4. To inspect the actual claims Keycloak is sending: in Keycloak admin, open Clients > muximux > Client scopes > Evaluate, pick a user, and click Generated ID Token. The groups claim should be there with the names you expect (no leading slash).

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

• Sign out at Keycloak from Muximux. Set provider_logout: true under auth.oidc. In the client's settings, add Muximux's return address (https://muximux.example.com/login?logged_out=1, or your post_logout_redirect_url) to Valid post logout redirect URIs. A value of + reuses the Valid redirect URIs list, but that list holds only the callback URL, so add the return address explicitly.
• Sign out of Muximux when the user signs out at Keycloak. In the client's settings, under the logout settings, set Backchannel logout URL to https://muximux.example.com/api/auth/oidc/backchannel-logout and turn Backchannel logout session required on, so Keycloak includes the session ID (sid) in the logout token. Leave Front channel logout off: Keycloak uses the back-channel URL only when front-channel logout is off.

See Authentication for what each option does.

• Authentication overview for the rest of auth.oidc.
• Other identity providers: Microsoft Entra ID, Authentik, Pocket ID, Zitadel, Google, Authelia, Cloudflare Access.