Skip to main content
Cluster SSO allows 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 convenience of being able to choose from a variety of SSO identity providers, including CockroachDB Cloud, Google, Azure, GitHub, or your own self-hosted OIDC. This page describes the procedure for accessing a CockroachDB Cloud cluster using the CockroachDB Cloud console as identity provider. To authenticate using JWT tokens from your external IdP, refer to .
This authentication method works for human users but not for service accounts, since only humans may have CockroachDB Cloud Console identities. To authenticate service accounts using JWT tokens from an external IdP, refer to .Note that the topic of this page is SQL access to a specific CockroachDB Cluster, not access to a CockroachDB Cloud organization. For the latter, see .

​
Before you begin

For more details and examples, refer to SSO to CockroachDB clusters using JWT in the CockroachDB blog.
  • You must be a member of a CockroachDB Cloud organization, and you must have access to an existing cluster or the permission to create a new cluster. For help setting up an organization and cluster, refer to .
  • To authenticate to a specific cluster using SSO, a CockroachDB Cloud user must have a corresponding SQL user already on that cluster. CockroachDB Cloud generates a SSO SQL username for each console, corresponding to the user’s email by the convention sso_{email_name}, where email_name is everything up to the @ in an email address, for example the SQL user sso_docs would result from docs@cockroachlabs.com. ccloud will prompt you to make this user if it does not already exist, in which case an admin must create it manually.
  • must be installed on your local system.

​
Sign in with Cluster SSO

  1. Authenticate ccloud to your CockroachDB Cloud organization. When you run the following command, your workstation’s default browser opens the CockroachDB Cloud login page for your organization.
  2. You may then use the ccloud utility to authenticate to your CockroachDB Cloud cluster, allowing you to access the SQL interface. Your browser will open again as ccloud requests an access token, although will not need to log in again if you are already logged in.

​
Troubleshooting

If you get an error that the SQL user is missing, you may need to create it manually. The SQL user’s username must match the CockroachDB Cloud identity’s email address, according to the following convention: email: {name}@emaildomain.com SQL username: sso_{name} For example, a user named docs_rule@cockroachlabs.com would need a SQL username of sso_docs_rule You can with:

​
What’s Next?