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.

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 passes, but sign-in fails with an Okta error naming an invalid client_id	The client ID is wrong. Validate only probes the org’s issuer, which is the same for every app in the org, so it cannot see a bad client ID. Copy the Client ID from the app integration’s General tab and re-save the IdP step.
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.