IdP setup: Microsoft Entra ID

Admin guide · Install wizard

This walkthrough pairs with the IdP step of the Greenlight install wizard. You’ll register an app in the Microsoft Entra admin center, copy three values back into the wizard, and validate the connection. Plan for about five minutes; everything happens in the browser — no CLI.

Note

Have the wizard open in another tab. It shows the exact Redirect URI and Sign-out redirect for your install — both live under your verified control-plane URL (for example https://greenlight.acme.com/auth/callback). Never register the temporary *.cloudapp.azure.com bootstrap URL.

What you’ll need

• A role that can create app registrations (Cloud Application Administrator or higher).
• The Redirect URI and Sign-out redirect shown in the wizard’s IdP step.

Register the app

1. Open entra.microsoft.com and go to Identity → Applications → App registrations → New registration.

2. Name it Greenlight. Under Supported account types, keep Accounts in this organizational directory only (single tenant).

3. Under Redirect URI, choose platform Web and paste the Redirect URI from the wizard. Select Register.

4. On the app’s Overview page, copy the Application (client) ID — this is the wizard’s Client ID — and the Directory (tenant) ID. Your Issuer URL is:

   https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0

5. Go to Certificates & secrets → Client secrets → New client secret. Add a description (greenlight-sso) and an expiry your policy allows, then copy the secret Value immediately — it is shown only once. This is the wizard’s Client secret.

6. Go to Token configuration → Add groups claim. Select Security groups, and under both ID and Access token sections keep Group ID. Save. This makes group memberships ride in the sign-in token, which Greenlight’s RBAC reads.

   Caution

   Do not skip this step. Without it, Entra issues sign-in tokens with no groups claim at all — every sign-in is refused with “access denied” after a normal-looking redirect through Entra, even for users who are genuinely members of the groups you configure below. Greenlight’s Group claim field in the wizard only names which claim it reads; it has no way to make Entra emit that claim. If you’ve already completed setup and are seeing this exact symptom, come back here and confirm Add groups claim was actually saved.

7. (Optional) Under Authentication, add the wizard’s Sign-out redirect as a front-channel logout URL.

Back in the wizard

1. Paste the Issuer URL, Client ID, and Client secret.

2. Keep Group claim as groups (it matches the groups claim you added in token configuration).

3. (Optional) Paste the object ID of the security group whose members should be Greenlight org admins into Org admin group.

4. (Optional) To restrict who can sign in, paste a group’s object ID into User group — only members may sign in (everyone else is refused). Leave it blank to let anyone in your tenant sign in as a user.

5. Select Validate configuration. Greenlight fetches your tenant’s /.well-known/openid-configuration and confirms the issuer, authorization endpoint, token endpoint, and JWKS all resolve.

6. Save & continue. The secret goes straight to Key Vault; it is never stored in the database or shown again.

Troubleshooting

Symptom	Fix
Validate fails with an issuer mismatch	The issuer must be the exact …/v2.0 URL with your tenant ID — not the app’s federation metadata URL.
Every sign-in redirects to “access denied,” even for users you’ve confirmed are in the right group	The groups claim wasn’t added under Token configuration (or wasn’t saved) — Entra is issuing tokens with no groups claim at all, so nobody ever matches. Confirm the user’s actual group membership independently (in the Entra admin center, under the group’s Members tab, or via Microsoft Graph’s /me/memberOf) before assuming the group ID is wrong — a mismatched group ID and a missing groups claim look identical from the sign-in screen. Add the groups claim per step 6 above, then retry.
Sign-in works but no groups arrive for some users	The user is in more groups than Entra inlines in a token (group overage, ~150–200 groups) — assign Greenlight access via fewer, dedicated groups rather than large all-purpose ones.
AADSTS50011 redirect mismatch at sign-in	The Redirect URI registered in Entra doesn’t exactly match the wizard’s value (scheme, host, and path must all match).

Tip

Whoever registered this app in Entra is automatically its owner and can change Token configuration directly — no tenant-wide admin role needed. If someone else needs to make the change, they need at least the Cloud Application Administrator directory role.