We recommend that CockroachDB Cloud Console users log in with Single Sign-On (SSO), 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 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.
Refer to Authenticating to CockroachDB Cloud for an overview of authentication in CockroachDB Cloud, both at the level of the organization and at the cluster.
Provision a PKI hierarchy for SQL authentication in your cluster
There are many ways to create, manage, and distribute digital security certificates. Cockroach Labs recommends using a secure secrets server such as HashiCorp Vault, which can be used to securely generate certificates without revealing the CA private key.
Alternatively, you can generate certificates using CockroachDB's cockroach cert command or with OpenSSL. However, generating certificates this way and manually handling cryptographic material comes with considerable additional risk and room for error. PKI cryptographic material related to your CockroachDB Cloud organizations, particularly in any production systems, should be handled according to a considered policy appropriate to your security goals.
Initialize your Vault workstation
Install Vault on your workstation. Your workstation must be secure to ensure the security of the PKI hierarchy you are establishing. Consider using a dedicated secure jumpbox, as described in PKI Strategy.
Obtain the required parameters to target and authenticate to Vault.
Option 1: If using a development Vault server (suitable only for tutorial/testing purposes), start the Vault development server and obtain your admin token locally on your CA admin jumpbox by running vault server --dev.
Option 2: If using HashiCorp Cloud Platform (HCP):
Go to the HCP console, choose Vault from the Services menu and then select your cluster.
Find the Public Cluster URL for your Vault cluster. This will be set as the VAULT_ADDR environment variable, in the following step.
Generate an admin token by clicking Generate token. This will be set as the VAULT_TOKEN environment variable, in the following step.
Option 3: If using a Vault deployment internal to your organization, contact your Vault administrator for a token and the appropriate endpoint.
Initialize your shell for Vault.
export VAULT_ADDR=# your Vault cluster's Public URLexport VAULT_NAMESPACE="admin"
Authenticate with your admin token.
vault login
Create the certificate authority (CA) certificate
This CA certificate will be used to configure your cluster's Trust Store. Any client certificate signed by the CA identified by this certificate will be trusted and can authenticate to your cluster.
Create a PKI secrets engine to serve as your client CA.
vault secrets enable-path=cockroach_client_ca pki
Success! Enabled the pki secrets engine at: cockroach_client_ca/
Generate a root credential pair for the CA. Certificates created with this CA/secrets engine will be signed with the private key generated here and held within Vault; this key cannot be exported, safeguarding it from being leaked and used to issue fraudulent certificates. The CA public certificate is downloaded in the resulting JSON payload.
Create a JSON file that includes your certificate as the value for the x509_pem_cert key. You will use this JSON file to upload the certificate to CockroachDB Cloud. In this example, replace the certificate with the contents of your certificate.
Create a PKI role and issue credentials for the client
You can authenticate to a cluster using the private key and public certificate previously signed by the CA as long as the cluster's trust store includes the corresponding CA.
Ensure that the key file is owned by and readable only by the current user. CockroachDB will reject requests to authenticate using keys with overly-permissive permissions.
Upload a certificate authority (CA) certificate for a CockroachDB Advanced cluster
Add a CA certificate to your cluster's trust store for client authentication. Client certificates signed using the private key corresponding to this certificate will be accepted by your cluster for certificate-based client authentication.
The Cluster Admin or Organization Admin Organization role is required to manage the CA certificate for a CockroachDB Advanced cluster.
Submit the asynchronous request, supplying your cluster ID, API key, and the path to the certificate JSON with your CA certificate, as described in Create the certificate authority (CA) certificate.
A 200 successful response code indicates that the asynchronous request was successfully submitted, but does not guarantee that the operation (configuring the CA certificate) successfully completed. You must confirm success with a follow-up GET request, as described in the next step.
curl --request POST \--url${COCKROACH_SERVER}/api/v1/clusters/${CLUSTER_ID}/client-ca-cert \--header"Authorization: Bearer ${API_KEY}"\--header'content-type: application/json'\--data"@cockroach_client_ca_cert.json"
200 OK
Confirm success of the operation with the following GET request.
curl --request GET \--url${COCKROACH_SERVER}/api/v1/clusters/${CLUSTER_ID}/client-ca-cert \--header"Authorization: Bearer ${API_KEY}"
PENDING indicates that the operation is still in process.
{
"status": "PENDING",
"x509_pem_cert": ""
}
IS_SET indicates that the operation completed successfully, confirming the configured public CA cert.
Clients must be provisioned with client certificates signed by the cluster's CA prior to the update, or their new connections will be blocked.
This section shows how to replace the CA certificate used by your cluster for certificate-based client authentication. To roll out a new CA certificate gradually instead of following this procedure directly, CockroachDB supports the ability to include multiple CA certificates for a cluster by concatenating them in PEM format. This allows clients to connect as long as the client certificate is signed by either the old CA certificate or the new one. PEM format requires a blank line in between certificates.
Tip:
The Cluster Admin or Organization Admin Organization role is required to manage the CA certificate for a CockroachDB Advanced cluster.
Submit the asynchronous request, supplying your cluster ID, API key, and the path to the certificate JSON with your CA certificate, as described in Create the certificate authority (CA) certificate.
A 200 successful response code indicates that the asynchronous request was successfully submitted, but does not guarantee that the operation (configuring the CA certificate) successfully completed. You must confirm success with a follow-up GET request, as described in the next step.
Delete the certificate authority (CA) certificate for a cluster
This section shows how to remove the configured CA certificate from the cluster.
Warning:
After this operation is performed, clients can no longer authenticate with certificates signed by this CA certificate.
Tip:
The Cluster Admin or Organization Admin Organization role is required to manage the CA certificate for a CockroachDB Advanced cluster.
Submit the asynchronous DELETE request, supplying your cluster ID, API key, and the path to the certificate JSON with your CA certificate, as described in Create the certificate authority (CA) certificate.
A 200 successful response code indicates that the asynchronous request was successfully submitted, but does not guarantee that the operation (configuring the CA certificate) successfully completed. You must confirm success with a follow-up GET request, as described in the next step.
From your cluster's overview page, https://cockroachlabs.cloud/cluster/{ your cluster ID }, click the Connect button.
Copy the command listed under Download CA Cert and run it locally to download the required public certificate, which your client will use to verify the identity of the cluster.
Obtain your choice of connection string or CLI connection command for your cluster from the UI. This connection string is designed for password authentication and must be modified.
Remove the placeholder password from the connection string.
Construct the full connection string by providing the paths to sslrootcert (the cluster's public CA certificate), sslcert (the client's public certificate, which must be signed by the CA specified in sslrootcert), and sslkey (the client's private key).