---
title: "OpenID Connect"
description: "Configure a generic OpenID Connect (OIDC) identity provider for single sign-on in SurrealDB. Register a web application with the authorization code flow and add an OpenID Connect connection in SurrealDB Studio."
canonical_url: "https://surrealdb.com/docs/operate/enterprise/single-sign-on/openid-connect"
section: "Single sign-on"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# OpenID Connect

Configure a generic OpenID Connect (OIDC) identity provider for single sign-on in SurrealDB. Register a web application with the authorization code flow and add an OpenID Connect connection in SurrealDB Studio.

Connect any identity provider that supports OpenID Connect (OIDC) to SurrealDB. Use this connection when your provider is not listed by name. You register a web application in your identity provider, then enter its details in a new connection in SurrealDB Studio.

Before you start, [verify the email domain](/docs/operate/enterprise/single-sign-on.md#step-1-verify-an-email-domain) your company uses.

## Step 1: Register a web application

1. In your identity provider, register a web application that uses the **authorization code** flow and has a client secret.
2. Add `https://auth.surrealdb.com/login/callback` as a redirect URI. Some providers call it a callback URL or a sign-in redirect URI.
3. Make sure the ID token includes each person's email address and name. Most providers include them when the `email` and `profile` scopes are requested.
4. Copy the client ID and the client secret.

You also need the provider's discovery URL. It ends in `/.well-known/openid-configuration`, for example `https://idp.example.com/.well-known/openid-configuration`. SurrealDB reads the provider's endpoints and signing keys from it.

## Step 2: Add the connection in SurrealDB

1. Open **Single sign-on** in your enterprise and add a new connection.
2. Select **OpenID Connect**.
3. Under **Name the connection**, enter a **Display name**. Members see this name on the sign-in screen.
4. Under **Enter the OpenID Connect details**, enter:
    - **Discovery URL**: the provider's discovery URL from step 1.
    - **Client ID**: the client ID from step 1.
    - **Scopes**: optional. Leave it empty to request `openid profile email`.
    - **Client secret**: the client secret from step 1.
5. Under **Route sign-in domains**, select the verified domains to send to this connection. This is optional, and you can change it later.
6. Select **Create connection**.

The **Set up OpenID Connect** section of the form shows the redirect URI, with a copy button beside it, if you need it again. SurrealDB stores the client secret securely and does not show it again.

## Step 3: Provision users with SCIM

If your identity provider supports SCIM 2.0, it can create, update and deactivate people's SurrealDB accounts. Skip this step if you do not want it to manage accounts.

In Studio, [turn on SCIM and create a token](/docs/operate/enterprise/scim-provisioning.md) for this connection. Keep the **SCIM base URL** and the token ready.

Give your provider's SCIM or provisioning settings these values:

| Setting | Value |
| --- | --- |
| Base URL, or tenant URL | The SCIM base URL |
| Authentication | Bearer token |
| Token | The token from Studio |
| Objects to manage | Users |
| `externalId` | The same value that your provider sends as the `sub` claim of the ID token |

> [!IMPORTANT]
> SurrealDB identifies a person on an OpenID Connect connection by the SCIM `externalId`. It must be the same as the `sub` claim that your provider sends at sign-in. If the two are different, the person gets a second account the first time they sign in.

## Next steps

If you did not route a domain when you created the connection, [route one now](/docs/operate/enterprise/single-sign-on.md#step-3-route-domains-to-the-connection). Then [choose the applications](/docs/operate/enterprise/single-sign-on.md#step-4-choose-the-applications) that people can sign in to with this connection.
