Skip to content

SSO Runbook — Okta

End-to-end setup for sign-in with Okta. ~10 minutes from a clean Okta tenant to a working "Sign in with Okta" button on the MFCloud console.

What you'll end up with

  • An OIDC Web Application in your Okta org.
  • Sign-in + sign-out redirect URIs registered.
  • Group claim configured so Okta groups drive MFCloud roles.
  • A client ID + secret you'll paste into MFCloud's Settings → SSO.

Prerequisites

  • Okta Super Admin or App Admin role.
  • MFCloud master reachable at a stable HTTPS URL.

Step 1 — Create the OIDC application

  1. Okta Admin Console → Applications → Applications → Create App Integration.
  2. Sign-in method = OIDC – OpenID Connect.
  3. Application type = Web Application.
  4. Next.
  5. App settings:
  6. App integration name = MFCloud Console
  7. Logo (optional) = upload an MFCloud icon for the Okta dashboard.
  8. Grant type — leave defaults: Authorization Code ticked.
  9. Sign-in redirect URIs = https://<your-mfcloud-host>/api/auth/oidc/callback
  10. Sign-out redirect URIs = https://<your-mfcloud-host>/
  11. Controlled access = pick Allow everyone in your organization to access OR Limit access to selected groups (recommended — assign only mfcloud-admins etc.).
  12. Save.

You land on the app's General tab. Copy two values from the Client Credentials section:

Field Where it goes in MFCloud
Client ID Settings → SSO → Client ID
Client secret Settings → SSO → Client Secret

The Issuer URL is your Okta tenant's domain:

https://<your-tenant>.okta.com

(For custom auth servers replace with https://<your-tenant>.okta.com/oauth2/<authServerId> — see Okta docs.)

Step 2 — Configure the group claim

So Okta groups end up in the ID token MFCloud reads.

  1. Security → API → Authorization Servers → default → Claims → + Add Claim.
  2. Fill in:
  3. Name = groups
  4. Include in token type = ID Token, Always
  5. Value type = Groups
  6. Filter = Matches regex .* (everything) — or Starts with mfcloud- to limit to MFCloud-relevant groups only.
  7. Include in = The following scopes = openid
  8. Create.

Now any group the user is a member of (matching the filter) will appear in the groups claim of their ID token.

Step 3 — Assign users / groups

  1. App's Assignments tab → Assign → Assign to People or Assign to Groups.
  2. Add the users/groups that should be able to sign in to MFCloud.

Without this, even an authenticated Okta user will get a 403 at the sign-in step.

Step 4 — Paste into MFCloud

In the MFCloud console:

  1. Settings → 🔑 Single Sign-On (OpenID Connect).
  2. Fill in:
  3. Issuer URL — https://<your-tenant>.okta.com
  4. Client ID — from Step 1.
  5. Client Secret — from Step 1.
  6. Sign-in Button Label — Sign in with Okta.
  7. Default Role — Tenant Viewer.
  8. Email Claim — email.
  9. Groups Claim — groups (matches what Step 2 created).
  10. Enable OIDC sign-in ✓.
  11. Save SSO Settings.

Step 5 — (Optional) Map Okta groups to MFCloud roles

In the same Settings → SSO panel:

  1. Scroll to the IdP GROUP → MFCloud ROLE MAPPING table.
  2. + Add Mapping for each group:
  3. Group ID = the Okta group's name (e.g. mfcloud-admins). Okta's groups claim sends group names, not the GUID-like IDs Entra uses.
  4. Role = pick from dropdown.
  5. Priority = 100 is fine unless you need a specific override order.
  6. Save Group Mappings.

A member of mfcloud-admins will now land as Super Admin on their next sign-in.

Step 6 — Test it

  1. Sign out of MFCloud.
  2. Login page → Sign in with Okta.
  3. Okta hosted sign-in → authenticate → consent (first time) → back to MFCloud dashboard.
  4. User avatar should show your Okta email; role should match the group mapping.
  5. Sign out — should bounce through <tenant>.okta.com/oauth2/v1/logout and return to MFCloud login.

Troubleshooting

Symptom Cause Fix
400: redirect_uri does not match Step 1 sign-in redirect URI mismatch Check master sends X-Forwarded-Proto: https. Uvicorn needs --proxy-headers.
User is not assigned to the client Step 3 not done Assign the user/group on the app's Assignments tab.
Group claim missing from token Step 2 not done OR filter doesn't match user's groups Re-check the claim filter; "regex .*" includes everything.
Logout doesn't return to MFCloud Sign-out redirect URI not registered (Step 1) Add https://<your-mfcloud-host>/ under Sign-out redirect URIs.

See also