Single Sign-on (SSO) for DB Console

CockroachDB clusters allow users to authenticate with single sign-on (SSO) to the and the SQL interface:

• Cluster single sign-on (SSO): Enables users to access the SQL interface of a CockroachDB cluster (whether provisioned on CockroachDB Cloud or self-hosted) with the full security of single sign-on (SSO), and the choice of a variety of cloud-based or customer-managed identity providers (IdPs).
• Single sign-on (SSO) for DB Console: Allows a CockroachDB user to access the in a secure cluster via an OpenID Connect (OIDC) client and an external identity provider. When SSO is configured and enabled, the will display an OAuth login button in addition to the password access option.

This page describes how to set up Single Sign-on to the DB Console, which includes the following steps:

• The login flow for users, once a cluster is SSO-enabled.
• Provision an OIDC client for CockroachDB Cluster SSO authentication using GCP.
• Configure a CockroachDB Cluster for OIDC SSO authentication to the DB Console.

If you would also like to enable SSO authentication for SQL clients, you must complete additional configuration on the page. This SSO implementation uses the authorization code grant type to authenticate a user. Prerequisites:

• IdP: You must have access to an OAuth 2.0 identity provider and client. The process of provisioning one with Google Cloud Platform is described on this page in the Provision an OAuth client using Google Cloud Platform (GCP) section.
• CockroachDB cluster: you must have access to one of the following:
  • A self-hosted cluster enabled with a valid .
  • A .

​

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 on the Log in with your OIDC provider button that renders 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 .

​

Provision an OAuth client using Google Cloud Platform (GCP)

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 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 a Advanced cluster, find the domain by opening the DB Console from your cluster’s Tools tab in DB Console.

​

Configure your cluster to use an OIDC client and provider

Prerequisites: You must have the ability to update your cluster settings, which you can achieve in several ways. Refer to the Required Privileges section on the page.

​

Cluster Settings

You must configure the in the following table to enable SSO authentication to the DB Console. Refer to the Update your cluster settings section to configure your cluster settings.

​

Update your cluster settings

1. Open a SQL shell to your cluster:
   cockroach sql --certs-dir=certs --host={your cluster url}:26257
   
2. Specify the client ID and client secret you obtained earlier:
   SET CLUSTER SETTING server.oidc_authentication.client_id = '\<client id\';
   SET CLUSTER SETTING server.oidc_authentication.client_secret = '\<client secret\';
   
3. Specify the OAuth provider URL:
   SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://accounts.google.com';
   
4. 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.
   SET CLUSTER SETTING server.oidc_authentication.redirect_url = 'https://{your cluster url}:8080/oidc/v1/callback';
   
5. Specify the following values to obtain an OIDC identifier that will be mapped to a SQL user. Request the openid and email scopes from the Access Token:
   SET CLUSTER SETTING server.oidc_authentication.scopes = 'openid email';
   
   Specify the email field from the ID Token:
   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.
   SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)@cockroachlabs.com$';
   
6. that will log into the DB Console. The SQL username you specify must match the identifier obtained in the previous step. For example, a user with the email address docs@cockroachlabs.com will need the SQL username docs:
   CREATE USER docs;
   
7. Finally, enable OIDC authentication:
   SET CLUSTER SETTING server.oidc_authentication.enabled = true;
   

​

Configure role-based access control

New in v25.4: Once OIDC authentication is configured, you can optionally enable automatic role synchronization based on group memberships from your identity provider. This simplifies access control by automatically granting and revoking CockroachDB roles based on IdP groups. For detailed instructions on configuring OIDC authorization, refer to .

​

See also