> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication on CockroachDB Cloud

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Users may connect with CockroachDB Cloud at two levels, the organization and the cluster, both of which are covered in this page.

Refer to: <InternalLink version="cockroachcloud" path="authorization#overview-of-the-cockroachdb-cloud-authorization-model">Overview of the CockroachDB Cloud authorization model</InternalLink>.

## Overview of CockroachDB Cloud authentication

**Organization level** functions can be performed through three different interfaces, each with its own authentication flows:

* The [CockroachDB Cloud Console UI](https://cockroachlabs.cloud/) provides a user with an overview of their CockroachDB Cloud account, and offers functionality for administering an organization and the clusters within it.

  Refer to: [Console authentication](#console-ui-authentication)
* The `ccloud` utility allows users to execute cloud functions from the command line.

  Refer to: [`ccloud` authentication](#ccloud-authentication)
* The CockroachDB Cloud API allows service accounts to perform many organization and cluster administration functions.

  Refer to: [Cloud API authentication](#cloud-api-authentication)

**Cluster level functions**, i.e. SQL statements, are executed by SQL clients.

Refer to: [SQL client authentication](#sql-client-authentication)

## Console UI authentication

You may log in to the [CockroachDB Cloud Console](https://cockroachlabs.cloud/) with a username and password, or by using <InternalLink path="cloud-org-sso">Single Sign-on (SSO) for CockroachDB Cloud</InternalLink>.

<Note>
  We recommend that CockroachDB Cloud Console users log in with <InternalLink path="cloud-org-sso">Single Sign-On (SSO)</InternalLink>, optionally with two-factor authentication (2FA) enabled for the SSO provider. This prevents potential attackers from using stolen credentials to access or tamper with your critical data.

  CockroachDB Cloud <InternalLink path="cloud-org-sso#basic-sso">Basic SSO</InternalLink> supports SSO with GitHub, Google, and Microsoft. <InternalLink path="cloud-org-sso#cloud-organization-sso">Cloud Organization SSO</InternalLink> provides additional configuration and flexibility, and includes support for OIDC or SAML protocols, autoprovisioning, and limiting the email domains that can use a given authentication method.

  Visit your CockroachDB Cloud Console's [account settings page](https://cockroachlabs.cloud/account/profile) and switch to SSO to improve the security of your cluster.
</Note>

## `ccloud` authentication

The `ccloud` utility offers Organization users a way to script many functions that must otherwise be performed in the console interface.

For more information, refer to: <InternalLink path="ccloud-get-started">Get Started with the `ccloud` CLI</InternalLink>

To authenticate `ccloud` to a particular organization, run the following command. `ccloud` will open up your machine's default browser, attempt to authenticate to the console and export a temporary auth token.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ccloud auth login --org <organization label>
```

Refer to: <InternalLink path="ccloud-get-started#log-in-to-cockroachdb-cloud-using-ccloud-auth">Log in to CockroachDB Cloud using `ccloud auth`</InternalLink>

## Cloud API authentication

The <InternalLink path="cloud-api">Cloud API</InternalLink> allows automated execution of organization functions. Unlike `ccloud` and the console UI, however, only service accounts can authenticate to the API.

Service accounts authenticate to the API using API keys, which are provisioned through the console UI.

Refer to: <InternalLink path="managing-access#api-access">Managing Service Accounts: API access</InternalLink>

## SQL client authentication

To execute SQL statements or perform database administration functions on a cluster, you must connect to the cluster with a SQL client. CockroachDB clients include the CockroachDB CLI, and numerous <InternalLink version="stable" path="install-client-drivers">drivers and object-relational mapping (ORM) tools</InternalLink>.

### The connection string

You can obtain a connection string or CLI command for your cluster, to use with your choice of SQL client, by visiting your cluster's overview page, and clicking **Connect** button, and following the instructions.

`https://cockroachlabs.cloud/cluster/< your cluster UUID >/`

Clients can authenticate in two ways. Your connection string must be modified depending on which you are using:

* [Username and password](#username-and-password)
* [PKI security certificate](#pki-security-certificate)

Note that the <InternalLink version="stable" path="security-reference/transport-layer-security#certificates-signing-trust-and-authority">TLS public root certificate authority (CA) certificate of the cluster</InternalLink> is also required for authenticating the cluster server against the SQL client. This certificate can be downloaded by following the instructions in the **Connect** UI.

### Username and password

A user can authenticate to a cluster by providing their username and password in the connection string.

[The connection string](#the-connection-string) UI will indicate how to modify the string to user credentials.

For information on managing SQL user credentials, including provisioning passwords, refer to <InternalLink path="managing-access#manage-sql-users-on-a-cluster">Manage SQL users on a cluster</InternalLink>.

### PKI security certificate

SQL clients may authenticate to CockroachDB Advanced clusters using PKI security certificates.

Refer to <InternalLink version="stable" path="security-reference/transport-layer-security">Transport Layer Security (TLS) and Public Key Infrastructure (PKI)</InternalLink> for an overview of PKI certificate authentication in general and its use in CockroachDB.

Refer to <InternalLink path="client-certs-advanced">Certificate Authentication for SQL Clients in CockroachDB Advanced Clusters</InternalLink> for procedural information on administering and using client certificate authentication.

## Node identity verification

The <InternalLink path="connect-to-your-cluster">connection string</InternalLink> generated to connect to your application uses the `verify-full` [SSL mode](#ssl-mode-settings) by default to verify a node’s identity. This mode encrypts the data in-flight as well as verifies the identity of the CockroachDB node, thus ensuring a secure connection to your cluster. Using this mode prevents MITM (Machine in the Middle) attacks, impersonation attacks, and eavesdropping.

To connect securely to your cluster using the `verify-full` mode:

1. Download the CA certificate and place it in the `certs` directory. The Certificate Authority (CA) certificate is the file that the client uses to verify the identity of the CockroachDB node.
2. When connecting to the cluster, specify the path to the `certs` directory in the connection string. See <InternalLink path="connect-to-your-cluster">Connect to your cluster</InternalLink> for more details.

You can also use the `require` SSL mode, although we do not recommend using it since it can make the cluster susceptible to MITM and impersonation attacks. For more information, see the "Protection Provided in Different Modes" section in PostgreSQL's [SSL Support](https://www.postgresql.org/docs/9.4/libpq-ssl) document.

For more information about creating SQL users and passwords, see <InternalLink path="managing-access">User Authorization</InternalLink>.

## SSL mode settings

The table below lists the `sslmode` settings you can use to <InternalLink path="connect-to-your-cluster">connect to your cluster</InternalLink> and their associated security risks. Other settings are not recommended.

| `sslmode`     | Eavesdropping protection | MITM protection | Description                                                                                                                                                                                         |
| ------------- | ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `require`     | Yes                      | No              | Force a secure connection. An error occurs if the secure connection cannot be established. This is less secure than using a CA certificate and is only recommended for testing or unimportant data. |
| `verify-full` | Yes                      | Yes             | Force a secure connection, verify that the server certificate is signed by a known CA, and verify that the server address matches that specified in the certificate.                                |

## See also

* <InternalLink path="cloud-org-sso">Cloud Organization SSO</InternalLink>
* <InternalLink path="configure-cloud-org-sso">Configure Cloud Organization SSO</InternalLink>
* <InternalLink version="stable" path="connection-parameters">Client Connection Parameters</InternalLink>
* <InternalLink path="connect-to-your-cluster">Connect to Your CockroachDB Standard Cluster</InternalLink>