---
title: "Single sign-on with OIDC"
---

# Single sign-on with OIDC

Connect Microsoft Entra ID, Okta or another OpenID Connect provider to Neural Inverse Govern, with client authentication, claims, logout and the social sign-in options.

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](https://neuralinverse.com/docs/govern/sso-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

| Setting | Default | Meaning |
|---|---|---|
| `Issuer` | | The provider's issuer URL |
| `ClientId` | | The client ID registered at the provider |
| `ClientAuthMethod` | the preset's (`private_key_jwt` for Entra ID and Okta) | `private_key_jwt`, `client_secret_basic` or `client_secret_post` |
| `ClientSecret` | | Input only. Stored as Govern Vault ciphertext and never returned; answers show it as set or not set. |
| `RotateClientKey` | | Input only. Generates a new `private_key_jwt` key. |
| `Scopes` | `openid`, `email`, `profile` | Scopes requested |
| `EmailClaim`, `NameClaim`, `GivenNameClaim`, `FamilyNameClaim` | `email`, `name`, `given_name`, `family_name` | Claim names |
| `GroupsClaim` | `groups` | The claim that carries the person's groups |
| `SendLoginHint` | the preset's | Sends the email typed at sign-in as `login_hint` |

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

| Route | Purpose |
|---|---|
| `GET /oidc/c/{connection_id}/login` | Builds the authorisation request for a pending sign-in or a test sign-in |
| `GET /oidc/c/{connection_id}/callback` | The redirect URI: verifies the answer and completes the sign-in or test |
| `POST /oidc/c/{connection_id}/backchannel-logout` | OpenID Connect back-channel logout: a logout token verified with the provider's keys ends the sessions of that `sid` or `sub` |

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.