Single Sign-On

Admin only. This panel is hidden from non-admin operators. If the tab isn’t visible in your Settings nav, your account doesn’t have the Admin role.

The SSO panel is the GUI for delegating Mimir authentication to your existing identity provider — typically Microsoft Entra (Azure AD), Okta, Google Workspace, Auth0, or any SAML 2.0 IdP your organization already runs. Once you wire a provider, users sign into Mimir with their corporate credentials and the IdP controls provisioning, deprovisioning, MFA, and password rotation.

This page documents the Mimir-side configuration: the fields on the form, what to copy where, how Mimir maps an IdP group to the admin role, the Edit/Disable/Remove actions. The IdP-side setup — what to click in Entra, Okta, Google, or your SAML console — is in your operator runbook, not on docs.projectmimir.io. Once your IdP admin hands you the issuer URL or the metadata URL plus the client credentials, every field on this panel is self-explanatory.

What you get

The panel shows a list of configured providers plus two Configure buttons. With no providers wired, you’ll see only the empty-state and the buttons:

No SSO providers configured. Add OIDC (Entra, Okta, Google) or SAML 2.0 below.

Once you’ve added at least one, a table appears:

Provider — a pill showing OIDC / Entra or SAML 2.0.
Name — the display name you set on the config (shows up on the Mimir login page as the “Sign in with <name>” button label).
Status — Active (green) or Disabled (muted).
Last updated — when this row was last saved, in your Time & Display format.
Actions — three buttons per row:
- Edit — reopens the configuration modal for that provider.
- Disable / Enable — flips the active flag without losing the configuration. Useful for “turn this off during the incident, keep the config so we don’t have to retype the secret”.
- Remove — deletes the configuration entirely. A confirmation modal warns “Users who sign in via this provider will lose access on their next login.” The action is destructive — no undo.

Mimir supports one OIDC config and one SAML config simultaneously. You can’t add a second Entra and a second Okta side-by-side; if you need that, the recommended pattern is a single OIDC config pointing at whichever provider is currently primary.

Wiring OIDC (Entra, Okta, Google, Auth0, …)

OIDC is the simpler of the two protocols and the right pick when your IdP supports it (which is to say: every modern provider).

Open Settings → SSO.
Click Configure OIDC. The modal opens.
Copy the Callback URL to register in your IdP — it’s the first thing in the modal, in a monospace block. Looks like https://your-mimir-host/auth/oidc/callback. Paste this URL into your IdP’s “Reply URL” / “Redirect URI” / “Allowed Callback URLs” field. (IdP-side steps live in your operator runbook.)
Fill in the modal:
- Display name — label for the Mimir login page button. Default Entra ID; change to whatever your team will recognize: Okta, Google Workspace, Corporate SSO.
- Enabled — checkbox in the top-right corner. Tick to make the provider live on the login page immediately. Leave unchecked while you’re staging the config.
- Issuer URL — your IdP’s OIDC discovery base. Examples shown under the field:
  - Entra: https://login.microsoftonline.com/{tenant-id}/v2.0
  - Okta: https://{your-org}.okta.com
  - Google: https://accounts.google.com The server will append /.well-known/openid-configuration to discover the rest of the endpoints.
- Client ID — from the application registration you made on the IdP side.
- Client secret — also from the IdP registration. Optional for public clients (rare). When editing an existing config, leave blank to keep the existing value; type a new value to replace it. The placeholder reads •••••••• in edit mode so you know an existing secret is on file.
- Redirect URI — defaults to the callback URL shown at the top. You can override if your deployment terminates TLS at a different hostname than Mimir’s UI; otherwise leave alone.
- Scopes — space- or comma-separated OIDC scopes. Default openid email profile covers every Mimir use case. Add groups if your IdP needs an explicit scope to include group claims (Entra doesn’t, Okta sometimes does).
- Admin groups — optional. A comma- or space-separated list of group names. If the IdP includes any of these in the authenticated user’s groups claim, Mimir assigns the user the Admin role at sign-in. Leave blank to manage roles manually (everyone signs in as Operator, you promote individuals out of band).
Click Save. The modal closes; the new row appears in the table with Active status (or Disabled if you unticked Enabled).

The configuration is now live on the login page. The next time anyone visits /login, they’ll see a Sign in with <name> button next to the local password form.

Wiring SAML 2.0

SAML is the right pick when your IdP only speaks SAML, or when your security team has standardized on SAML across the org. The mechanics are similar to OIDC but the field set is different.

Open Settings → SSO.
Click Configure SAML 2.0. The modal opens.
Copy both URLs from the monospace card at the top of the modal:
- ACS URL (Assertion Consumer Service) — where the IdP POSTs the SAML response: https://your-mimir-host/saml/acs.
- SP Metadata URL — https://your-mimir-host/saml/metadata. Most IdPs accept this URL directly as a one-click way to pull all the SP details (entity ID, ACS URL, certificate).
Fill in the modal:
- Display name — login button label. Default SAML IdP; change to Okta SAML, OneLogin, etc.
- Enabled — checkbox in the top-right corner.
- IdP metadata URL — the IdP’s metadata endpoint. Mimir fetches and caches the XML at save time, then uses it to verify SAML assertions. Most IdPs publish this at a well-known location (Okta: https://{org}.okta.com/app/{app-id}/sso/saml/metadata).
- Entity ID (SP) — defaults to https://your-mimir-host/saml/metadata. This is Mimir’s identifier in the SAML federation; only change if your IdP requires a specific value.
- ACS URL — defaults to https://your-mimir-host/saml/acs. Leave alone unless your deployment terminates TLS at a different hostname.
- Admin groups — same semantics as OIDC. Group names from the IdP’s groups SAML attribute. Members of any listed group land with the Admin role.
Click Save. Mimir fetches the IdP metadata at this moment; if the URL is unreachable, save fails with the error shown in a toast.

The provider lights up on the Mimir login page the moment the row saves with Active status.

Admin groups in detail

The Admin groups field is the single mechanism that turns IdP group membership into Mimir admin role. Behavior worth knowing:

By default the check runs only at first sign-in (JIT provisioning). Mimir evaluates the user’s group claim once, at the moment it creates their users row. Every subsequent sign-in reads the role straight from the database. This means adding or removing a user from an IdP admin group does NOT retroactively change their Mimir role — if you wire up admin groups after people have already signed in, the existing rows keep whatever role they were provisioned with (typically Operator, since you hadn’t configured the groups yet).
Opt in to per-login re-evaluation with MIMIR_SSO_REEVALUATE_ROLE_ON_LOGIN=true. When set, Mimir recomputes the role from the current group claims on every SSO sign-in and updates users.role when it changes (which also invalidates the user’s existing sessions). This closes the deprovisioning gap: pull a user from the admin group at your IdP and they lose Mimir admin on their next login. It is off by default because it is a behavior change — a misconfigured Admin groups field (or an IdP that stops emitting the groups claim) would demote real admins. As a backstop, Mimir refuses to demote the last remaining active admin via this path, so a claim hiccup can’t lock your whole org out of the dashboard. Verify your Admin groups list and that the IdP reliably emits group claims before enabling it.
Match is by name, case-insensitive, exact. IT-Security and it-security both match, but IT-Security-Admins doesn’t match IT-Security. List every name you want to grant admin.
Empty field = no automatic admin promotion. With the field blank, every SSO-provisioned user lands as Operator.
One group is enough. If a user is a member of any of the listed groups at provisioning time, they get Admin. The check is OR, not AND.

Unless you enable per-login re-evaluation (above), role promotion is not reactive, and the operational implication is the same gap the Users panel describes: there’s no GUI flow to change a user’s role after their account exists. If an existing SSO user needs to be promoted to Admin (or demoted) and you’re on the default, your operator has to update the users.role column directly. Get the admin groups right before people start signing in, or accept that the first wave will need manual fixup — or turn on MIMIR_SSO_REEVALUATE_ROLE_ON_LOGIN so the next sign-in fixes it for you.

For OIDC, the groups claim shows up only if the IdP includes it (typically via the groups scope; Entra includes it by default once the application is granted group permissions; Okta usually needs an explicit scope). For SAML, the IdP must include a groups attribute in the assertion.

If you wired everything but Admin groups doesn’t seem to take effect, the most likely cause is the claim/attribute isn’t in the assertion at all. The fix is on the IdP side — verify the groups claim is being emitted using your IdP’s debugger tools (your operator runbook covers the IdP-side debugging surface).

What this panel doesn’t do

It doesn’t configure your IdP for you. The reply URL, the app registration, the group claim configuration — those steps are in your operator runbook, not surface-able from Mimir’s GUI.
It doesn’t synchronize users on a schedule. SSO accounts appear on the Users table only after their first successful sign-in. There’s no SCIM, no nightly LDAP pull. Provisioning is lazy.
It doesn’t deprovision automatically. Removing a user from the IdP prevents future new sign-ins through the IdP, but does not affect anything else: the row stays in Users (no GUI delete affordance — see that panel for the gap description), the user’s existing Mimir session keeps working until it expires naturally (default 24h), and any API key they minted continues to authenticate. Mimir’s auth path checks the local users.status and authorization version, not the IdP. To actually lock a removed employee out: your deployment operator has to flip the users.status column to non-active or bump the user’s authz_version directly in the database — there’s no GUI affordance to do either in v1. Plan IdP offboarding around this gap, not against the doc fiction that “the IdP refuses, Mimir refuses.”
It doesn’t surface real-time SSO health. The Last updated column shows when you last edited the row, not when the IdP was last reachable. A broken IdP shows up as user sign-in failures, not a status indicator here.

Editing an existing provider

Heads up — the edit modal does NOT pre-populate. The modal title flips to Edit OIDC configuration / Edit SAML configuration and the Client secret field shows the placeholder •••••••• with the hint “or to keep existing”, but every form field opens empty regardless. The server replaces the entire stored config with whatever you submit — so if you only want to change Admin groups but leave the rest blank, you’ll silently wipe the Issuer URL, Client ID, Client Secret, Redirect URI, and Scopes from the saved configuration and break sign-ins on the next save. Until this is fixed in the GUI, the safe operator gesture is to re-type every field every time you click Edit — treat the edit modal as a re-create modal.

Click Edit on the row.
The modal opens with the title Edit OIDC configuration / Edit SAML configuration and every field set to its initial blank or default value (the OIDC modal defaults Display name to Entra ID, Redirect URI to <origin>/auth/oidc/callback, and Scopes to openid email profile; the SAML modal defaults Display name to SAML IdP, Entity ID to <origin>/saml/metadata, and ACS URL to <origin>/saml/acs).
Re-enter every field as if you were creating the provider from scratch, including the Client secret (the placeholder •••••••• and the hint about “keeping existing” are misleading in v1 — leaving the field blank writes an empty secret to the server).
Click Save changes. The row’s Last updated column updates to now.

Disabling vs Removing

Disable flips the enabled flag. The provider’s button disappears from the login page; existing browser sessions signed in via the provider keep working until they expire naturally. The config row stays in the table with Disabled status. Re-enable with one click.
Remove deletes the config row entirely. Users authenticating via the deleted provider get rejected on their next sign-in. The user rows in the Users table stay (Mimir does not cascade-delete users when their SSO provider is removed — another GUI gap, see the Users page).

Disable is the right tool when you’re rotating IdP credentials and want to coordinate downtime. Remove is the right tool when you’re permanently migrating off a provider.

Troubleshooting

The Mimir login page doesn’t show my provider button. The row exists but Status is Disabled. Click Enable.

Save failed on the OIDC modal. Common causes:

The Client secret field contains characters the IdP doesn’t match (extra trailing newline from a clipboard copy). Re-paste.
The Issuer URL doesn’t return a valid /.well-known/openid-configuration document. Try opening the URL with /.well-known/openid-configuration appended in your browser; you should see JSON.

Save failed on the SAML modal. Almost always the IdP metadata URL is unreachable from the Mimir server (proxy issue, private DNS, certificate trust). Try opening the URL from a shell on the Mimir host.

Users land as Operator instead of Admin. Three things to check, in order. (1) Was Admin groups populated before this user signed in for the first time? The check is only run at JIT provisioning — see the Admin groups in detail section above. (2) Is the user actually in the group you listed under Admin groups? (3) Is the IdP actually emitting the groups claim or attribute in the assertion? Your IdP-side debugger is the right tool for that last one — Mimir trusts what the IdP sends, so if the claim isn’t in the assertion, Mimir can’t match it.

Failed to load SSO config on page load. A backend error fetching the list — check the server log. The most common cause is the database role lacking SELECT permission on sso_configs (transient during deploy; persistent if migration 028 failed).