> ## Documentation Index > Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # SQL Authentication export const InternalLink = ({version, path = "", children, ...props}) => { let detectedVersion = version || "stable"; if (typeof window !== 'undefined' && !version) { const match = window.location.pathname.match(/\/docs\/([^/]+)/); if (match) { detectedVersion = match[1]; } } const normalizedPath = path.startsWith("/") ? path.slice(1) : path; return {children} ; }; 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: * Logging in to the CockroachDB Cloud web console. * Accessing the DB console on CockroachDB clusters. ## 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` cluster setting, using the `SET CLUSTER SETTING` statement, which accepts a single text field that must be a correctly formatted HBA manifest. Inspect the current setting with `SHOW CLUSTER SETTING`. ## Supported authentication methods | Authentication Method | CockroachDB Cloud | CockroachDB | CockroachDB | | ------------------------------ | ----------------- | ----------- | ----------- | | password | ✓ | ✓ | ✓ | | username/password combination | ✓ | ✓ | ✓ | | [SCRAM-SHA-256][SCRAM-SHA-256] | ✓ | ✓ | ✓ | | [certificate][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. [SCRAM-SHA-256]: /docs/v26.3/security-reference/scram-authentication [certificate]: /docs/v26.3/security-reference/transport-layer-security ## 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. 1. Each line must begin with a connection **TYPE**. CockroachDB currently supports two connection types: 2. `local` 3. `host` (any remote host) 4. **`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`. 5. **`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. 6. **`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). 7. **`IP MASK`** (unless the Address in the prior field included or did not require an IP mask). 8. 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 Salted Challenge-Response * `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 SCRAM 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 SCRAM exchange. * `gss`: user may authenticate with a GSSAPI token. * `ldap`: user may authenticate using LDAP-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. ### Disabling root login **This feature is in preview** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com). 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 `admin` role 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](#disable-root-login-and-use-debug_user). ### Using debug\_user for diagnostics **This feature is in preview** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com). The `debug_user` is a special privileged user designed for collecting `cockroach debug zip` and `cockroach debug tsdump` 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 Managing Network Authorization for CockroachDB Advanced. ### 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 ``` ## Disable root login and use debug\_user 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 `admin` role 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` 1. Connect to the cluster as a user with admin privileges (such as `root`): ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach sql --certs-dir=certs ``` 2. Create user `debug_user`: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} CREATE USER debug_user; ``` 3. 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. ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} GRANT admin TO debug_user; ``` ### Step 2: Generate `debug_user` certificate Generate a client certificate for `debug_user`. Refer to Create a `debug_user` client certificate for detailed instructions. ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach start \ --certs-dir=certs \ --allow-debug-user \ [other existing flags...] ``` ### Step 5: Disable root login After all nodes have been restarted with `--allow-debug-user`, perform another rolling restart with the `--disallow-root-login` flag: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach start \ --certs-dir=certs \ --disallow-root-login \ --allow-debug-user \ [other existing flags...] ``` ### Step 6: Verify configuration 1. Verify `root` is blocked: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach sql --certs-dir=certs --user=root ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} ERROR: certificate authentication failed for user "root" ``` 2. Verify debug\_user works: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach sql --certs-dir=certs --user=debug_user -e "SELECT current_user();" ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} current_user ---------------- debug_user ``` 3. Verify debug zip collection: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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. ### See also * `cockroach start` * `cockroach cert create-client` * `cockroach debug zip` * `CREATE USER`