SQL Authentication

This page give an overview of CockroachDB’s security features for authenticating the identity of SQL users attempting to connect to the cluster. Instead, you might be looking for:

Authentication configuration

CockroachDB allows fine-grained configuration of which database connection attempts it allows to proceed to the authentication stage, and which authentication methods it accepts, based on:

Who is making the attempt (SQL user).
Where on the internet (IP Address) the attempt is coming from.

CockroachDB’s authentication behavior is configured using a domain-specific language (DSL) called host-based authentication (HBA). HBA syntax is shared with PostgreSQL. A specific CockroachDB cluster’s authentication behavior is configured by setting its server.host_based_authentication.configuration , using the , which accepts a single text field that must be a correctly formatted HBA manifest. Inspect the current setting with

Supported authentication methods

Authentication Method	CockroachDB Cloud	CockroachDB	CockroachDB
password	✓	✓	✓
username/password combination	✓	✓	✓
SCRAM-SHA-256	✓	✓	✓
certificate	✓	✓	✓
GSS			✓

All options also support the following no-op ‘authentication methods’, which do not perform authentication:

reject: unconditionally rejects the connection attempt.
trust: unconditionally accepts the connection attempt.

HBA configuration syntax

Each line of a Host-based Authentication (HBA) configuration manifest defines a rule. Lines commented with # are ignored. For example, the following naive configuration has three rules:

User ceo can connect to the database from a known IP address without a password.
User sabateur cannot connect from anywhere.
All users (including ceo but not sabateur) can connect from anywhere using a password.

 # TYPE    DATABASE      USER           ADDRESS             METHOD
   host    all           ceo            555.123.456.789/32  trust
   host    all           saboteur       all                 reject
   host    all           all            all                 password

Each rule definition contains up to 6 values.

Each line must begin with a connection TYPE. CockroachDB currently supports two connection types:
local
host (any remote host)
DATABASE, which defines the name of the database(s) to which the rule will apply. Currently, CockroachDB only supports cluster-wide rules, so the value in this column must be all.
USER, which defines the username to which the rule applies. CockroachDB requires all connection requests to include a username. If the presented username exists in the system.users table and has the LOGIN option enabled, CockroachDB will check the authentication configuration to find an allowed method by which the user may authenticate. This parameter can also take the value all, in which case it will match all users.
ADDRESS specifies the IP range which the rule will allow or block, either with the keyword “all”, or with a valid IP address. The IP address can include an IP mask (the value of the field can be of the format XXX.XXX.XXX.XXX/X), or not, in which case the next value must be the mask (the value of this field will be of the form XXX.XXX.XXX.XXX, in which case the next field must be a valid IP mask).
IP MASK (unless the Address in the prior field included or did not require an IP mask).
Authentication METHOD by which specified user(s) may authenticate from specified addresses.

password: user may authenticate with a plaintext password.
scram-sha-256: user may authenticate via
cert: user may authenticate with a PKI certificate signed by a trusted certificate authority CA.
cert-password: user may authenticate with either a certificate or a password. Additionally, the server may use a exchange, if the cluster setting server.user_login.cert_password_method.auto_scram_promotion.enabled is set to true.
cert-scram-sha-25: user may authenticate with either a certificate or a exchange.
gss: user may authenticate with a GSSAPI token.
ldap: user may authenticate using -compatible directory services, such as Microsoft Entra ID and Active Directory.
reject: server unconditionally rejects connection without performing authentication.
trust: server unconditionally allows connection without performing authentication.

The `root` access rule

By default, the root SQL user can always authenticate using username/password or certificate, as if the first rule of the configuration were:

# TYPE    DATABASE      USER           ADDRESS             METHOD
  host    all           root           all                 root

This rule is not displayed in the configuration, and cannot be overridden through HBA configuration alone. This ensures that access to the cluster can always be recovered, but it also means that access with root credentials cannot be restricted by IP range at the authentication configuration level.

This feature is in and subject to change. To share feedback and/or issues, contact Support.

For compliance requirements, you can disable root user login using the --disallow-root-login flag when starting nodes. When this flag is set:

The root user cannot authenticate via SQL or RPC connections
Any certificate with “root” in the CommonName or SubjectAlternativeName is rejected
Error messages indicate root login has been disallowed

Important Prerequisites:

Before disabling root, ensure you have at least one other user with the configured. Once root is disabled, you will need another admin user to perform administrative tasks.
Before disabling root, it is highly recommended to set up the debug_user for troubleshooting operations. See Using debug_user for diagnostics.
Ensure no cluster or client certificates contain “root” in their SAN (Subject Alternative Name) fields, as these will be blocked.

The cluster does not validate that other users are members of the admin role or that debug_user is configured before allowing root to be disabled.

For setup instructions, see Disable root login and use debug_user.

Using debug_user for diagnostics

This feature is in and subject to change. To share feedback and/or issues, contact Support.

The debug_user is a special privileged user designed for collecting and data when root is disabled. Unlike root, debug_user:

Must be explicitly enabled using the --allow-debug-user flag on cockroach start
Is disabled by default for security
Must be manually created using CREATE USER debug_user
Requires a certificate with “debug_user” in CommonName or SubjectAlternativeName
Has privileged access to serverpb admin and status endpoints required for debug zip and tsdump collection
Can be audited using SHOW USERS

The debug_user is not subject to the --disallow-root-login flag and provides a secure, auditable alternative for these diagnostic operations. CockroachDB Advanced or CockroachDB self-hosted customers can and should enforce network protections, preventing access attempts from any sources other than a valid ones such as application servers or a secure operations jumpbox.

Default behavior

CockroachDB Standard and CockroachDB Basic

The default authentication configuration for CockroachDB Standard and CockroachDB Basic clusters is equivalent to the following configuration:

 # TYPE    DATABASE      USER        ADDRESS       METHOD
   host    all           all         all           password

This is convenient for quick usage and experimentation, but is not suitable for clusters containing production data. It is a best practice to configure SQL authentication for hardened CockroachDB cluster security.

CockroachDB Advanced

CockroachDB Advanced clusters enforce IP allowlisting. Each cluster has an allowlist, which is configured through the CockroachDB Cloud Console. See .

CockroachDB

CockroachDB deploys with the following default HBA configuration:

# TYPE    DATABASE      USER        ADDRESS        METHOD
  host    all           root        all            cert-password
  host    all           all         all            cert-password
  local   all           all                        password

Access for SQL health monitoring

CockroachDB Cloud uses a service user named managed-sql-prober that regularly runs SELECT 1; queries on the cluster to monitor and report issues with SQL availability. The default host-based authentication configurations allow this service user to run, but more restrictive HBA configurations may prevent SQL availability monitoring. To explicitly enable this service user to authenticate, add the following line to your HBA configuration:

# TYPE    DATABASE      USER                 ADDRESS        METHOD
  host    all           managed-sql-prober   all            cert

This procedure shows how to configure a cluster to disable root login for compliance requirements while maintaining the ability to collect debug zip and tsdump data.

While it is possible to disable root login without first setting up debug_user, enabling debug_user later when diagnostic data is needed requires a rolling restart of all cluster nodes. This can add a significant delay during troubleshooting incidents.Cockroach Labs recommends setting up debug_user before disabling root login to ensure diagnostic capabilities are immediately available when needed.

Before you begin

To complete this process, you will need:

An existing CockroachDB cluster.
Admin privileges to create users and grant roles.
Access to the CA key to generate certificates.

Important: Ensure you have at least one other user with the besides root before proceeding. Once root is disabled, you will need another admin user to perform administrative tasks. Without this, you risk losing administrative access to your cluster.

Step 1: Create `debug_user`

Connect to the cluster as a user with admin privileges (such as root):
cockroach sql --certs-dir=certs
Create user debug_user:
CREATE USER debug_user;
Grant the admin role for debug zip collection.
While cockroach debug tsdump does not require any SQL privileges, the admin role is required for cockroach debug zip. Cockroach Labs recommends granting it to debug_user when the user is created to ensure that the debug zip capability is immediately available when needed. Alternatively, another admin user can grant this role when needed.
GRANT admin TO debug_user;

Step 2: Generate `debug_user` certificate

Generate a client certificate for debug_user. Refer to for detailed instructions.

cockroach cert create-client debug_user \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

This creates client.debug_user.crt and client.debug_user.key in the certs directory.

Step 3: Test `debug_user` access

Before disabling root, verify that debug_user can collect debug information:

cockroach debug zip test-debug.zip \
  --certs-dir=certs \
  --user=debug_user

If successful, you should see debug information being collected.

Step 4: Enable `debug_user` on all nodes

Perform a rolling restart of all nodes with the --allow-debug-user flag:

cockroach start \
  --certs-dir=certs \
  --allow-debug-user \
  [other existing flags...]

After all nodes have been restarted with --allow-debug-user, perform another rolling restart with the --disallow-root-login flag:

cockroach start \
  --certs-dir=certs \
  --disallow-root-login \
  --allow-debug-user \
  [other existing flags...]

Step 6: Verify configuration

Verify root is blocked:

cockroach sql --certs-dir=certs --user=root

ERROR: certificate authentication failed for user "root"

Verify debug_user works:

cockroach sql --certs-dir=certs --user=debug_user -e "SELECT current_user();"

  current_user
----------------
  debug_user

Verify debug zip collection:

cockroach debug zip production-debug.zip \
  --certs-dir=certs \
  --user=debug_user

Security best practices

Monitor debug_user activity through audit logs
Rotate debug_user certificates regularly
Ensure debug_user certificate files have appropriate permissions (mode 0700)
Store debug_user certificates securely and limit access to authorized personnel

Troubleshooting

Error: “failed to perform RPC, as root login has been disallowed”

Root login is disabled. Use debug_user instead.

Error: “failed to perform RPC, as debug_user login is not allowed”

The --allow-debug-user flag is not set on the server. Restart the node with this flag.

Error: “certificate authentication failed for user ‘debug_user’”

Either the debug_user certificate is invalid or --allow-debug-user is not set.
Verify the certificate has “debug_user” in CommonName or SubjectAlternativeName.

Architecture

Cockroach Commands

Logs

Metrics

Policies

Third-Party Support

Security

System Catalogs

FAQs

Authentication configuration

Supported authentication methods

HBA configuration syntax

The `root` access rule

Using debug_user for diagnostics

Default behavior

CockroachDB Standard and CockroachDB Basic

CockroachDB Advanced

CockroachDB

Access for SQL health monitoring

Before you begin

Step 1: Create `debug_user`

Step 2: Generate `debug_user` certificate

Step 3: Test `debug_user` access

Step 4: Enable `debug_user` on all nodes

Step 6: Verify configuration

Security best practices

Troubleshooting

See also

​Authentication configuration

​Supported authentication methods

​HBA configuration syntax

​The root access rule

​Disabling root login

​Using debug_user for diagnostics

​Default behavior

​CockroachDB Standard and CockroachDB Basic

​CockroachDB Advanced

​CockroachDB

​Access for SQL health monitoring

​Disable root login and use debug_user

​Before you begin

​Step 1: Create debug_user

​Step 2: Generate debug_user certificate

​Step 3: Test debug_user access

​Step 4: Enable debug_user on all nodes

​Step 5: Disable root login

​Step 6: Verify configuration

​Security best practices

​Troubleshooting

​See also

Authentication configuration

Supported authentication methods

HBA configuration syntax

The `root` access rule

Disabling root login

Using debug_user for diagnostics

Default behavior

CockroachDB Standard and CockroachDB Basic

CockroachDB Advanced

CockroachDB

Access for SQL health monitoring

Disable root login and use debug_user

Before you begin

Step 1: Create `debug_user`

Step 2: Generate `debug_user` certificate

Step 3: Test `debug_user` access

Step 4: Enable `debug_user` on all nodes

Step 5: Disable root login

Step 6: Verify configuration

Security best practices

Troubleshooting

See also