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 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. Greenlight builds your issuer from the tenant ID: 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 Groups assigned to the application, 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.

   The dialog offers four group types, and only one fits an app like Greenlight:

   Option	What the token carries	For Greenlight
   Security groups	Every security group the user is in, nested ones included	Fine only in a small tenant whose Greenlight groups are all security groups. It leaves out Microsoft 365 groups entirely, and a user in more than 200 groups gets no groups claim at all (group overage).
   Directory roles	The user’s directory roles, in a separate wids claim — no groups claim	Doesn’t work: Greenlight reads groups, not roles.
   All groups	Security groups, distribution lists, and directory roles	Hits the same overage limit, sooner.
   Groups assigned to the application	Only the groups assigned to this app that the user is a direct member of	Recommended. Any group type works, Microsoft 365 groups included, and the token never carries more than the groups you assigned.

   Caution

   Do not skip this step. Without it, Entra issues sign-in tokens with no groups claim at all. Nobody matches the Org admin group, and if you set a User group 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. Assign the groups you’ll enter in the wizard to the app. Go to Identity → Applications → Enterprise applications → Greenlight → Users and groups → Add user/group, and add every group you’ll enter in the wizard: your Org admin group, Admin group, and User group, as you use them. With Groups assigned to the application, a group that isn’t assigned here never appears in the token.

   • Only direct members count. A user who is in the group only through another, nested group doesn’t get it in the token, so assign the group people are actually in.
   • Assigning groups to an app needs Microsoft Entra ID P1 or P2. Without it, use Security groups and keep your Greenlight groups to security groups.
   • Leave Properties → Assignment required? at No unless you also want Entra itself to block sign-in for anyone outside the assigned groups. Greenlight’s User group already does that gating.

8. (Optional) Set up sign-out. Copy the wizard’s Sign-out redirect, then go to Authentication and paste it into Entra’s Front-channel logout URL field. Save. The two screens name the same value differently: the wizard calls it Sign-out redirect, Entra calls it Front-channel logout URL.

Back in the wizard

1. Paste the Directory (tenant) ID, Client ID, and Client secret. The wizard shows the issuer it built from the tenant ID. On a sovereign cloud (US Gov, China), choose Enter a full issuer URL instead and paste your cloud’s …/v2.0 issuer.

2. Keep Group claim as groups (it matches the groups claim you added in token configuration). Every group you enter below must be one you assigned to the app in step 7.

3. (Optional) Paste the object ID of the 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, then presents your client ID and secret to Entra and asks whether your redirect URI is registered against that app. Each check shows a green tick when it passed, a red cross when it failed, or a grey dash when Greenlight could not check it, with the reason on the line beneath; only a red cross blocks Save & continue, and a failing check tells you where to copy the correct value from. On Entra, Redirect URI registered usually shows a grey dash: Entra checks the redirect URI only after someone signs in, so Validate cannot.

6. Save & continue. The secret goes straight to your cloud’s managed secret store; it is never stored in the database or shown again.

Troubleshooting

Symptom	Fix
Validate fails with an issuer mismatch	Enter the Directory (tenant) ID GUID, not a domain such as contoso.onmicrosoft.com — Entra reports its issuer by GUID. If you entered a full issuer URL, it 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	Either the groups claim is missing, or it doesn’t cover your group. Missing: the claim wasn’t added under Token configuration (or wasn’t saved), so Entra issues tokens with no groups claim and nobody ever matches — add it per step 6. Doesn’t cover your group: with Groups assigned to the application, the User group isn’t assigned under the enterprise app’s Users and groups (step 7), or the user is only a nested member; with Security groups, the group is a Microsoft 365 group. 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 claim that leaves the group out look identical from the sign-in screen.
Sign-in works but no groups arrive for some users	With Security groups or All groups: the user is in more groups than Entra puts in a token (group overage, more than 200), so Entra drops the claim entirely, or the group is a Microsoft 365 group, which Security groups never includes. Switch the claim to Groups assigned to the application (step 6) and assign your Greenlight groups (step 7). With Groups assigned to the application: the group isn’t assigned to the app, or the user is only a nested member of it.
Client credentials fails with “Entra does not recognize this Application (client) ID”	The Application (client) ID is wrong. The Directory (tenant) ID, the app’s Object ID, and the Application (client) ID are all GUIDs, so a mix-up is easy. Copy the value labelled Application (client) ID from the app registration’s Overview page.
Client credentials fails with “the issuer rejected the client secret as wrong or expired”	The client secret is wrong or has expired. Create a new secret under Certificates & secrets and paste its Value (not its Secret ID) — Entra shows the value only once.
Client credentials shows a grey dash	Entra answered with something that doesn’t name your client ID or secret as the problem — usually its own scope or grant policy. This doesn’t block the save, but nothing else in Validate confirms the Application (client) ID, so check it against the app registration’s Overview page before you save.
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). Entra checks the redirect URI only after sign-in, so Validate usually can’t catch this ahead of time.
Every sign-in suddenly shows a Microsoft “approval required” / consent prompt, right after someone turned on Show group names instead of IDs	That setting adds a delegated Microsoft Graph permission to the sign-in request, and tenant-wide admin consent for GroupMember.Read.All has not been granted on this app registration. Either grant it (API permissions → Grant admin consent) or turn the setting back off in Settings → Identity — turning it off restores the previous sign-in request immediately. See Showing group names instead of IDs.

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.