Users may connect with CockroachDB Cloud in two ways:
- The CockroachDB Cloud Console provides an overview of your CockroachDB Cloud account, and offers functionality for administrating or connecting to clusters.
- SQL clients, including the CockroachDB CLI client and the various supported drivers and ORMs, connect directly to CockroachDB clusters using the CockroachDB SQL interface.
CockroachDB Cloud authentication
You may log in to the CockroachDB Cloud Console with a username and password, or by using Single Sign-on (SSO) for CockroachDB Cloud.
CockroachDB Cloud Basic SSO supports SSO with GitHub, Google, and Microsoft. Cloud Organization SSO 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 and switch to SSO to improve the security of your cluster.
If you have not done so, create your own free CockroachDB Serverless cluster.
Connecting SQL clients
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 drivers and object-relational mapping (ORM) tools.
To connect any SQL client to a CockroachDB Cloud cluster, you must have a username/password combination and the TLS public root certificate authority (CA) certificate of the cluster.
To connect any SQL client to a CockroachDB Cloud cluster, you must have a username/password combination, and the TLS public root certificate authority (CA) certificate of the cluster.
Node identity verification
The connection string generated to connect to your application uses the verify-full SSL mode 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:
- Download the CA certificate and place it in the
certsdirectory. The Certificate Authority (CA) certificate is the file that the client uses to verify the identity of the CockroachDB node. - When connecting to the cluster, specify the path to the
certsdirectory in the connection string. See Connect to your cluster 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 document.
Client identity verification
CockroachDB Cloud uses password authentication for verifying a client’s identity. If no password has been set up for a user, password authentication will always fail for that user and you won’t be able to connect to the cluster.
For more information about creating SQL users and passwords, see User Authorization.
SSL mode settings
The table below lists the sslmode settings you can use to connect to your cluster 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
- Cloud Organization SSO
- Configure Cloud Organization SSO
- Client Connection Parameters
- Connect to Your CockroachDB Dedicated Cluster
Was this helpful?
