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

On this page Carat arrow pointing down

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).

Note:

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

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 Single Sign-On (SSO) for CockroachDB Cloud organizations.

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.

    icon/buttons/copy
    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.

    icon/buttons/copy
    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:

icon/buttons/copy
 `ccloud cluster user create {cluster name} {SSO SQL username}`

What's Next?


Yes No
On this page

Yes No