# Generic OIDC single sign-on

<!-- Generated by scripts/generate.ts. Do not edit. -->

Create an OpenID Connect app in your identity provider, add the redirect URI from this setup, assign your users and enter the app's issuer and credentials here.

:::caution[Verification]
Not yet verified on a real Generic OIDC tenant. It was written from the public Generic OIDC documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{redirect_uri}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="create-app"></a>

### Create an OIDC app

In the admin console of your identity provider, create a new OpenID Connect web application for this app: a confidential client that signs users in with the authorization code flow. Give it a name your users will recognize.

:::caution[Labels not confirmed in step 1]
Written generically from the protocol specifications; no public Generic OIDC admin page was checked for the console's own labels and menu paths.
:::

</li>

<li class="idp-step">

<a id="redirect-uri"></a>

### Add the redirect URI

Add `{redirect_uri}` to the app's sign-in redirect URIs, exactly as shown. A redirect URI that differs by one character is refused.

<div class="setup-values">

Paste into Generic OIDC:

- Redirect URI: `{redirect_uri}`

</div>

Fixes: [`oidc_token_exchange_failed`](/errors/oidc_token_exchange_failed/)

</li>

<li class="idp-step">

<a id="scopes"></a>

### Allow the sign-in scopes

Allow the openid, email and profile scopes, so the ID token carries the email, email_verified, given_name and family_name claims.

Fixes: [`oidc_email_missing`](/errors/oidc_email_missing/), [`oidc_email_not_verified`](/errors/oidc_email_not_verified/)

</li>

<li class="idp-step">

<a id="groups"></a>

### Send groups (optional)

To send groups, add a groups claim with the user's group names to the ID token.

</li>

<li class="idp-step">

<a id="assign"></a>

### Assign people to the app

Assign the people or groups who should sign in to this app with single sign-on.

</li>

<li class="idp-step">

<a id="credentials"></a>

### Copy the client ID and secret

Copy the app's client ID and client secret into this setup. Keep the secret only here, and enter a new one in this setup whenever you rotate it.

Fixes: [`oidc_token_exchange_failed`](/errors/oidc_token_exchange_failed/)

</li>

<li class="idp-step">

<a id="issuer"></a>

### Enter the issuer URL

Enter the app's issuer URL in this setup. Your identity provider shows it in the app's settings or its discovery document. We read the provider's endpoints and keys from the issuer's /.well-known/openid-configuration document.

Fixes: [`oidc_discovery_unreachable`](/errors/oidc_discovery_unreachable/), [`oidc_id_token_invalid`](/errors/oidc_id_token_invalid/)

</li>

<li class="idp-step">

<a id="test"></a>

### Test the connection

Run a test sign-in in this setup, signing in as a user you assigned to the app.

</li>

</ol>

## Sources

- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html), read on 2026-10-29
- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html), read on 2026-10-29
