IdP setup: Okta

Admin guide · Install wizard

This walkthrough pairs with the IdP step of the Greenlight install wizard. You’ll create an OIDC web app in the Okta admin console, copy its credentials 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

• An Okta administrator who can create app integrations.
• The Redirect URI and Sign-out redirect shown in the wizard’s IdP step.

Create the app integration

1. In the Okta admin console, go to Applications → Applications → Create App Integration.

2. Choose OIDC – OpenID Connect, then application type Web Application. Select Next.

3. Name it Greenlight. Under Sign-in redirect URIs, paste the Redirect URI from the wizard. Under Sign-out redirect URIs, paste the Sign-out redirect.

4. Under Assignments, assign the groups that should have Greenlight access (you can refine this later). Select Save.

5. Copy the Client ID and Client secret from the app’s General tab.

6. Add the groups claim. With the org authorization server (issuer is your bare org URL, the wizard’s default), open the app’s Sign On tab and set the Groups claim filter — for example groups · Matches regex · .*. If you deliberately use a custom authorization server instead, add a groups claim on the ID token under Security → API → Authorization Servers → Claims (value type Groups, with a filter matching the groups you assigned).

Back in the wizard

1. Your Issuer URL is your Okta org URL, for example https://acme.okta.com.

2. Paste the Client ID and Client secret.

3. Keep Group claim as groups (it matches the claim you added on the authorization server).

4. (Optional) Paste the name of the Okta group whose members should be Greenlight org admins into Org admin group.

5. (Optional) To restrict who can sign in, paste a group’s name into User group — only members may sign in (everyone else is refused). Leave it blank to let anyone assigned the app sign in as a user.

6. Select Validate configuration. Greenlight fetches your org’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 Okta and asks whether your sign-in 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. Okta answers some of these questions only for a signed-in user, so a grey dash on Client credentials or Redirect URI registered is common and is not a problem.

7. 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 HTTP 404	The issuer must be the bare org URL (https://acme.okta.com) — no /oauth2/default path unless you deliberately use a custom authorization server that serves discovery there.
400 Bad Request redirect mismatch at sign-in	The sign-in redirect URI in Okta doesn’t exactly match the wizard’s value (scheme, host, and path must all match). Validate pre-flights this, but Okta doesn’t always say why it refused, so the check may show a grey dash instead of failing.
Client ID format shows a grey dash saying the ID doesn’t start with 0oa	Client IDs Okta generates start 0oa. Unless you gave the app a custom client ID, copy the Client ID from the app integration’s General tab.
Sign-in fails with invalid_client	The client ID or secret is wrong. Validate can’t always tell, because Okta gives the same answer to requests it doesn’t accept at all. Copy the Client ID and a fresh Client secret from the app integration’s General tab.
Everyone is refused at Okta’s sign-in screen, before reaching Greenlight	The app integration isn’t assigned to anyone. Under the app’s Assignments tab, assign the users or groups that should have Greenlight access. Nothing in the wizard can detect this — Okta refuses at its own end, so the sign-in never reaches Greenlight.
Users sign in but have no group-based access	The groups claim isn’t on the ID token, its filter doesn’t match, the user isn’t assigned to the app, or the group mapping was filled in with Okta’s group ID (00g…) where the claim emits the group name. Paste the exact value your claim emits.