> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificate-based authentication using multiple values from the X.509 Subject field

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 <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

For customers that need to use their established Certificate Authority (CA) infrastructure to manage SQL user authentication, CockroachDB supports mapping of SQL user <InternalLink path="security-reference/authorization#roles">roles</InternalLink> to values in the Subject field of the [X.509 certificate](https://en.wikipedia.org/wiki/X.509) used for <InternalLink path="security-reference/transport-layer-security#what-is-transport-layer-security-tls">TLS authentication</InternalLink>.

This mapping (hereafter referred to as "Subject mapping") can be used to automate the synchronization of SQL user roles with specific certificate attributes, leading to improved scalability of access control mechanisms.

Subject mapping is useful if:

* You run your own <InternalLink path="security-reference/transport-layer-security#certificates-signing-trust-and-authority">Certificate Authority (CA)</InternalLink> infrastructure.
* You need to use your existing CA infrastructure to manage <InternalLink path="create-user#user-authentication">SQL user authentication</InternalLink>.
* You need to use the same CA for multiple CockroachDB clusters.

For instructions showing how to map SQL user roles to values in the Subject field of the X.509 certificate, see the [Example](#example).

## Related functionality

Prior to CockroachDB v24.1, it was only safe to use certificates generated by CAs that placed restrictions on the `CommonName` 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 <InternalLink path="cockroach-start">the `--cert-principal-map` flag</InternalLink>, 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](#step-3-set-the-subject-role-option-using-create-role-or-alter-role-to-match-your-certificates).

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 <InternalLink path="cockroach-cert#examples">default workflow using `cockroach cert`</InternalLink> 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](https://en.wikipedia.org/wiki/X.509) and a SQL <InternalLink path="security-reference/authorization#roles">user or role</InternalLink>.

### 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 <InternalLink path="security-reference/authorization">`root` user</InternalLink>.
* The <InternalLink path="security-reference/authorization">`node` user</InternalLink>.
* Any <InternalLink path="security-reference/authorization#sql-users">SQL user</InternalLink> who needs to authenticate with your cluster. In this example, we will call the user `maxroach`.

General guidelines for certificate creation:

* 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 `OU` or `DC` fields, and the user name in `UID` or `CN` fields. You can also map the user name to a `SAN` field by enabling [Subject Alternative Name mapping](#optional-enable-the-cluster-setting-to-map-users-to-subject-alternative-name-san-fields).
* 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 the <InternalLink path="cockroach-start">`cockroach start`</InternalLink> flags <InternalLink path="cockroach-start">`--node-cert-distinguished-name`</InternalLink> and <InternalLink path="cockroach-start">`--root-cert-distinguished-name`</InternalLink>.

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](https://www.rfc-editor.org/rfc/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.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach start --certs-dir=/path/to/certs --node-cert-distinguished-name="O=Acme Inc,OU=movr-prod,UID=node" --root-cert-distinguished-name="O=Acme Inc,OU=movr-prod,UID=root" # other startup flags, etc.
```

The DN mappings in the certificates you create should match what you pass in at cluster start time. One way to create a certificate matching the `node` user in the example above is:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
openssl req -new -key /path/to/certs/client.node.key -out client.node.csr -batch -subj '/O=Acme Inc/OU=movr-prod/UID=node'
```

A similar command can be used to generate a certificate for the `root` user.

### Step 3. Set the `SUBJECT` role option using `CREATE ROLE` or `ALTER ROLE` to match your certificates

You can associate an [X.509](https://en.wikipedia.org/wiki/X.509) certificate's Subject with a <InternalLink path="security-reference/authorization#roles">role</InternalLink> 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.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE ROLE maxroach WITH SUBJECT 'CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry' LOGIN;
```

Alternatively, you can update existing users with <InternalLink path="alter-role#set-the-subject-role-option-for-certificate-based-authentication">`ALTER ROLE ... SUBJECT`</InternalLink>.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER ROLE maxroach WITH SUBJECT 'CN=myName2,OU=myOrgUnit2,O=myOrg2,L=myLocality2,ST=myState2,C=myCountry2' LOGIN;
```

Note that `ALTER ROLE ... SUBJECT` cannot be applied to the `root` user. You must use `cockroach start --root-cert-distinguished-name` instead.

```
ERROR: role "root" cannot have a SUBJECT%!(EXTRA string=use the --%s CLI flag to configure root, string=root-cert-distinguished-name)
SQLSTATE: 22023
```

If you do not have an <InternalLink path="licensing-faqs">enterprise license</InternalLink>, the following error is signaled:

```
ERROR: use of SUBJECT role option requires an enterprise license. see https://cockroachlabs.com/pricing for details on how to enable enterprise features
SQLSTATE: XXC02
```

### Step 4. Enable the cluster setting to require the Subject field in certificates

Once the cluster is started, enable the following <InternalLink path="cluster-settings">cluster setting</InternalLink>:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING security.client_cert.subject_required.enabled = true;
```

When this setting is enabled, users who don't have a `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 `root` user, that the distinguished name in the certificate Subject matches the distinguished name fields passed in via `cockroach start --root-cert-distinguished-name`.
* For the `node` user, that the distinguished name in the certificate Subject matches the distinguished name fields passed in via `cockroach start --node-cert-distinguished-name`.
* For all other SQL users, that the values in the Subject field of the [X.509 certificate](https://en.wikipedia.org/wiki/X.509) match the values attached to the user or role with `CREATE ROLE ... SUBJECT` or `ALTER 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 map user identity to `SAN` fields instead of the default `CN` lookup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING security.client_cert.san_required.enabled = true;
```

## See also

* <InternalLink path="alter-role#set-the-subject-role-option-for-certificate-based-authentication">`ALTER ROLE ... SUBJECT`</InternalLink>
* <InternalLink path="create-role#set-the-subject-role-option-for-certificate-based-authentication">`CREATE ROLE ... SUBJECT`</InternalLink>
* <InternalLink path="authentication">Authenticate to CockroachDB self-hosted Clusters</InternalLink>
* <InternalLink path="gssapi_authentication">GSSAPI Authentication</InternalLink>
* <InternalLink path="security-reference/authentication">SQL Authentication</InternalLink>
* <InternalLink path="cloud-storage-authentication">Cloud Storage Authentication</InternalLink>
* <InternalLink path="cluster-settings">Cluster Settings</InternalLink>
* <InternalLink path="cockroach-start">`cockroach start`</InternalLink>
* <InternalLink path="cockroach-cert">`cockroach cert`</InternalLink>
* <InternalLink path="cockroach-auth-session">`cockroach auth-session`</InternalLink>