Repository navigation
oidc keycloak
This guide sets up Muximux to sign users in with a Keycloak realm (a separate space of users and settings in Keycloak). Keycloak puts group memberships in the ID token (the signed sign-in record that Keycloak sends to Muximux). Muximux uses these groups to promote users to admin and to control which apps each user sees.
When you're done, users sign in with their Keycloak account. Muximux receives their group list as groups: ["developers", "Muximux-Admins"]. Admins see the Settings gear, which opens the Settings page.
- 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. Use HTTPS in production. HTTP works for localhost testing.
- The base URL of your Keycloak instance, including the realm path. Take a realm called
homelabrunning athttps://auth.example.com. Its full issuer URL (the address Muximux uses to find the provider) ishttps://auth.example.com/realms/homelab. Note the format. It changed in Keycloak 17. Older versions used/auth/realms/....
- Sign in to the Keycloak admin console.
- Select the realm.
- Open Clients.
- Click Create client.
-
General settings:
- Client type:
OpenID Connect - Client ID:
muximux
- Client type:
-
Capability config:
- Client authentication: On (gives you a client secret).
- Authentication flow: leave Standard flow checked. Uncheck the rest.
-
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
- Root URL:
- Save.
- Switch to the Credentials tab.
- Copy the Client secret. You will need it in
config.yaml.
By default, Keycloak does not include groups in the ID token. Muximux needs them, or admin_groups and per-app allowed_groups do not work.
- Open the
muximuxclient. - Go to Client scopes.
- Click on muximux-dedicated in the list (the client's dedicated scope).
- Click Add mapper > By configuration > Group Membership.
- Fill in these fields:
- Name:
groups - Token Claim Name:
groups -
Full group path: Off. This is the important one. When it is on, Keycloak sends
/Engineeringinstead ofEngineering. Thenadmin_groupswon't match the names you would naturally write. - Add to ID token: On
- Add to access token: On
- Add to userinfo: On
- Name:
- Save.
If you want some users to log in as Muximux admins, the admin group must exist in Keycloak.
- Open Groups > Create group.
- Name:
Muximux-Admins(or another name you will recognize). - Add members on the Members tab. Or assign the group to users in Users > > Groups.
You can repeat this for other groups you want 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-AdminsSet KEYCLOAK_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 realm URL (
https://auth.example.com/realms/homelab). - Enter the client ID from Step 1.
- Enter the client secret from the client's Credentials tab.
- 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) and Back-channel logout URL rows into the provider.
- 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. Muximux should send you to Keycloak.
- Sign in at Keycloak. You should land back on the Muximux dashboard.
- Sign in as a member of
Muximux-Admins. - Confirm that the Settings gear appears in the navigation.
- To see the actual claims Keycloak sends, open Clients > muximux > Client scopes > Evaluate in Keycloak admin.
- Pick a user.
- Click Generated ID Token. The
groupsclaim should be there with the names you expect (no leading slash).
Keycloak supports RP-initiated logout (Muximux sends the user to the provider to sign out). Its discovery document lists an end_session_endpoint. Keycloak also supports OIDC back-channel logout (the provider tells Muximux directly that a session ended).
-
Sign out at Keycloak from Muximux. Set
provider_logout: trueunderauth.oidc. In the client's settings, add Muximux's return address (https://muximux.example.com/login?logged_out=1, or yourpost_logout_redirect_url) to Valid post logout redirect URIs. A value of+reuses the Valid redirect URIs list. That list holds only the callback URL, so add the return address explicitly. -
Sign out of Muximux when the user signs out at Keycloak. Open the logout settings in the client's settings. Set Backchannel logout URL to
https://muximux.example.com/api/auth/oidc/backchannel-logout. Turn Backchannel logout session required on, so that 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.
| Symptom | Cause | Fix |
|---|---|---|
Invalid parameter: redirect_uri |
The URI in Muximux's redirect_url doesn't match the Valid redirect URIs list on the client. |
Set the client's redirect URI to exactly https://muximux.example.com/api/auth/oidc/callback. Avoid wildcards here. Use the exact value. |
| Sign-in works but admin promotion doesn't | The groups mapper either isn't attached or has Full group path on. |
Re-check the mapper in Step 2. Names must come through as plain strings (Engineering), not paths (/Engineering). |
404 Not Found from Keycloak when Muximux fetches discovery |
Wrong issuer URL format. Keycloak 17+ dropped the /auth/ prefix. |
Use https://<host>/realms/<realm>, not https://<host>/auth/realms/<realm>. |
Invalid token issuer after upgrading Keycloak |
The issuer in tokens changed because the public-facing URL of Keycloak changed. | Set KC_HOSTNAME_URL (or the older KEYCLOAK_FRONTEND_URL) on the Keycloak side to its public-facing URL, and make sure issuer_url: in Muximux matches. |
| Browser console shows CORS errors during sign-in | The client does not allow the Muximux web origin. | Add https://muximux.example.com to the client's Web origins. |
-
Authentication overview for the rest of
auth.oidc. - Other identity providers: Microsoft Entra ID, Authentik, 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