Single sign-on (SSO) allows a CockroachDB user to access the DB Console in a secure cluster via an external identity provider. When SSO is configured and enabled, the DB Console login page will display an OAuth login button in addition to the password access option.
CockroachDB supports SSO via OpenID Connect (OIDC), an authentication layer built on top of OAuth 2.0.
SSO authentication is an Enterprise-only feature.
- An external OAuth 2.0 identity provider
This SSO implementation uses the authorization code grant type to authenticate a user.
- A user opens the DB Console and clicks on the OAuth login button.
- The user is redirected to an external identity provider.
- The user successfully authenticates with the provider, completing the OAuth flow.
- The user is redirected to the CockroachDB cluster via a callback URL.
- The authorization code in the callback query is exchanged for an ID Token.
- CockroachDB matches the ID Token to a registered SQL user.
- CockroachDB creates a web session for the SQL user.
- The user is redirected to the DB Console Cluster Overview.
The following OIDC cluster settings are used to configure and enable SSO.
|Cluster Setting||Example Value|
||'openid profile email'|
enabledis a Boolean that enables or disables SSO.
client_secretare generated by the external identity provider.
redirect_urlspecifies 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. The path must be appended with
provider_urlspecifies the OAuth issuer identifier. Ensure that the URL does not have a terminating
/. For more information, see the OIDC specification. Note that CockroachDB appends the required
/.well-known/openid-configurationby default. You do not need to include it.
scopesis a space-delimited list of the OAuth scopes being requested for an Access Token. The
openidscope must be included.
claim_json_keyis the key of the field to be extracted from the external identity provider's ID Token and mapped to a SQL user. This field is likely to be a standard claim such as
principal_regexis a regular expression applied to the field specified by
claim_json_key. It is used to extract an identifier that can be mapped to a SQL user. For example:
^([^@]+)@[^@]+$matches any email address (defined as a string containing one
@sign) and extracts a username from the string to the left of
^(.+)$maps the claim directly to a principal.
autologinis a Boolean. When
true, upon loading the DB Console login page, the browser will automatically initiate the OIDC authentication process by redirecting to
/oidc/v1/logininstead of waiting for the user to log in manually or click the OIDC login button.
Example (Google OAuth 2.0)
Open the Credentials page for your account at Google APIs.
Click + CREATE CREDENTIALS and select OAuth client ID. Specify a web application from the pulldown menu.
Note the client ID and client secret of the OAuth 2.0 client. You can find these in the dialog that appears after you create the client, or in the details view for the client:
Add the callback URL to the list of Authorized redirect URIs. On a local cluster, this will be
https://localhost:8080/oidc/v1/callback. You will later set
server.oidc_authentication.redirect_urlto the same value.
Open a SQL shell to the cluster on node 1:
$ cockroach sql --certs-dir=certs --host=localhost:26257
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\>';
Specify the OAuth issuer identifier:
> SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://accounts.google.com';
Specify the callback URL to redirect the user to the CockroachDB cluster:
> SET CLUSTER SETTING server.oidc_authentication.redirect_url = 'https://localhost:8080/oidc/v1/callback';
Specify the following values to obtain an OIDC identifier that will be mapped to a SQL user.
> SET CLUSTER SETTING server.oidc_authentication.scopes = 'openid email';
> SET CLUSTER SETTING server.oidc_authentication.claim_json_key = 'email';
Use a regular expression that will extract a username from
'^([^@]+)@cockroachlabs\.com$'extracts the characters that precede
@cockroachlabs.comin the email address.
> SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)@cockroachlabs.com$';
Create a SQL user 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
email@example.com need the SQL username
> CREATE USER maxroach;
Finally, enable OIDC authentication:
> SET CLUSTER SETTING server.oidc_authentication.enabled = true;
When the user accesses the DB Console, they will be able to log in with their Google account.
You can optionally enable the
server.oidc_authentication.autologin cluster setting to automatically log in an authenticated user who visits the DB Console.