IdP setup: Other OpenID Connect provider

Admin guide · Install wizard

This walkthrough pairs with the IdP step of the Greenlight install wizard when your identity provider is not Entra ID, Okta, or Google Workspace. Any provider that implements OpenID Connect discovery and the authorization-code flow works: you create a confidential OIDC client in your provider, paste its issuer URL and credentials into the wizard, choose the name users see on the sign-in button, and validate the connection. The concrete clicks below use Authentik; other providers follow the same shape with their own console names.

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 administrator of your identity provider who can create OAuth 2.0 / OIDC clients.
• The Redirect URI and Sign-out redirect shown in the wizard’s IdP step.
• Your provider’s issuer URL — the base under which it serves /.well-known/openid-configuration over HTTPS. Opening that address in a browser must return JSON whose issuer field is the same URL.

Where roles come from

The wizard asks whether platform roles are Greenlight-managed or IdP-managed. For a generic provider it pre-selects Greenlight-managed, and you should keep that unless you know your provider emits a groups claim in its ID tokens. IdP-managed roles depend on that claim, and Greenlight cannot assume a generic provider emits one, so choosing IdP-managed makes the test sign-in required: after you save, the step stays open until you sign in once through the saved configuration and the ID token carries the configured groups claim; that test sign-in is refused with auth.group_claim_missing if the ID token carries no such claim, rather than admitted as a plain user. Once the install is finished, a user whose token carries no groups claim simply signs in with no groups, as with any other provider. A refused test sign-in is explained on the step, and you can edit the configuration to fix the claim or switch to Greenlight-managed roles. Greenlight-managed roles need no groups claim at all — you name an initial org admin by email and assign the rest in the dashboard.

Create the client (Authentik example)

1. In the Authentik admin interface, go to Applications → Providers → Create and choose OAuth2/OpenID Provider.

2. Name it Greenlight. Set Client type to Confidential. Under Redirect URIs/Origins, add the wizard’s Redirect URI as a strict match. Pick an Authorization flow (the default implicit-consent flow is fine) and a Signing key.

3. Copy the Client ID and Client Secret from the provider’s details — the secret is shown once.

4. Go to Applications → Applications → Create, name it Greenlight, give it a slug (for example greenlight), and select the provider you just created. Assign access to the users or groups who should reach Greenlight under the application’s Policy / Group / User Bindings.

5. Note the OpenID Configuration Issuer on the provider’s overview page. It is per application: https://<authentik-host>/application/o/<slug>/.

Authentik’s default profile scope mapping already emits a groups claim containing group names, so IdP-managed roles work out of the box if you choose them. Other providers differ: Keycloak needs a Group Membership mapper on the client scope, Auth0 needs an Action that adds a custom groups claim, and PingFederate needs the attribute contract to include groups.

Back in the wizard

1. Choose Other OpenID Connect provider.

2. Paste the Issuer URL — for Authentik, the per-application issuer from step 5 above.

3. (Optional) Enter a Sign-in button label, for example Acme SSO. Users see “Sign in with Acme SSO” on the login page; leave it blank to show “Sign in with SSO”.

4. Paste the Client ID and Client secret.

5. Keep Greenlight-managed roles and enter the Initial org admin email — or, if your provider emits a groups claim, choose IdP-managed, keep Group claim as the claim’s name (groups for Authentik), and paste the exact group value your provider emits into Org admin group.

6. (Optional) To restrict who can sign in, paste a group value into User sign-in group — only members may sign in. Leave it blank to let anyone your provider admits sign in as a user.

7. Select Validate configuration. Greenlight fetches <issuer>/.well-known/openid-configuration and confirms the issuer, authorization endpoint, token endpoint, and JWKS all resolve, then presents your client ID and secret to the provider and asks whether your redirect URI is registered against that client. 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. Providers vary in how much they will tell an unauthenticated caller, so a grey dash is common here and is not a problem.

8. 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 on the issuer check	The issuer in the discovery document must equal the URL you entered (a trailing slash is ignored; the path is not). Authentik issuers end in /application/o/<slug>/; copy the value from the provider page rather than typing it.
Validate fails with HTTP 404	The provider does not serve discovery at that base. Check the exact issuer your provider publishes; some providers place realms or tenants in the path (Keycloak: https://<host>/realms/<realm>).
Redirect URI mismatch at sign-in	The redirect URI registered in the provider does not exactly match the wizard’s value (scheme, host, path, and — for strict matchers — a trailing slash). Validate pre-flights this, so a mismatch the provider reports plainly fails the Redirect URI registered check before you save.
Everyone is refused at the provider’s own sign-in screen	The application is not assigned to any users or groups in the provider. Nothing in the wizard can detect this; the sign-in never reaches Greenlight.
The test sign-in is refused with auth.group_claim_missing	You chose IdP-managed roles and the ID token carries no claim under the configured group claim name. Add a groups claim in the provider (Authentik’s default profile scope emits groups; Keycloak needs a Group Membership mapper; Auth0 an Action), confirm the claim name matches, and try the test sign-in again — or edit the configuration and choose Greenlight-managed roles.
Users sign in but have no group-based access, or under IdP-managed roles everyone is a plain user and nobody is an administrator	The ID token carries no claim under the configured group claim name, or the values differ from what you mapped. Fix the provider’s claim mapping and confirm the claim name; roles are recomputed at every sign-in, so a member of the org admin group becomes an administrator the next time they sign in. Before the install finishes, you can instead reconfigure the wizard’s IdP step (for example to Greenlight-managed roles). After install, if the provider cannot emit a groups claim at all, there is no administrator left to change the setting in-product — which is why the claim must be confirmed before choosing IdP-managed roles.