Single sign-on with OIDC

OpenID Connect connections are Identity Center connections, like SAML ones: the same six setup steps, the same draft and test-before-activate rule, and the same actions. This page covers what is specific to OIDC. Read Single sign-on with SAML for the connection lifecycle, session policy and the action table.

How sign-in works

Govern is the relying party. It uses the authorisation code flow with PKCE S256 and a nonce, and verifies the ID token against the provider's discovery document and key set:

• The discovery issuer must equal the configured issuer exactly, and every endpoint must be https.
• Calls to the provider never follow redirects, so a client secret is never resent to another host.
• The ID token must be signed with an RS, PS or ES algorithm by a key from the provider's key set. HS and none are refused.
• The token must carry the configured issuer, this client as audience (and as azp when present or when there are several audiences), exp, iat and the nonce.
• Only email_verified: true lets an email be linked or provisioned.
• When the ID token has no email, Govern reads the userinfo endpoint, whose sub must match.
• The callback requires the RFC 9207 iss parameter to name the connection's issuer.

Calls to the provider go through Govern's outbound network guard. A provider on a private or loopback address needs the operator to allow it with NI_AUTH_OUTBOUND_ALLOW_PRIVATE_CIDRS.

Set up a connection

Open Identity Center > Connections, add a connection and choose OpenID Connect. The presets that support OIDC are Microsoft Entra ID, Okta, Ping Identity and "Other OpenID Connect provider".

1. Choose the identity provider.
2. Copy the redirect URI. It is NI_AUTH_PUBLIC_URL/oidc/c/{connection_id}/callback (ServiceProvider.RedirectUri in DescribeConnection).
3. Enter the issuer and the client (below).
4. Preview the attribute and group mapping.
5. Test sign-in.
6. Activate the tested revision.

Microsoft Entra ID

1. In the Microsoft Entra admin center, open App registrations, choose New registration and add the redirect URI as a Web platform redirect URI.
2. In Govern, enter the issuer https://login.microsoftonline.com/<tenant ID>/v2.0 and the application (client) ID.
3. Under Certificates & secrets, upload the Govern certificate (private_key_jwt, recommended) or create a client secret.
4. Under Token configuration, add the optional claims email, given_name and family_name, and a groups claim limited to the groups assigned to the application.

An Entra ID groups overage (_claim_names or groups.link) is refused.

Okta

1. In the Okta Admin Console, create an app integration of type OIDC, Web Application, and enter the sign-in redirect URI.
2. In Govern, enter your Okta domain (https://<your Okta domain>) as the issuer and the client ID.
3. For client authentication choose Public key / Private key and add the Govern public key (recommended), or use a client secret.
4. On the Sign On tab, set the groups claim filter so the ID token carries the groups assigned to the application.

The Okta preset asks for the scopes openid, email, profile and groups.

Settings

With private_key_jwt, Govern generates an RS256 key for the connection. DescribeConnection returns its public JWK and a self-signed certificate with its x5t thumbprint: Entra ID registers the certificate, Okta the JWK. The private key is stored only as Govern Vault ciphertext.

Logout

Signing out of Govern sends the browser to the provider's end-session endpoint when it has one (RP-initiated logout).

Refusals

Test sign-ins and sign-ins report stable reasons, among them discovery_failed, issuer_mismatch, client_auth_method_unsupported, token_exchange_failed, id_token_invalid, nonce_mismatch, subject_missing, email_missing, entra_group_overage, groups_claim_invalid, userinfo_failed and logout_token_invalid. Each sign-in, success or failure, is audited as auth.external_signin with the connection ID.

Social sign-in

Google, GitHub and Microsoft can be turned on per organisation on Identity Center > Social sign-in, or with PUT /api/v1/organizations/{id}/social/{provider} (client credentials, optional Microsoft tenant, enabled state, allowed_email_domains and jit_provisioning, which is on when omitted).

• Only an email the provider says it verified can be linked or provisioned: Google's email_verified, GitHub's verified primary address.
• Microsoft's user info has no verification claim, so a Microsoft social connection signs in only identities already linked to a user.
• Client secrets are encrypted with AES-256-GCM and never returned.

For company sign-in, prefer an Identity Center connection: it supports tests, revisions, group mappings and enforcement, which social sign-in does not.