Security¶

CockroachDB is designed as a security-first distributed database. Every inter-node communication channel is encrypted by default using mutual TLS, and the system provides layered controls spanning authentication, authorisation, encryption at rest, and audit logging. Several advanced features (SSO, encryption at rest, audit logging) require an Enterprise licence.

Authentication¶

CockroachDB supports multiple authentication methods for SQL clients. All methods are configured at the cluster level and can be restricted per user.

TLS Certificate Authentication¶

Certificate-based authentication is the recommended method for production deployments. CockroachDB uses a PKI model where:

A cluster CA signs node certificates and client certificates.
Each node presents a node certificate to other nodes (mutual TLS for inter-node traffic).
Each SQL client presents a user certificate mapped to a CockroachDB SQL username (extracted from the certificate CN or SAN).

# Generate a client certificate for user 'app_user'
cockroach cert create-client app_user \
    --certs-dir=certs \
    --ca-key=my-safe-directory/ca.key

Connection string with client certificate:

cockroach sql \
    --certs-dir=certs \
    --user=app_user \
    --host=node1.example.com:26257

Password Authentication¶

CockroachDB supports username/password authentication using SCRAM-SHA-256 (default in v22.2+). Passwords are hashed and stored in the system table system.users. Password authentication is common for CockroachDB Cloud deployments.

CREATE USER app_user WITH PASSWORD 'secure_password';

Password Auth Requires TLS

Password authentication should only be used over TLS-encrypted connections. CockroachDB rejects password auth on unencrypted connections by default (insecure mode bypasses this but must never be used in production).

GSSAPI / Kerberos Authentication (Enterprise)¶

CockroachDB Enterprise supports GSSAPI authentication, allowing SQL clients to authenticate using Kerberos tickets issued by an Active Directory or MIT Kerberos KDC. This is configured via the cluster setting server.user_login.cert_email_domain and HBA-style rules.

Cluster Single Sign-On (Enterprise)¶

CockroachDB Enterprise supports JWT-based cluster SSO. Users authenticate via an external Identity Provider (IdP) that issues a JSON Web Token. The CockroachDB cluster validates the JWT signature and maps the token subject to a SQL user.

DB Console SSO (Enterprise)¶

The web-based DB Console supports OpenID Connect (OIDC) SSO, allowing administrators to log in using corporate IdPs such as Okta, Azure AD, or Google Workspace.

Authorization (RBAC)¶

CockroachDB implements role-based access control (RBAC) modelled after PostgreSQL's privilege system.

Users and Roles¶

Users -- SQL identities that can log in. Every connection is associated with a user.
Roles -- named groups of privileges. Users can be granted membership in roles, inheriting their privileges.
The admin role has full cluster access. The root user is a member of admin by default.

-- Create a role with limited privileges
CREATE ROLE read_only;
GRANT SELECT ON DATABASE appdb TO read_only;

-- Create a user and assign the role
CREATE USER analyst WITH PASSWORD 'analyst_pass';
GRANT read_only TO analyst;

Privilege Hierarchy¶

Privileges can be granted at multiple levels:

Level	Grantable Privileges
System	`CREATEROLE`, `CREATELOGIN`, `CREATEDB`, `CONTROLJOB`, `VIEWACTIVITY`, `MODIFYCLUSTERSETTING`
Database	`ALL`, `CREATE`, `DROP`, `CONNECT`, `EXTERNALCONNECTION`
Table	`ALL`, `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`
Schema	`ALL`, `CREATE`, `DROP`, `USAGE`

Grant and Revoke¶

GRANT SELECT, INSERT ON TABLE orders TO app_writer;
REVOKE DELETE ON TABLE orders FROM app_writer;

Default Privileges

Use ALTER DEFAULT PRIVILEGES to set privileges that automatically apply to future objects created in a schema or database.

Encryption at Rest (Enterprise)¶

CockroachDB Enterprise provides transparent data encryption at the storage layer using AES in counter mode (AES-CTR). All keys sizes (128, 192, 256 bit) are supported.

How It Works¶

Encryption is applied at the Pebble storage engine level, before data is written to disk.
All files managed by Pebble (SSTables, WAL files, manifest files) are encrypted.
Keys are managed via a key registry. CockroachDB supports:
- Plaintext keys -- stored in a local file (suitable for development).
- KMS-backed keys -- keys stored and rotated via AWS KMS or Google Cloud KMS.

Enabling Encryption¶

# Start a node with encryption enabled using a KMS
cockroach start \
    --enterprise-encryption=path=/cockroach/cockroach-data,key=aws-kms://arn:aws:kms:...,old-key=plain \
    --certs-dir=certs \
    --join=node1:26257,node2:26257,node3:26257

Zone-Aware Encryption¶

Encryption settings can be applied per zone configuration, allowing different encryption keys or policies for different databases, tables, or partitions:

ALTER DATABASE sensitive_data CONFIGURE ZONE USING
    enterprise_key = 'aws-kms://arn:aws:kms:us-east-1:123456789012:key/abc-123';

Encryption in Transit¶

All network communication in CockroachDB is encrypted by default using TLS:

Channel	TLS Version	Authentication
Inter-node (node-to-node)	TLS 1.3	Mutual TLS (mTLS) -- both sides present certificates
Client-to-node (SQL)	TLS 1.2 / 1.3	Server certificate + optional client certificate
DB Console (HTTP)	TLS 1.2 / 1.3	Server certificate; user auth via password or SSO
Admin RPC	TLS 1.3	Mutual TLS

OCSP Certificate Revocation (Enterprise)¶

CockroachDB Enterprise supports OCSP (Online Certificate Status Protocol) to check whether client or node certificates have been revoked. This adds a real-time revocation check to the TLS handshake.

Audit Logging¶

SQL Audit Logging (Enterprise)¶

CockroachDB Enterprise provides role-based SQL audit logging that records query activity for specified users or roles. This is used for compliance, forensic analysis, and change tracking.

Enable audit logging for a role:

ALTER ROLE auditor WITH AUDIT;

Audit log entries include: timestamp, user, statement text, affected rows, execution status, and database context.

System Event Log¶

All clusters (including Core) write system events to system.eventlog, recording DDL operations, privilege changes, user creation, zone config changes, and node join/leave events.

SELECT timestamp, "eventType", "userName", "reportedApplication"
FROM system.eventlog
ORDER BY timestamp DESC
LIMIT 50;

Network Security¶

IP Allowlisting¶

CockroachDB supports restricting SQL connections by source IP address using the server.host_based_authentication.configuration cluster setting. This is functionally similar to PostgreSQL's pg_hba.conf:

SET CLUSTER SETTING server.host_based_authentication.configuration = '
    host all all 10.0.0.0/8 password
    host all all 0.0.0.0/0 cert-password
';

Cloud-Native Network Controls¶

For CockroachDB Cloud deployments:

AWS PrivateLink -- private connectivity from VPC to CockroachDB Cloud.
GCP VPC Peering -- private peering between GCP VPC and CockroachDB Cloud.
IP allowlists -- restrict DB Console and SQL access to specific CIDR ranges.

Security Best Practices¶

Production Security Checklist

Use mutual TLS for all inter-node and client-to-node communication.
Generate node and client certificates from a dedicated cluster CA (not a public CA).
Enable encryption at rest for any data subject to regulatory requirements.
Create dedicated SQL users for each application; never use root for application workloads.
Grant least-privilege roles; avoid granting ALL when only SELECT is needed.
Enable audit logging for privileged roles (admin, custom operator roles).
Rotate CA and node certificates before expiry. Monitor certificate expiry metrics.
Use insecure=false (default). Never run production clusters in insecure mode.
Restrict network access with IP allowlists or private connectivity options.