Authentication in CockroachDB Cloud

CockroachDB Cloud supports authentication at two levels: organization-level access for administrative tasks and cluster-level access for SQL operations.

Authentication Overview

Authentication in CockroachDB Cloud works at different levels:

Organization Level: Access to Cloud Console, API, and ccloud CLI
Cluster Level: SQL user authentication for database operations

Organization Authentication

Authenticate to manage your CockroachDB Cloud organization through three interfaces.

Cloud Console Authentication

Access the Cloud Console at cockroachlabs.cloud. Authentication Methods:

Email and Password
Single Sign-On (SSO)
GitHub

Standard Login:

Navigate to Login

Go to cockroachlabs.cloud

Enter Credentials

Enter your email address
Enter your password
Click Sign In

Multi-Factor Authentication

If MFA is enabled, enter your verification code

`ccloud` CLI Authentication

Authenticate the ccloud command-line tool to your organization.

Install ccloud

Download and install the ccloud CLI:

# macOS
brew install cockroachdb/tap/ccloud

# Linux
curl -L https://binaries.cockroachlabs.com/ccloud-latest.linux-amd64.tar.gz | tar -xz

Authenticate

Run the login command:

ccloud auth login --org <organization-name>

This opens your browser for authentication.

Complete Login

Authenticate in your browser
Return to the terminal
ccloud is now authenticated

Headless Authentication: For servers without a browser:

ccloud auth login --no-redirect --org <organization-name>

Copy the provided URL, authenticate on another machine, and enter the authorization code.

Cloud API Authentication

Service accounts authenticate to the Cloud API using API keys.

Create Service Account

Go to Access Management in Cloud Console
Click Service Accounts tab
Click Create Service Account
Name the account and assign roles

Generate API Key

Select the service account
Click Create API Key
Copy the API key (shown only once)
Store securely

Use API Key

Include the API key in API requests:

curl -X GET \
  https://cockroachlabs.cloud/api/v1/clusters \
  -H "Authorization: Bearer {api-key}"

SQL User Authentication

Authenticate to CockroachDB clusters to execute SQL statements.

Create SQL Users

Navigate to SQL Users

Select your cluster
Click SQL Users in the navigation

Add User

Click Add User
Enter username (lowercase, alphanumeric, hyphens)
Generate or enter a strong password
Click Create

Save Credentials

Save the password securely - it won’t be shown again

Password Requirements:

Minimum 12 characters
Include uppercase and lowercase letters
Include numbers and special characters
Avoid common passwords or patterns

SQL Authentication Methods

Username and Password
Client Certificates
SSO for SQL

Standard SQL Authentication:Connect using username and password in the connection string:

cockroach sql --url "postgresql://myuser:[email protected]:26257/defaultdb?sslmode=verify-full"

Or provide credentials interactively:

cockroach sql --url "postgresql://cluster-name.cloud.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full" --user myuser
Password: [enter password]

PKI Certificate Authentication (Advanced only):Use client certificates for passwordless authentication:

Generate Certificate

Create a client certificate signed by the cluster’s CA:

cockroach cert create-client {username} \
  --certs-dir=certs \
  --ca-key=ca.key

Connect with Certificate

Use certificate files in connection:

cockroach sql --url "postgresql://[email protected]:26257/defaultdb?sslcert=client.myuser.crt&sslkey=client.myuser.key&sslrootcert=ca.crt&sslmode=verify-full"

Client certificate authentication is only available for CockroachDB Advanced clusters.

Cluster SSO (Advanced only):Authenticate to clusters using organization SSO credentials:

Create SSO SQL User

The SQL username must match the format sso_{email_prefix}:

-- For user [email protected]
CREATE USER sso_alice;
GRANT admin TO sso_alice;

Connect with SSO

Use the --sso flag:

ccloud cluster sql --sso {cluster-name}

Authenticate

Your browser opens for SSO authentication

Connection Security

CockroachDB Cloud enforces secure connections: SSL/TLS Requirements:

Connections must use TLS encryption
sslmode=verify-full required for production
CA certificate validates server identity

SSL Mode Settings:

Mode	Encryption	Verification	Use Case
`require`	Yes	No	Testing only (not recommended)
`verify-full`	Yes	Yes	Production (required)

Download CA Certificate: Get the cluster’s CA certificate from the Connect dialog:

mkdir -p ~/.postgresql
curl --create-dirs -o ~/.postgresql/root.crt \
  'https://cockroachlabs.cloud/clusters/{cluster-id}/cert'

Manage SQL Users

Perform common SQL user management tasks.

Reset Password

Only Organization Admins and Cluster Admins can reset passwords:

Access SQL Users

Navigate to cluster’s SQL Users page

Reset Password

Click the user’s action menu (•••)
Select Reset password
Generate or enter new password
Click Update

Distribute New Credentials

Securely share the new password with the user

Grant SQL Privileges

Control what SQL users can do:

-- Grant database access
GRANT ALL ON DATABASE mydb TO myuser;

-- Grant table access
GRANT SELECT, INSERT ON TABLE mytable TO myuser;

-- Grant admin privileges
GRANT admin TO myuser;

-- Create read-only user
CREATE USER readonly;
GRANT SELECT ON DATABASE mydb TO readonly;

Delete SQL User

Revoke Privileges

Remove the user’s privileges:

REVOKE ALL ON DATABASE mydb FROM myuser;

Drop User

Delete the user:

DROP USER myuser;

Or use the Cloud Console:

Go to SQL Users page
Click action menu for user
Select Delete user

Multi-Factor Authentication

Enable MFA for enhanced organization account security.

Access Account Settings

Click your profile icon > Account Settings

Enable MFA

Go to Security tab
Click Enable MFA
Scan QR code with authenticator app
Enter verification code
Save recovery codes

Future logins require:

Username and password
MFA verification code

Supported Authenticator Apps:

Google Authenticator
Microsoft Authenticator
Authy
1Password
Other TOTP-compatible apps

Configure Organization SSO

Organization Admins can configure SSO for all users.

Access SSO Settings

Go to Organization Settings
Click SSO tab

Configure Identity Provider

Select your IdP type (SAML 2.0)
Enter IdP metadata URL or upload metadata XML
Configure attribute mappings

Test SSO

Click Test SSO
Verify authentication flow
Check user attributes

Enable SSO

Toggle SSO Enabled
Optionally enforce SSO (disable password login)

SSO Benefits:

Centralized user management
Automated provisioning/deprovisioning
Enhanced security with IdP policies
Simplified user experience

Security Best Practices

Organization Authentication

Recommendations

Enable SSO: Centralize authentication
Require MFA: Add extra security layer
Use Service Accounts: For API access, not personal accounts
Rotate API Keys: Regularly update service account keys
Review Access: Audit user access quarterly

SQL User Security

Best Practices

Strong Passwords: Minimum 12 characters, complex
Least Privilege: Grant only necessary permissions
Separate Users: Different users for different applications
Regular Audits: Review user list and privileges
Use Certificates: For Advanced clusters when possible

Connection Security

Secure Connections

Always use TLS: Never disable SSL/TLS
Verify Server: Use sslmode=verify-full
Secure Credentials: Use environment variables, not hard-coded
Rotate Passwords: Change passwords regularly
Monitor Connections: Track unusual access patterns

Troubleshooting Authentication

Cannot Log into Cloud Console

Issue: Login fails or times out Solutions:

Verify email and password are correct
Check if SSO is enforced for your organization
Clear browser cache and cookies
Try different browser
Reset password if forgotten
Contact Organization Admin

SQL Connection Refused

Issue: Cannot connect to cluster Solutions:

Check IP allowlist includes your IP
Verify SQL username and password
Confirm sslmode=verify-full is set
Download CA certificate
Check network connectivity
Verify cluster is running

Certificate Verification Failed

Issue: SSL/TLS verification fails Solutions:

Download latest CA certificate
Verify certificate path in connection string
Check certificate hasn’t expired
Ensure sslmode=verify-full is used
Verify hostname matches certificate

API Authentication Failed

Issue: API key not working Solutions:

Verify API key is correct (no extra spaces)
Check service account hasn’t been deleted
Confirm service account has necessary roles
Regenerate API key if compromised
Check API key hasn’t been revoked

Next Steps

Authorization

Learn about roles and permissions

Connect to Cluster

Connect your applications

Network Security

Configure network authorization

Compliance

Security compliance and certifications

Getting Started

Cluster Management

Security

Billing & Plans

Authentication in CockroachDB Cloud

Authentication Overview

Organization Authentication

Cloud Console Authentication

`ccloud` CLI Authentication

Cloud API Authentication

SQL User Authentication

Create SQL Users

SQL Authentication Methods

Connection Security

Manage SQL Users

Reset Password

Grant SQL Privileges

Delete SQL User

Multi-Factor Authentication

Configure Organization SSO

Security Best Practices

Organization Authentication

Recommendations

SQL User Security

Best Practices

Connection Security

Secure Connections

Troubleshooting Authentication

Cannot Log into Cloud Console

SQL Connection Refused

Certificate Verification Failed

API Authentication Failed

Next Steps

Authorization

Connect to Cluster

Network Security

Compliance

Build docs developers (and LLMs) love

Getting Started

Cluster Management

Security

Billing & Plans

​Authentication Overview

​Organization Authentication

​Cloud Console Authentication

​ccloud CLI Authentication

​Cloud API Authentication

​SQL User Authentication

​Create SQL Users

​SQL Authentication Methods

​Connection Security

​Manage SQL Users

​Reset Password

​Grant SQL Privileges

​Delete SQL User

​Multi-Factor Authentication

​Configure Organization SSO

​Security Best Practices

​Organization Authentication

Recommendations

​SQL User Security

Best Practices

​Connection Security

Secure Connections

​Troubleshooting Authentication

​Cannot Log into Cloud Console

​SQL Connection Refused

​Certificate Verification Failed

​API Authentication Failed

​Next Steps

Authorization

Connect to Cluster

Network Security

Compliance

Build docs developers (and LLMs) love

Authentication Overview

Organization Authentication

Cloud Console Authentication

`ccloud` CLI Authentication

Cloud API Authentication

SQL User Authentication

Create SQL Users

SQL Authentication Methods

Connection Security

Manage SQL Users

Reset Password

Grant SQL Privileges

Delete SQL User

Multi-Factor Authentication

Configure Organization SSO

Security Best Practices

Organization Authentication

SQL User Security

Connection Security

Troubleshooting Authentication

Cannot Log into Cloud Console

SQL Connection Refused

Certificate Verification Failed

API Authentication Failed

Next Steps