Cluster Single Sign-on (SSO) using the Cloud Console

On this page

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 Cluster Single Sign-on (SSO) using JSON web tokens (JWT).

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 Quickstart with CockroachDB.
• To authenticate to a specific cluster using SSO, a CockroachDB Cloud user must have a corresponding SQL user already created 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.
• ccloud, the CockroachDB Cloud CLI 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.

   ccloud auth login --org {your organization label}
   # when running ccloud on a remote host, add the following:
   # --no-redirect
   

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.

   ccloud cluster sql --sso {your cluster name}
   # when running ccloud on a remote host, add the following:
   # --no-redirect
   

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 create a user with:

 `ccloud cluster user create {cluster name} {SSO SQL username}`

What's Next?

• Read about SSO to CockroachDB clusters using JWT in the CockroachDB blog.
• Learn more about CockroachDB Cloud Organization SSO.

Was this helpful?