Skip to content

Configure OIDC / SSO

OpenID Connect single sign-on — corporate users sign in with their existing Microsoft Entra ID, Google Workspace, or Okta account. Same JWT downstream, so all RBAC and permission checks work unchanged.

Why use it

  • One password (the IdP's) instead of three (local + LDAP + per-product).
  • MFA / conditional access enforced at the IdP automatically apply.
  • Offboarding = disable the user in the IdP, MFCloud access dies on next login.
  • Zero password-reset tickets — that's the IdP's problem.

Prerequisites

  • Master reachable from the IdP at a stable URL (the redirect URI).
  • Operator has global_admin permission.
  • An OIDC app registered at the IdP — see provider-specific sections below.

Quick steps (any provider)

  1. Settings → 🔑 Single Sign-On (OpenID Connect).
  2. Toggle Enable OIDC sign-in.
  3. Fill in:
  4. Issuer URL — the IdP's discovery base.
    • Entra: https://login.microsoftonline.com/<tenant-id>/v2.0
    • Google: https://accounts.google.com
    • Okta: https://<your-domain>.okta.com
  5. Client ID — application/client ID from the IdP.
  6. Client Secret — paste the secret. Leave blank on subsequent saves to keep the existing value.
  7. Sign-in Button Label — what shows on the login page (default: Sign in with Microsoft).
  8. Default Role — the role assigned to new users on first SSO login.
  9. Email Claim — usually email. Entra often needs preferred_username.
  10. Save SSO Settings.

The login page now shows a "Sign in with X" button below the local form. Click → IdP authenticate → land back in the console with a fresh JWT.

Register the app at your IdP

Per-IdP step-by-step runbooks — pick the one that matches your provider:

The bullet-point summary below is enough if you've done OIDC app registration before.

Microsoft Entra ID

  1. Azure Portal → Entra ID → App registrations → New registration.
  2. Redirect URI (Web): https://<your-mfcloud-host>/api/auth/oidc/callback.
  3. After creation → Certificates & Secrets → + New client secret. Copy the Value (not Secret ID).
  4. Token configuration → + Add optional claim → tick email if you want the canonical email.
  5. API permissions → ensure openid, email, profile are granted (default).
  6. Authentication → Front-channel logout URL = https://<your-mfcloud-host>/ so logout returns to MFCloud.

Google Workspace

  1. console.cloud.google.com → APIs & Services → Credentials → + Create Credentials → OAuth client ID.
  2. Application type: Web application.
  3. Authorized redirect URI: https://<your-mfcloud-host>/api/auth/oidc/callback.
  4. After creation, copy the Client ID and Client secret.
  5. Google has no end_session_endpoint — logout clears MFCloud only.

Okta

  1. Admin console → Applications → Create App Integration → OIDC, Web Application.
  2. Sign-in redirect URI: https://<your-mfcloud-host>/api/auth/oidc/callback.
  3. Sign-out redirect URI: https://<your-mfcloud-host>/.
  4. Assignments: pick the groups that should have console access.

Behind the scenes

  • /api/auth/oidc/start generates state, nonce, and a PKCE S256 verifier; signs them into a 10-min HMAC cookie; 302s to the IdP.
  • /api/auth/oidc/callback validates the cookie, exchanges the auth code for an ID token, verifies the JWT against the IdP's JWKS, looks up or auto-creates the user by (oidc_issuer, oidc_subject).
  • Discovery doc + JWKS cached for 60 min; key rotation handled automatically (cache busts on kid miss).

Safety net — local always wins

Local sign-in (/api/login) is tried first regardless of OIDC state. The local admin user is unconditionally promoted to Super Admin on every login. You cannot lock yourself out by misconfiguring SSO.

See also