Repository navigation
oidc microsoft entra id
This guide shows how to set up Muximux to sign users in with Microsoft Entra ID (formerly Azure AD). It also shows how to send Entra group memberships to Muximux. Muximux uses these groups for its admin_groups and per-app allowed_groups features.
When you're done, users sign in to Muximux with their corporate Microsoft account. Muximux receives their group memberships as readable names like Engineering, not as GUIDs (long random IDs).
- A Microsoft Entra ID tenant (your organization's Entra directory) where you can create app registrations. You typically need the Cloud Application Administrator role (or higher).
- Muximux already serving on a stable HTTPS URL. A self-signed certificate is fine for testing. Production needs a real certificate, so that the browser follows the redirect back from
login.microsoftonline.com. - Your Muximux base URL. This guide uses
https://muximux.example.com. Put your real URL in its place everywhere.
- Open the Entra admin center.
- Open Applications > App registrations.
- Click New registration.
- Fill in these fields:
-
Name:
Muximux(or the name you want users to see on the consent screen). - Supported account types: pick Accounts in this organizational directory only. The issuer URL in Step 5 names your tenant. So only users of your tenant can sign in, and users from other organizations only if they are guests in your tenant. A multi-tenant account type does not change this.
-
Redirect URI: choose Web and enter
https://muximux.example.com/api/auth/oidc/callback. The path is fixed. The host must match your Muximux URL exactly.
-
Name:
- Click Register.
Entra shows the Overview page. Write down these two values. You will paste them into config.yaml later:
- Application (client) ID
- Directory (tenant) ID
- In the app registration, open Certificates & secrets > Client secrets.
- Click New client secret.
- For Description, enter
Muximux OIDC. - For Expires, pick a value your policy allows. Rotate the secret before it expires.
- Click Add.
- Immediately copy the Value (not the Secret ID). Entra hides it after you leave the page.
Many homelab and small-team setups skip this step. Then they cannot find out why admin_groups does not match. You must tell Entra to put groups in the ID token (the signed sign-in record that Entra sends to Muximux). You should also pick the group format.
- In the app registration, open Token configuration.
- Click Add groups claim.
- Under Select group types to include, pick Security groups, unless you also use Microsoft 365 / mail-enabled groups for access decisions. If you want Cloud-only group display names in step 5, pick Groups assigned to the application instead. Then assign the admin group to the application (Enterprise applications > Muximux > Users and groups), and make the users direct members of that group. Do the same for every group you use in
allowed_groups. Entra leaves out groups that are not assigned to the application, so their members could sign in but would not see the apps that those groups unlock. Group assignment needs an Entra ID P1 license. Without it, use group IDs. - Expand the ID section. (Optionally also expand Access / SAML if you will use them later.)
- In each section you expanded, choose how Entra sends groups:
-
Group ID (the default) sends group GUIDs. Muximux works, but your config will look like
admin_groups: [22e90a9d-1c5d-4f0b-9c5f-...]. -
sAMAccountNameor Cloud-only group display names sends readable names likeEngineering. PicksAMAccountNameif your tenant is hybrid (synced from on-prem AD). Pick Cloud-only group display names for cloud-only Entra tenants (this needs Groups assigned to the application, see step 3). If no group name matchesadmin_groups, Muximux gives the user theuserrole.
-
Group ID (the default) sends group GUIDs. Muximux works, but your config will look like
- Click Add.
Note on group overage. A user can be a member of more than ~200 groups. For that user, Entra sends a
_claim_namesclaim instead, which points to Microsoft Graph. Muximux does not follow that pointer. If your tenant has users with that many groups, narrow the Groups assigned to the application filter on the Groups claim dialog. Then Entra sends only the groups Muximux cares about.
By default, Entra's OpenID Connect permissions cover everything Muximux needs. To check this:
- Open API permissions.
- Look under Microsoft Graph. You should see
User.Read,openid,profile, andemail. - If
emailis missing, click Add a permission > Microsoft Graph > Delegated permissions and add it.
Your tenant can require admin consent for these scopes. Most tenants do not for the basic scopes. If yours does, click Grant admin consent for at the top of the API permissions page.
Edit config.yaml:
auth:
method: oidc
oidc:
enabled: true
issuer_url: https://login.microsoftonline.com/<TENANT_ID>/v2.0
client_id: <APPLICATION_CLIENT_ID>
client_secret: ${ENTRA_CLIENT_SECRET}
redirect_url: https://muximux.example.com/api/auth/oidc/callback
scopes:
- openid
- profile
- email
# Entra puts the user principal name in `preferred_username`. Leave at default.
# Entra emits `groups` once the claim is configured in Step 3.
groups_claim: groups
admin_groups:
- Muximux-Admins # match the display name (or GUID) you saw in Step 3Replace <TENANT_ID> and <APPLICATION_CLIENT_ID> with the values from Step 1. Set ENTRA_CLIENT_SECRET in the environment, so that the secret stays out of the YAML.
Restart Muximux. The Login with SSO button on /login now sends the user to Entra.
You can use the Settings page instead of editing config.yaml:
- Open Settings > Security.
- Choose Single sign-on (OIDC).
- For the issuer URL, enter
https://login.microsoftonline.com/<TENANT_ID>/v2.0. - For the client ID, enter the application (client) ID.
- Enter the client secret value from Step 2.
- For the groups claim, enter
groups. - Under admin groups, enter the group name or GUID from Step 3.
- 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.
- Sign in with a regular (non-admin) user. The user should land on the dashboard.
- Sign in with a user who is a member of the group in
admin_groups. The user should see the Settings gear in the navigation. Only admins see this gear. - Open Muximux's logs (
docker logs muximuxor systemd journal). - Look for
OIDC user logged in. The line shows the resolved username and role. A user who should be admin can showrole=user. In that case, the group claim is missing or has the wrong name.
Entra ID offers RP-initiated logout (Muximux sends the user to the provider to sign out). It does this through the end_session_endpoint in its discovery document. So provider_logout: true works without setting logout_url.
Entra ID does not offer OIDC back-channel logout (the provider tells Muximux directly that a session ended). It offers front-channel logout, which Muximux does not implement. So signing out at Microsoft does not end the Muximux session.
-
Return address. Microsoft requires the
post_logout_redirect_urito match a redirect URI registered on the app. In the app registration, open Authentication. Addhttps://muximux.example.com/login?logged_out=1(or yourpost_logout_redirect_url) under Redirect URIs. If the app registration supports personal Microsoft accounts, Entra does not accept a redirect URI with a query string. Then setpost_logout_redirect_urlto an address without one, such ashttps://muximux.example.com/login, and register that address. Without?logged_out=1, a login page withauto_redirect: truesends the user straight back to Microsoft after logout. To keep the user on the login page in that case, setauto_redirect: false. - Front-channel logout URL. Leave the Front-channel logout URL field empty. Muximux has no endpoint for it.
| Symptom | Cause | Fix |
|---|---|---|
redirect_uri mismatch from Entra |
The URI in the app registration doesn't match what Muximux sends. | Copy the Redirect URL in your Muximux config (redirect_url: line) into Entra exactly, including scheme, host, port, and path. |
| User signs in but isn't promoted to admin even though they're in the right group | Group claim isn't configured (Step 3 skipped), or admin_groups has GUIDs but Entra is emitting names (or vice versa). |
Add ?debug=true to your Muximux URL after sign-in and check the browser console. Or set log level to debug and look at the OIDC user logged in line. Either the groups claim is missing, or its values don't match admin_groups. |
AADSTS50011: The redirect URI specified in the request does not match |
Trailing slash mismatch, or HTTPS vs HTTP. | Both sides must match byte-for-byte. |
Entra returns interaction_required even after consent |
A Conditional Access policy blocks the session. | Check Microsoft Entra ID > Sign-in logs for the user. The sign-in log shows the failure reason. |
| Group claim contains GUIDs you didn't expect | Token configuration emits Group ID instead of display name. | Re-open Token configuration > groups claim and switch to sAMAccountName or Cloud-only group display names. |
-
Authentication overview for the rest of
auth.oidcand how OIDC interacts with the API key. - Other identity providers: Keycloak, 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