- You run your own Certificate Authority (CA) infrastructure.
- You need to use your existing CA infrastructure to manage SQL user authentication.
- You need to use the same CA for multiple CockroachDB clusters.
Related functionality
Prior to CockroachDB v24.1, it was only safe to use certificates generated by CAs that placed restrictions on theCommonName field (so that only authorized users could get a cert with CommonName=root, for example). That meant that mapping the certificate principals to IP addresses, DNS names, and SQL users required using the --cert-principal-map flag, which was first added in v20.1. That approach still works, but is superseded by the functionality described on this page, which should be much easier to use since you do not need to restart nodes when you add or remove users.
The Subject mapping functionality described on this page makes it possible to use CAs that do not place restrictions on the CommonName field but do place restrictions on other subject fields (for example, that every cert has an OU field based on the user that created it).
The default workflow using cockroach cert only sets the CommonName field in its certificates, so the functionality described in this page is unnecessary. It is not possible to share a single CA managed by cockroach cert across multiple CockroachDB clusters.
Example
This example shows how to set up a mapping between the Subject field of an X.509 certificate and a SQL user or role.Step 1. Create certificates using your infrastructure
These instructions assume that you have already created certificates using your own infrastructure for the following users:- The
rootuser. - The
nodeuser. - Any SQL user who needs to authenticate with your cluster. In this example, we will call the user
maxroach.
- The cluster name and SQL user name will generally both appear somewhere in the certificate’s Subject.
- The cluster name will usually go in the
OUorDCfields, and the user name inUIDorCNfields. You can also map the user name to aSANfield by enabling Subject Alternative Name mapping. - For example, the Subject might look like
O=Acme Inc,OU=movr-prod,UID=root.
Step 2. Start your cluster with root and node certificate flags
At cluster startup, you’ll need to pass thecockroach start flags --node-cert-distinguished-name and --root-cert-distinguished-name.
The argument to each flag is a string with a comma separated list of distinguished name (DN) mappings in {attribute-type}={attribute-value} format in accordance with RFC4514. When each of these flags are set, the argument needs to be an exact match with the DN subject in the client certificate provided. By exact match, we mean that the order of attributes in the argument must match the order of attributes in the DN subject in the certificate.
node user in the example above is:
root user.
If you plan to map users to Subject Alternative Name (SAN) fields, also pass the --root-cert-san and --node-cert-san flags. Each flag takes a comma-separated list of {attribute-type}={attribute-value} SAN entries, where the attribute type is DNS, IP, or URI. These flags are enforced only when the security.client_cert.san_required.enabled cluster setting is true.
Step 3. Set the SUBJECT role option using CREATE ROLE or ALTER ROLE to match your certificates
You can associate an X.509 certificate’s Subject with a role as shown below. Note that the Subject fields in the certificate have to be an exact match with what you pass in via the SQL statement. By exact match, we mean that the order of attributes passed in via the SQL statement must match the order of attributes in the certificate.
ALTER ROLE ... SUBJECT.
ALTER ROLE ... SUBJECT cannot be applied to the root user. You must use cockroach start --root-cert-distinguished-name instead.
Step 4. Enable the cluster setting to require the Subject field in certificates
Once the cluster is started, enable the following cluster setting:SUBJECT role option set will be unable to log in with certificates.
Regardless of this setting’s value, CockroachDB will verify the following during user authentication provided the Subject options or DN flags or both are set:
- For the
rootuser, that the distinguished name in the certificate Subject matches the distinguished name fields passed in viacockroach start --root-cert-distinguished-name. - For the
nodeuser, that the distinguished name in the certificate Subject matches the distinguished name fields passed in viacockroach start --node-cert-distinguished-name. - For all other SQL users, that the values in the Subject field of the X.509 certificate match the values attached to the user or role with
CREATE ROLE ... SUBJECTorALTER ROLE ... SUBJECT.
(Optional) Enable the cluster setting to map users to Subject Alternative Name (SAN) fields
If your organization uses Subject Alternative Name (SAN) fields for user identity mapping, enable the following cluster setting to authenticate client certificates by their SAN entries instead of the default CN lookup:
SAN entry, and CockroachDB establishes the identity of each user as follows:
- For the
rootuser, everySANentry passed tocockroach start --root-cert-sanmust be present in the certificate’sSANentries. If--root-cert-sanis not set,rootcertificate login is rejected unless--root-cert-distinguished-nameis set and matches the certificate’s Subject DN. Enabling this setting without one of these flags locksrootout of certificate authentication. - For the
nodeuser, everySANentry passed tocockroach start --node-cert-sanmust be present in the certificate’sSANentries. If--node-cert-sanis not set,nodecertificate login is rejected unless--node-cert-distinguished-nameis set and matches the certificate’s Subject DN. - For
debug_user, the certificate must be issued fordebug_user. Refer to Using debug_user for diagnostics. - For all other SQL users, the certificate must be explicitly bound to the SQL user by one of the following:
- An identity map: a
mapoption on the certificate rule in the HBA configuration, together with a matching line in theserver.identity_map.configurationcluster setting. See Bind a SAN to a SQL user with an identity map. - An exact subject DN: the
SUBJECTrole option set to the certificate’s full Subject DN, as described in Step 3.
- An identity map: a
CN is not used as a fallback. A non-privileged SQL user whose certificate is bound by neither an identity map nor a SUBJECT DN is rejected with an error such as:
auth.cert.san.conn.total and auth.cert.san.conn.success metrics track the number of SQL connection attempts, and successful connections, that use SAN-based certificate authentication.
Bind a SAN to a SQL user with an identity map
The identity map follows the PostgreSQLpg_ident.conf user name map format: each line of server.identity_map.configuration is a space-separated triple of map name, external identity, and SQL username, and the map name is the value you reference with the map option in the HBA configuration. For SAN-based certificate authentication, the external identity has the format SAN:{attribute-type}:{attribute-value}, where the attribute type is DNS, URI, or IP. For example: SAN:DNS:maxroach.example.com, SAN:URI:spiffe://example.org/maxroach, or SAN:IP:10.0.0.5. A literal external identity matches case-insensitively. An external identity that starts with / is treated as a regular expression, and the SQL username can reference its first capture group as \1.
This is not the same format as the SSO identity map used for JWT authentication, where the first field is the token issuer URL rather than a map name.
DNS SAN entry to the SQL user maxroach.
-
Create a client certificate for
maxroachthat carries aSANentry. For example, usingopenssl: -
Add a line to the identity map that maps the
SANentry to the SQL user. This example names the mapcrdb: -
Reference the map from the certificate rule in the HBA configuration with the
mapoption. Thecert,cert-password, andcert-scram-sha-256methods all acceptmap:
maxroach certificate can now connect as maxroach. If the certificate’s SAN entries do not match any line in the map, or map to a different SQL user than the one requested in the connection, the connection is rejected.

