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.

Caution

Okta appears in the wizard as coming soon: Microsoft Entra ID and Google Workspace are the launch providers, with Okta selection enabling shortly after. These steps prepare your Okta org so configuration is a paste-and-validate exercise the moment it’s selectable.

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

• 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: go to Security → API → Authorization Servers, edit the server Greenlight will use, and under Claims add a claim named groups on the ID token, value type Groups, with a filter that matches the groups you assigned (for example, a regex of .* scoped to assigned groups).

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 Key Vault; 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).
Users sign in but have no group-based access	The groups claim isn’t on the ID token, its filter doesn’t match, or the user isn’t assigned to the app.