CockroachDB Security: Certificates, SQL Roles, CMEK and Network Controls Explained

A CockroachDB cluster trusts whatever holds a valid certificate, password or token for a SQL user, so certificate handling, role design and network reach decide who can read and change your data. This guide covers the customer side of CockroachDB security for self-hosted clusters and CockroachDB Cloud: node and client certificates, SQL users, roles and system privileges, Cloud organisation roles and service accounts, customer-managed encryption keys (CMEK), network authorisation and audit logging. It is written for database administrators, platform engineers and security teams who run or approve CockroachDB deployments. For controls common to every database engine, see the Database Security Guide.

This is an independent guide from NHI Mgmt Group, based on Cockroach Labs' public documentation as of November 2026. It is not sponsored or reviewed by Cockroach Labs. Product features change, so confirm settings against Cockroach Labs' current documentation.

Key takeaways

• Certificates are machine identities. Every node holds ca.crt, node.crt and node.key, and every certificate-authenticated client holds a client.<user>.crt whose CN matches the SQL username. Inventory, protect and rotate them like any other credential.
• Keep root for break glass. Set a password on root, restrict where it can be used, and grant the admin role to a few named users instead; applications get their own least-privilege users.
• Prefer system privileges to role options. Grant VIEWACTIVITY, MODIFYCLUSTERSETTING or CREATEROLE with GRANT ... SYSTEM, and audit them with SHOW SYSTEM GRANTS.
• Decide on CMEK at cluster creation. On CockroachDB Cloud Advanced, CMEK needs advanced security features enabled when the cluster is created; plan key ownership, per-region keys and rotation before you provision.
• Close the network first. Remove 0.0.0.0/0 before production, use private connectivity where you can, and route SQL audit events from the SENSITIVE_ACCESS, USER_ADMIN, PRIVILEGES and SESSIONS channels to your SIEM.

How identity and access work in CockroachDB

CockroachDB separates three questions: how a node or client proves who it is (authentication), what that SQL identity may do (authorisation), and who may manage the cluster itself (Cloud organisation roles, or operating system access for self-hosted clusters).

Node and client certificates

A self-hosted node needs three files in its --certs-dir: ca.crt (the CA it trusts), node.crt and node.key. The node presents the same certificate as a server and as a client to other nodes. When you use a public or organisational CA, split the identity into node.crt and node.key for server use and client.node.crt and client.node.key for client use. A split CA with a separate ca-client.crt for client certificates is possible, though Cockroach Labs advises it only where your security practice requires it.

• Creation: cockroach cert create-ca, create-node and create-client, or openssl. The --ca-key flag (or COCKROACH_CA_KEY) points to the CA private key; cockroach cert list shows what is in a certs directory.
• Lifetime: the documented --lifetime default is 87840h (10 years) and the default key size is 2048 bits. Set a shorter --lifetime explicitly that matches your certificate policy rather than accepting a decade-long credential.
• CA key custody: the CA key can mint a certificate for any SQL user, including root. Keep it off the nodes, in a vault or HSM-backed store, and record who can use it.
• Revocation: self-hosted Enterprise supports OCSP certificate revocation checking, so a lost client key can be revoked before it expires.

Host-based authentication

The cluster setting server.host_based_authentication.configuration holds HBA rules that choose the authentication method by user, database and source address. Use it to require certificates for root, restrict password logins to known application subnets and reject everything else. The --accept-sql-without-tls flag (preview) allows password logins without TLS where transport security is handled by the infrastructure; keep TLS end to end unless you have that control in place. Always start production nodes in secure mode, never with --insecure.

Admin roles and privileged access

SQL users, roles and the built-in identities

CockroachDB does not technically distinguish users from roles: CREATE USER makes a login-enabled entity and CREATE ROLE adds NOLOGIN by default. By convention, roles hold privileges and users are members of roles.

System privileges

System privileges apply cluster wide, are inherited through role membership, and are granted with GRANT ... SYSTEM and listed with SHOW SYSTEM GRANTS. They are gradually replacing the older role options; where both exist with the same name, the system privilege takes precedence, so prefer it. Useful ones for delegating without admin:

• VIEWACTIVITY: view other users' activity statistics, for support and performance staff.
• MODIFYCLUSTERSETTING: change cluster settings, including HBA and audit settings. Treat it as privileged and alert on its use.
• CREATEROLE: create, modify and drop non-admin roles; give it to an identity team role rather than to admin.

Object privileges and ownership

Object privileges (SELECT, INSERT, UPDATE, DELETE, CREATE, USAGE, ZONECONFIG and others) are granted on databases, schemas, tables, sequences, types and functions. Privileges on a database do not flow to its existing or future objects, so use ALTER DEFAULT PRIVILEGES and check them with SHOW DEFAULT PRIVILEGES. The creator owns an object and holds ALL on it; transfer ownership to a role before dropping a departing user. For role design patterns, see the Least Privilege Techniques Guide.

CockroachDB Cloud organisation roles

Managing the Cloud organisation is separate from SQL access. A Cluster Admin can provision SQL users from the console, so console roles are privileged too.

Roles assigned at folder scope are inherited by its clusters, so assign at the narrowest scope that works.

Integrations, API tokens and service accounts

CockroachDB carries two families of non-human identity: Cloud service accounts that call the CockroachDB Cloud API with API keys, and SQL users that applications, ETL jobs and changefeeds use to connect. Both need an owner, a purpose and a rotation date. See the Service Account Security Guide for the general lifecycle.

• Cloud service accounts: authenticate only to the Cloud API, using keys issued in the console, and can hold the same roles as people. Give Terraform and pipelines Cluster Operator or Cluster Creator at folder or cluster scope rather than Organization Admin, store keys in a secrets manager and rotate them on a schedule. See the API Key Management Guide.
• Application SQL users: one user per application, a role holding only the object privileges it needs, no membership of admin, and a client certificate or a password stored in a secrets manager. JWT authentication on Advanced and self-hosted lets workloads present short-lived identity provider tokens instead of static passwords.
• Identity provider sync: with JWT or OIDC, CockroachDB can grant and revoke membership of existing roles from group claims, so joiner and leaver changes in the IdP reach the database. Only roles that already exist are synced, so create them first.
• Backups and KMS credentials: backup and restore jobs reach cloud storage and KMS with AUTH=implicit or specified credentials. Prefer implicit workload credentials so no long-lived cloud key sits in a job definition. See the Secrets Management Guide.

Encryption and key management

Operating CMEK safely

CockroachDB Cloud never sees the CMEK key material. That gives you a kill switch and a responsibility: if the key becomes unavailable or access is revoked, the cluster cannot start until access is restored, restarted nodes cannot rejoin, managed backups start failing, and Cockroach Labs support may be needed even after the key returns. Protect the key with KMS deletion protection, alert on key disable or schedule-for-deletion events, and never destroy a key until KMS audit logs show it is unused. Rotate the CMEK by creating a new key version and rotating each region in CockroachDB Cloud, or by rotating to a new key URI. Add a CMEK for every region you add later. See the BYOK, HYOK and External Key Management Guide.

Self-hosted encryption at rest

Generate store keys with cockroach gen encryption-key -s 256, keep them on a protected path outside the data directory, and rotate the store key by restarting with key set to the new file and old-key to the previous one. Encryption covers new data, and existing data is encrypted as compactions rewrite it, so enable it before loading production data. Confirm status in DB Console at /#/reports/stores/local or with cockroach debug encryption-active-key.

Network authorisation

CockroachDB Cloud uses IP allowlists plus private connectivity. Standard clusters start with a 0.0.0.0/0 entry for quick setup, and Advanced clusters start with no authorised networks; remove 0.0.0.0/0 before production.

Prefer private connectivity when you need more ranges than the allowlist allows, have non-static addresses, or must keep traffic off the public internet. DB Console access on Advanced needs a Cloud role on the cluster; over the internet, add a temporary allowlist entry with the DB Console option and remove it afterwards, and connect through admin-{cluster-name}.crdb.io rather than a hardcoded IP. Over AWS PrivateLink, allow port 8080 as well as SQL port 26257 in the endpoint security group. For self-hosted clusters, restrict 26257 to application and node subnets and 8080 to administrator networks with host and network firewalls.

Logging and detection

• Table audit: ALTER TABLE <table> EXPERIMENTAL_AUDIT SET READ WRITE writes sensitive_table_access events to the SENSITIVE_ACCESS channel (files prefixed cockroach-sql-audit). Enable it on tables holding personal or regulated data.
• Role-based audit (preview, Enterprise): the sql.log.user_audit cluster setting lists USER/ROLE and ALL or NONE rows, first match wins. Log everything from admin members and human users; for example, list a high-volume application role as NONE above an ALL ALL row only if its table access is already covered.
• Identity channels: pair SENSITIVE_ACCESS with USER_ADMIN (user and role changes), PRIVILEGES (grants and revokes) and SESSIONS (logins), as the docs recommend.
• Non-repudiation: setting auditable on the SENSITIVE_ACCESS sink logs synchronously and durably, with added overhead; use it where evidence quality matters.
• Cloud exports: Cluster Operators can export logs and metrics to your cloud logging service; also collect KMS audit logs for every CMEK and backup key.

Audit logging has a performance cost, because each logged query writes to disk on the node, so scope it deliberately and use SQL_EXEC, not audit channels, for debugging. Detection ideas and SIEM patterns are in the Database Audit Log Detection Guide.

Metrics to track: number of admin members and root logins per month; percentage of application users with a named owner; certificates expiring within 30 days (check Valid Until on the DB Console Local Node Certificates page); percentage of sensitive tables under audit; allowlist entries wider than /24; and days since last Cloud API key rotation.

Hardening baseline

The sequence below is NHI Mgmt Group guidance, not a vendor requirement; adjust it to your environment.

1. Inventory. List nodes, certificates and expiry dates, SQL users and roles, admin members, system grants, Cloud users, service accounts and API keys, and allowlist entries.
2. Fix identities first. Move applications off root, create per-application users and roles, set a root password and an HBA rule requiring certificates for root, and grant admin only to named people.
3. Delegate with system privileges. Replace broad admin membership with VIEWACTIVITY, CREATEROLE and other narrow grants; revoke anything granted to public.
4. Close the network. Remove 0.0.0.0/0, add named ranges or private connectivity, and test each application path in staging before the production change. Roll back by restoring the previous allowlist entry if a path breaks.
5. Set certificate policy. Issue certificates with explicit lifetimes, keep the CA key off nodes, rotate the CA months ahead of node and client certificates using the combined ca.crt, and reload with SIGHUP (pkill -SIGHUP -x cockroach) without restarting nodes.
6. Encrypt. Choose CMEK (Advanced, at creation) or Enterprise Encryption At Rest (self-hosted) and encrypt every backup with kms, using one key per region.
7. Turn on auditing. Enable table audit on sensitive tables, configure sql.log.user_audit, route channels to the SIEM and build the alerts above. Pilot on a staging cluster to measure overhead first.
8. Maintain. Apply CockroachDB version upgrades and security updates promptly (Cloud maintenance windows are set by Cluster Admins), and review roles, keys and allowlists quarterly.

Framework mapping

Common misconfigurations

• Applications connecting as root. One leaked connection string then carries full cluster control. Give each application its own user and role.
• Ten-year certificates and an online CA key. Accepting the default lifetime and leaving ca.key on nodes turns one host compromise into the power to mint any user's certificate. Set lifetimes and move the CA key to a vault.
• 0.0.0.0/0 left after testing. Remove the open entry before go-live and review allowlists quarterly.
• CMEK without key governance. A disabled or deleted key stops the cluster and breaks managed backups. Use deletion protection, alerts and change control on the KMS key.
• Grants to public or assumed inheritance. Privileges granted to public reach every user, and database grants do not cover new tables; use roles and ALTER DEFAULT PRIVILEGES.
• Audit configured, never collected. SENSITIVE_ACCESS files on local disk help no one; ship them, with USER_ADMIN, PRIVILEGES and SESSIONS, to the SIEM.

Practitioner checklist

• Confirm every production node runs in secure mode with TLS and a node certificate covering all its addresses.
• Issue certificates with explicit lifetimes, keep the CA key in a vault and track expiry dates.
• Set a root password, require certificates for root via HBA and keep root for break glass.
• Limit admin to named people and delegate with system privileges instead.
• Give each application its own SQL user and role with object privileges only.
• Scope Cloud service accounts to Cluster Operator or narrower, store API keys in a secrets manager and rotate them.
• Remove 0.0.0.0/0 and use PrivateLink, Private Service Connect or Azure Private Link where available.
• Enable CMEK on Advanced clusters at creation, or Enterprise Encryption At Rest when self-hosted, and encrypt backups with KMS.
• Enable table and role-based audit logging and forward all security channels to the SIEM.
• Apply CockroachDB upgrades promptly and review roles, keys and allowlists every quarter.

Standards and references

• Cockroach Labs: CockroachDB security overview
• Cockroach Labs: Authentication
• Cockroach Labs: Authorization
• Cockroach Labs: Rotate security certificates
• Cockroach Labs: Customer-Managed Encryption Keys (CMEK)
• Cockroach Labs: Network authorization for CockroachDB Cloud
• Cockroach Labs: SQL audit logging
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Database Security Guide · Machine Identity, PKI and Certificate Lifecycle Guide · Service Account Security Guide · Data Security Guide