Skip to content

SSO Runbook — Microsoft Entra ID (Azure AD)

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

What you'll end up with

  • An MFCloud-specific app registration in your Entra tenant.
  • A redirect URI registered for the OIDC callback.
  • A front-channel logout URL registered so RP-initiated logout actually signs the user out at Microsoft.
  • A client ID + client secret you'll paste into MFCloud's Settings → SSO.
  • (Optional) Groups claim configured so group → role mapping works.

Prerequisites

  • Global Administrator or Application Administrator role on the Entra tenant.
  • MFCloud master reachable at a stable URL with a valid TLS cert (Entra refuses HTTP and refuses self-signed certs for sign-in URLs that aren't localhost).
  • The exact MFCloud hostname — used three times below, byte-for-byte identical.

Step 1 — Create the app registration

  1. Azure Portal → Microsoft Entra ID → App registrations → + New registration.
  2. Fill in:
  3. Name — MFCloud Console (visible only to admins).
  4. Supported account types — most setups: Accounts in this organizational directory only (Single tenant). Pick Multitenant only if you serve external partners with their own Entra tenants.
  5. Redirect URI — Platform = Web, value = https://<your-mfcloud-host>/api/auth/oidc/callback.
  6. Register.

You land on the app's Overview page. Copy two values:

Field Where it goes in MFCloud
Application (client) ID Settings → SSO → Client ID
Directory (tenant) ID used to build the Issuer URL below

The Issuer URL for MFCloud is:

https://login.microsoftonline.com/<TENANT_ID>/v2.0

(Note the /v2.0 suffix — MFCloud's OIDC verifier expects v2 tokens.)

Step 2 — Create the client secret

  1. Certificates & secrets → Client secrets → + New client secret.
  2. Description = mfcloud, Expires = 24 months (set a calendar reminder to rotate).
  3. Add.
  4. Copy the Value column immediately — Azure hides it after you leave the page. You can't recover it; you'd have to make a new secret.

Paste this value into Settings → SSO → Client Secret on the MFCloud side.

Don't copy Secret ID by mistake

The portal shows two columns: Value and Secret ID. The one you want is Value — typically ~40 chars, starts with a letter. Secret ID is a GUID, only useful for audit.

Step 3 — Configure the front-channel logout URL

Required for RP-initiated logout to bounce the user back to MFCloud cleanly.

  1. Authentication → Front-channel logout URL = https://<your-mfcloud-host>/
  2. Save.

Without this, clicking Logout in MFCloud will sign the user out at Entra but Microsoft's logout page won't return them to MFCloud — they'll land on a generic "Pick an account to sign out of" screen.

Step 4 — Configure API permissions

The defaults are usually enough but worth confirming:

  1. API permissions → verify these Microsoft Graph delegated permissions are present:
  2. openid (Sign users in)
  3. profile (View basic profile)
  4. email (View email address)
  5. If they're missing → + Add a permission → Microsoft Graph → Delegated permissions → tick all three → Add.
  6. Grant admin consent for — green tick should appear in the Status column.

Step 5 — Add the groups claim (optional, for group → role mapping)

Only needed if you want Entra group membership to drive MFCloud roles.

  1. Token configuration → + Add groups claim.
  2. Pick Security groups (or Groups assigned to the application if you're scoping tighter).
  3. Customize Token properties: pick Group ID for the ID token (MFCloud expects ObjectIds in the claim by default; switch to sAMAccountName only if your group map uses display names).
  4. Add.

To find a group's ObjectId for the MFCloud mapping table: Entra ID → Groups → click the group → Object ID field at the top.

Step 6 — Paste into MFCloud

In the MFCloud console:

  1. Settings → 🔑 Single Sign-On (OpenID Connect).
  2. Fill in:
  3. Issuer URL — https://login.microsoftonline.com/<TENANT_ID>/v2.0
  4. Client ID — Application (client) ID from Step 1.
  5. Client Secret — Value from Step 2.
  6. Sign-in Button Label — Sign in with Microsoft (default is already this).
  7. Default Role — what newly-signed-in users get if no group mapping matches. Tenant Viewer is the safe default.
  8. Email Claim — email works for most setups; if your tenant doesn't populate email, change to preferred_username (Entra always has this).
  9. Groups Claim — groups (leave as default; Entra writes ObjectIds here once Step 5 is done).
  10. Enable OIDC sign-in ✓.
  11. Save SSO Settings.

Step 7 — Test it

  1. Log out of the MFCloud console (sign out via the user avatar menu).
  2. The login page should now show a Sign in with Microsoft button below the local form.
  3. Click it. You'll be redirected to login.microsoftonline.com. Sign in with a tenant user.
  4. Microsoft bounces you back to /api/auth/oidc/callback, MFCloud verifies the ID token, creates a federated user row, and lands you on the dashboard.
  5. Open the user-avatar menu in the top right — your username should be the email (or UPN) Entra sent.
  6. Sign out — you should be redirected through Microsoft's logout flow and back to MFCloud's login page.

Troubleshooting

Symptom Cause Fix
AADSTS50011: redirect URI mismatch Step 1 Redirect URI doesn't byte-match what MFCloud generates Check master is behind a reverse proxy that sends X-Forwarded-Proto: https. Uvicorn must be started with --proxy-headers.
IdP returned error 'invalid_client' Client Secret wrong / expired Step 2 — generate a fresh secret, re-paste.
ID token rejected: aud is required Token's audience claim doesn't include your client_id Token configuration → Optional claims → add aud to the ID token.
User signs in but lands as Tenant Viewer Group mapping not picking up Step 5 — confirm groups claim is enabled; check Entra ObjectId matches what you pasted in MFCloud's mapping table.
Logout doesn't return to MFCloud Front-channel logout URL not registered Step 3.

See the SSO callback 400 troubleshooting page for deeper diagnosis.

See also