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

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.

       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.