> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-on (SSO) for DB Console

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Single sign-on (SSO) for DB Console allows a CockroachDB user to access the <InternalLink path="ui-overview">DB Console</InternalLink> in a secure cluster via an OpenID Connect (OIDC) client and an external identity provider. When SSO is configured and enabled, the <InternalLink path="ui-overview#db-console-access">DB Console login page</InternalLink> will display an OAuth login button in addition to the password access option.

<Note>
  This page covers OIDC-based SSO authentication to the DB Console. For SSO authentication to the SQL interface using JSON Web Tokens (JWT), refer to <InternalLink path="sso-sql">Cluster Single Sign-on (SSO) using JWT</InternalLink>. For LDAP-based authentication (which also supports DB Console login), refer to <InternalLink path="ldap-authentication">LDAP Authentication</InternalLink>.
</Note>

CockroachDB's OIDC implementation for DB Console uses the [authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1) to authenticate a user.

## Configuration

### Prerequisites

* **IdP:** You must have access to an OAuth 2.0 identity provider and client. Refer to [Step 1: Provision an OIDC client](#step-1-provision-an-oidc-client).

* **CockroachDB cluster**: You must have access to one of the following:
  * A self-hosted cluster enabled with a valid <InternalLink path="licensing-faqs">CockroachDB Enterprise license</InternalLink>.
  * A <InternalLink version="cockroachcloud" path="create-your-cluster">CockroachDB Advanced cluster</InternalLink>.

<Note>
  CockroachDB Standard and Basic clusters do not have access to the DB Console. For SQL client authentication on these tiers, refer to <InternalLink version="cockroachcloud" path="cloud-sso-sql">Cluster Single Sign-on (SSO) using the Cloud Console</InternalLink>.
</Note>

### Step 1: Provision an OIDC client

These steps demonstrate how to create an OIDC auth client in Google Cloud Platform to use for SSO authentication to the DB Console.

1. Open the [Credentials page](https://console.developers.google.com/apis/credentials) for your account at Google APIs.

2. Click **+ CREATE CREDENTIALS** and select **OAuth client ID**. Specify a **web application** from the pulldown menu.

3. Note the *client ID* and *client secret* of the OAuth 2.0 client: you will need to configure your cluster to use these values.

4. Add your cluster's callback URL to the list of **Authorized redirect URIs**. On a local cluster, this will be `https://{ your cluster's domain }:8080/oidc/v1/callback`. Subsequently, when configuring your cluster, you will need to ensure that the cluster setting `server.oidc_authentication.redirect_url` has the same value.
   * For a self-hosted cluster, the domain is `localhost`.
   * For an Advanced cluster, open the DB Console from the cluster’s **Tools** tab in the Cloud Console, and use the host portion of that URL as your domain.

### Step 2: Configure cluster settings

You must have the required privileges to update your cluster settings. Refer to <InternalLink path="set-cluster-setting#required-privileges">`SET CLUSTER SETTING`</InternalLink>.

#### Cluster settings

Configure the <InternalLink path="cluster-settings">cluster settings</InternalLink> in the following table to enable SSO authentication to the DB Console. Refer to [Update your cluster settings](#update-your-cluster-settings).

| Cluster Setting                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.oidc_authentication.enabled`               | A Boolean that enables or disables SSO.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `server.oidc_authentication.client_id`             | Your auth client's ID.<br />**Example:** `32789079457-g3hdfw8cbw85obi5cb525hsceaqf69unn.apps.googleusercontent.com`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `server.oidc_authentication.client_secret`         | Your auth client's secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `server.oidc_authentication.client.timeout`        | An optional HTTP client timeout for external calls made during OIDC authentication, in seconds. Defaults to `15` seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `server.oidc_authentication.redirect_url`          | Specifies the callback URL that redirects the user to CockroachDB after a successful authentication. This can be the address of a node in the cluster or the address of a load balancer that routes traffic to the nodes. You must append the path with `/oidc/v1/callback`. Accepts either a single URL string (for example, `https://{your_cluster's_domain }:8080/oidc/v1/callback`) or a JSON object with the following format, which supports region-based OIDC authentication with a callback URL configured per region:<br />**Example:** `{"redirect_urls": {"us-east-1": "https://{cluster_ip_address}:8080/oidc/v1/callback","eu-west-1": "example.com"}}`                |
| `server.oidc_authentication.provider_url`          | Specifies the OAuth issuer identifier. Ensure that the URL does not have a terminating `/`. For more information, refer to the [OIDC specification](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). Note that CockroachDB appends the required `/.well-known/openid-configuration` by default. You do not need to include it.<br />**Example:** `https://accounts.google.com`.                                                                                                                                                                                                                                                                          |
| `server.oidc_authentication.scopes`                | A space-delimited list of the [OAuth scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) being requested for an access token. The `openid` scope is required. Additional scopes such as `email` and `profile` may be needed depending on your `claim_json_key` configuration.<br />**Example:** `openid email` or `openid profile email`.                                                                                                                                                                                                                                                                                                                    |
| `server.oidc_authentication.claim_json_key`        | The field/key used to identify the user from the external identity provider's [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken), such as `email`. The key can contain a single identity or a list of identities, and is parsed using `server.oidc_authentication.principal_regex`.                                                                                                                                                                                                                                                                                                                                                                          |
| `server.oidc_authentication.principal_regex`       | Regex used to map the external identity key to a SQL user. If the identity key contains a list of identities instead of a single identity, each identity is evaluated serially until a match is found. The first match that is found is used, and the remaining identities are not evaluated. For example: `^([^@]+)@[^@]+$` matches any email address (defined as a string containing one `@` sign) and extracts a username from the string to the left of `@`, whereas `^(.+)$` maps the claim directly to a principal. The regex must contain exactly one capture group (set of parentheses); a regex with no capture groups or multiple capture groups will never find a match. |
| `server.oidc_authentication.autologin`             | A Boolean that enables or disables automatic login with SSO when the DB Console is loaded. If set to `false` (the default), the user will have to click **Log in with your OIDC provider** (unless overriden with `server.oidc_authentication.button_text`) before they're authenticated.                                                                                                                                                                                                                                                                                                                                                                                           |
| `server.oidc_authentication.button_text`           | Specifies the text to show on the button that launches authentication with the OIDC provider. This is set to `Log in with your OIDC provider` by default but can be customized to reference your specific provider by name.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `security.provisioning.oidc.enabled`               | Enables automatic user creation on first OIDC login. When enabled, also updates the `estimated_last_login_time` column in the `SHOW USERS` output for DB Console logins, allowing administrators to track when OIDC users last accessed the cluster. Defaults to `false`. Refer to [Step 3: Configure user creation](#step-3-configure-user-creation).                                                                                                                                                                                                                                                                                                                              |
| `server.oidc_authentication.authorization.enabled` | Enables automatic role synchronization based on OIDC group claims. See <InternalLink path="oidc-authorization">Configure OIDC Authorization for DB Console</InternalLink>. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

#### Update your cluster settings

Open a SQL shell to your cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach sql --certs-dir=certs --host={your cluster url}:26257
```

Specify the client ID and client secret you [obtained earlier](#step-1-provision-an-oidc-client):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.client_id = '\<client id\';
SET CLUSTER SETTING server.oidc_authentication.client_secret = '\<client secret\';
```

Specify the OAuth provider URL:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://accounts.google.com';
```

Specify the callback URL to redirect the user to the CockroachDB cluster. On a local cluster, this will be `https://localhost:8080/oidc/v1/callback`. For a Advanced cluster, replace `localhost` with your cluster's domain, which can be found by opening the DB Console from the **Tools** tab in your cluster's page in Cloud Console.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.redirect_url = 'https://{your cluster url}:8080/oidc/v1/callback';
```

Specify the following values to obtain an OIDC identifier that will be mapped to a SQL user.

Request the `openid` scope (required) and the `email` scope (needed when using email as the claim key):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.scopes = 'openid email';
```

Specify the `email` field from the ID Token:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.claim_json_key = 'email';
```

Use a regular expression that will extract a username from `email` that you can match to a SQL user. For example, `'^([^@]+)@cockroachlabs\.com$'` extracts the characters that precede `@cockroachlabs.com` in the email address.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)@cockroachlabs.com$';
```

### Step 3: Configure user creation

CockroachDB supports two approaches for the creation of users who will authenticate via OIDC:

#### Option 1: Automatic user provisioning (recommended)

With automatic user provisioning, CockroachDB creates users automatically during their first successful OIDC authentication. This eliminates the need for custom scripting to create user accounts.

To enable automatic user provisioning:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING security.provisioning.oidc.enabled = true;
```

<Note>
  Enabling automatic user provisioning may introduce latency during periods of concurrent OIDC authentication attempts from multiple browsers. This is because CockroachDB must check for user existence before provisioning, which generates read request load on the `system.users` table.
</Note>

When enabled:

* Users are created automatically upon successful OIDC authentication.
* All auto-provisioned users receive a `PROVISIONSRC` role option set to `oidc:{provider_url}`.
* The `estimated_last_login_time` column in the `SHOW USERS` output is updated for DB Console logins, enabling tracking of user activity for auditing and identifying dormant accounts.
* Auto-provisioned users cannot change their own passwords (managed via OIDC only).

<Note>
  Before you enable automatic user provisioning, it is recommended that you enable <InternalLink path="oidc-authorization">OIDC authorization</InternalLink>. This ensures that upon initial login, new CockroachDB users are members of the intended CockroachDB roles, with the privileges they confer, according to users' group memberships in the identity provider. Otherwise, functionality may be limited for a new user until your alternative process applies roles or privileges.

  If you choose to manage CockroachDB role memberships and privileges directly, you could script the required <InternalLink path="grant">`GRANT`</InternalLink> commands to be <InternalLink path="cockroach-sql#general">executed</InternalLink> as needed.
</Note>

#### Option 2: Manual/scripted user creation

You can manage users by directly creating them before OIDC authentication is used. This approach provides explicit control over user creation.

To create a single user:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE USER docs;
```

The SQL username you specify must match the identifier extracted by your `principal_regex` from the OIDC token. For example, if you configured `claim_json_key = 'email'` and `principal_regex = '^([^@]+)@cockroachlabs\.com$'`, a user with the email address `docs@cockroachlabs.com` will need the SQL username `docs`.

### Step 4: Enable OIDC authentication

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING server.oidc_authentication.enabled = true;
```

<Tip>
  You can enable the optional <InternalLink path="cluster-settings">`server.oidc_authentication.autologin` cluster setting</InternalLink> to automatically log in an authenticated user who visits the DB Console.
</Tip>

## Log in to a cluster's DB Console with SSO

From the user's perspective, once the cluster is properly configured to an identity provider, the sign-in flow is as follows:

1. A user opens the cluster's DB Console, and clicks the **Log in with your OIDC provider** button on the page.
2. The user is redirected to an external identity provider.
3. The user authenticates successfully with the provider, which completes the OAuth flow.
4. The user is redirected to the CockroachDB cluster.
5. CockroachDB creates a web session for the SQL user in a new browser tab.
6. In the original browser tab, the user is redirected to the DB Console <InternalLink path="ui-cluster-overview-page">**Cluster Overview**</InternalLink> page.

## Manage auto-provisioned users

When automatic user provisioning is enabled, you can identify and manage auto-provisioned users as follows:

### View provisioned users

Auto-provisioned users can be identified by their `PROVISIONSRC` role option:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
-- View all auto-provisioned users (users with PROVISIONSRC role option)
SELECT * FROM [SHOW USERS] AS u
WHERE EXISTS (
  SELECT 1 FROM unnest(u.options) AS opt
  WHERE opt LIKE 'PROVISIONSRC=oidc:%'
);
```

```
  username |                     options                     | member_of    |   estimated_last_login_time
-----------+-------------------------------------------------+--------------+--------------------------------
  alice    | {PROVISIONSRC=oidc:https://accounts.google.com} | {developers} | 2025-08-04 19:18:00.201402+00
  bob      | {PROVISIONSRC=oidc:https://accounts.google.com} | {analysts}   | 2025-08-03 14:22:15.102938+00
(2 rows)
```

Users provisioned via OIDC will have `PROVISIONSRC=oidc:{provider_url}` in their options column.

### Last-login tracking for usage and dormancy

The `estimated_last_login_time` column in the [`SHOW USERS` output](#view-provisioned-users) tracks when users last authenticated. This can help identify dormant accounts that may need review or removal.

<Note>
  `estimated_last_login_time` is computed on a best-effort basis and may not capture every login event due to asynchronous updates.
</Note>

To identify potentially dormant auto-provisioned users:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SELECT u.username, u.estimated_last_login_time
FROM [SHOW USERS] AS u
WHERE EXISTS (
  SELECT 1 FROM unnest(u.options) AS opt
  WHERE opt LIKE 'PROVISIONSRC=oidc:%'
) AND (
  u.estimated_last_login_time IS NULL OR
  u.estimated_last_login_time < NOW() - INTERVAL '90 days'
)
ORDER BY u.estimated_last_login_time DESC NULLS LAST;
```

### Clean up users removed from the identity provider

Auto-provisioned users who have been removed or deactivated in your identity provider will not be automatically removed from CockroachDB. To identify and clean up these orphaned accounts:

#### Step 1: Export auto-provisioned users from CockroachDB

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
-- Export list of auto-provisioned usernames for comparison with your IdP
SELECT u.username FROM [SHOW USERS] AS u
WHERE EXISTS (
  SELECT 1 FROM unnest(u.options) AS opt
  WHERE opt LIKE 'PROVISIONSRC=oidc:%'
);
```

#### Step 2: Cross-reference with your identity provider

Use your organization's identity management tools to verify which of these users still exist in your IdP. The specific method depends on your identity provider (Okta, Google Workspace, Azure AD, etc.).

#### Step 3: Remove orphaned users

Before dropping users confirmed to no longer exist in your identity provider, check for any privileges that were granted directly to the user:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
-- Check for direct grants to the user (privileges inherited through roles won't block DROP USER)
SHOW GRANTS FOR username;
```

If any direct grants exist, revoke them before dropping the user. For users confirmed to no longer exist in your identity provider:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
-- Remove users that no longer exist in the identity provider
DROP USER username1, username2, username3;
```

<Note>
  Users cannot be dropped if they have direct privilege grants or own database objects. For complete requirements, refer to <InternalLink path="drop-user">`DROP USER`</InternalLink>. When using both automatic user provisioning and OIDC authorization, consider granting privileges primarily through roles (mapped to IdP groups) rather than directly to users to simplify cleanup operations.
</Note>

### Restrictions on auto-provisioned users

Users created through automatic provisioning have specific restrictions:

* **Password changes**: Auto-provisioned users cannot change their own passwords using `ALTER USER`, even if the cluster setting `sql.auth.change_own_password.enabled` is true.
* **PROVISIONSRC modification**: The `PROVISIONSRC` role option cannot be modified or removed once set.
* **Authentication method**: These users must authenticate through OIDC; password-based authentication is not available.

Attempting to change the password of an auto-provisioned user will result in an error:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER USER provisioned_user WITH PASSWORD 'newpassword';
```

```
ERROR: cannot alter PASSWORD/PROVISIONSRC option for provisioned user provisioned_user
```

## Configure role-based access control

Once OIDC authentication is configured, you can optionally enable automatic role synchronization to automatically grant and revoke CockroachDB roles based on group memberships from your identity provider.

For detailed instructions, refer to <InternalLink path="oidc-authorization">Configure OIDC Authorization for DB Console</InternalLink>.

## See also

* <InternalLink path="ui-overview">DB Console Overview</InternalLink>
* <InternalLink path="sso-sql">Cluster Single Sign-on (SSO) using JSON web tokens (JWTs)</InternalLink>
* <InternalLink path="oidc-authorization">Configure OIDC Authorization for DB Console</InternalLink>
* <InternalLink path="jwt-authorization">JWT Authorization</InternalLink>
* <InternalLink path="ldap-authorization">LDAP Authorization</InternalLink>