> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# x.509

MongoDB supports X.509 certificate authentication for client authentication and internal authentication of the members of replica sets and sharded clusters.

X.509 certificate authentication requires a secure [TLS/SSL connection.](https://www.mongodb.com/docs/manual/tutorial/configure-ssl.md)

## Certificate Authority

For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by third-party TLS vendors. Obtaining and managing certificates is beyond the scope of this documentation.

## Client X.509 Certificates

To authenticate to servers, clients can use X.509 certificates instead of usernames and passwords.

### Client Certificate Requirements

Client certificate requirements:

- A single Certificate Authority (CA) must issue the certificates for both the client and the server.

- Each unique MongoDB user must have a unique certificate.

- The X.509 certificate must *not* be expired.

  **Note:**

  [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) / [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) logs a warning on connection if the presented X.509 certificate expires within `30` days of the `mongod/mongos` host system time.

- Client certificates must contain the following fields:

  ```none
  keyUsage = digitalSignature
  extendedKeyUsage = clientAuth
  ```

- At least one of the following client certificate attributes must be **different** than the attributes in both the [`net.tls.clusterFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.clusterFile) and [`net.tls.certificateKeyFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile) server certificates:

  - Organization (`O`)

  - Organizational Unit (`OU`)

  - Domain Component (`DC`)

  **Note:**

  You can also disable the `enforceUserClusterSeparation` parameter during startup to automatically disable the `O/OU/DC` check. This allows member certificates to authenticate as users stored in the `$external` database.

- The `subject` of a client X.509 certificate, which contains the Distinguished Name (`DN`), must be **different** than the `subject`s of [member X.509 certificates](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md#std-label-x509-member-certificate). If the MongoDB deployment has [`tlsX509ClusterAuthDNOverride`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.tlsX509ClusterAuthDNOverride) set, the client X.509 certificate's subject must not match that value.

  **Important:**

  If a client X.509 certificate's subject matches the `O`, `OU`, and `DC` attributes of the [Member X.509 Certificate](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md#std-label-x509-member-certificate) (or [`tlsX509ClusterAuthDNOverride`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.tlsX509ClusterAuthDNOverride), if set) exactly, the client connection is accepted, full permissions are granted, and a warning message appears in the log.

  Only [cluster member x509 certificates](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md#std-label-x509-member-certificate) should use the same `O`, `OU`, and `DC` attribute combinations.

### MongoDB User and `$external` Database

To authenticate with a client certificate, you must first add the client certificate's `subject` as a MongoDB user in the `$external` database. The `$external` database is the [Authentication Database](https://www.mongodb.com/docs/manual/core/security-users.md#std-label-authentication-database) for the user.

Each unique X.509 client certificate is for one MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user.

To use [Client Sessions and Causal Consistency Guarantees](https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency.md#std-label-sessions) with `$external` authentication users (Kerberos, LDAP, or X.509 users), usernames cannot be greater than 10k bytes.

### TLS Connection X509 Certificate Startup Warning

Starting in MongoDB 5.0, [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) now issue a startup warning when their certificates do not include a [Subject Alternative Name](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-Subject-Alternative-Name) attribute.

The following platforms do not support common name validation:

- iOS 13 and higher

- MacOS 10.15 and higher

- Go 1.15 and higher

Clients using these platforms will not [authenticate](https://www.mongodb.com/docs/manual/tutorial/configure-x509-client-authentication.md#std-label-x509-client-authentication) to MongoDB servers that use X.509 certificates whose hostnames are [specified by CommonName attributes.](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-label-KMIP-subject-alternative-name-CN)

## Member X.509 Certificates

For internal authentication between members of sharded clusters and replica sets, you can use X.509 certificates instead of [keyfiles.](https://www.mongodb.com/docs/manual/tutorial/deploy-sharded-cluster-with-keyfile-access-control.md)

### Member Certificate Requirements

When TLS is enabled, use member certificates to verify membership to internal connections in a sharded cluster or a replica set. You can configure member certificate file paths with the [`net.tls.clusterFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.clusterFile) and [`net.tls.certificateKeyFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile) options. Members have the following configuration requirements:

- Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:

  - the Organization (`O`)

  - the Organizational Unit (`OU`)

  - the Domain Component (`DC`)

  MongoDB verifies that entries match exactly across all member certificates. If you list multiple `OU` values, all certificates must use an identical list.

  You can specify alternative attributes to use for authentication by setting [`net.tls.clusterAuthX509.extensionValue`.](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.clusterAuthX509.extensionValue)

- Cluster member configuration must include the same [`net.tls.clusterAuthX509.attributes`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.clusterAuthX509.attributes) and use matching values. Attribute order doesn't matter. The following example sets `O` and `OU`, but not `DC`:

  ```yaml
  net:
    tls:
      clusterAuthX509:
        attributes: O=MongoDB, OU=MongoDB Server
  ```

**Note:**

If you set the `enforceUserClusterSeparation` parameter to `false`, the following behaviors apply:

- You cannot set `clusterAuthMode` to an option that allows X.509 or the server will not start. The server will only start if `clusterAuthMode` is `keyFile`.

- A client can create a user in the `$external` database whose `O/OU/DC` attributes match the server's configured attributes for cluster membership.

- A client presenting a member certificate can now attempt [MONGODB-X509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509) authentication as a user in the `$external` database.

To set the `enforceUserClusterSeparation` parameter to `false`, run the following command during startup:

```javascript
mongod --setParameter enforceUserClusterSeparation=false
```

The certificates have the following requirements:

- A single Certificate Authority (CA) must issue all X.509 certificates for the members of a sharded cluster or a replica set.

- At least one of the Subject Alternative Name (`SAN`) entries must match the server hostname used by other cluster members. When comparing `SAN`s, MongoDB can compare either DNS names or IP addresses.

  If you don't specify `subjectAltName`, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per [RFC2818](https://datatracker.ietf.org/doc/html/rfc2818)

Key Usage and Extended Key Usage are X.509 extensions that strictly define and restrict the use of the key associated with a certificate. Both of these extensions are optional. If `tlsCertificateKeyFile` or `tlsClusterFile` point to certificates that omit these extensions, no restrictions apply to using the certificate.

If X.509 certificates used for `tlsCertificateKeyFile` or `tlsClusterFile` include the Extended Key Usage (EKU) extension, they must comply with the following rules:

- `tlsCertificateKeyFile` must include `serverAuth` in EKU.

  ```none
  extendedKeyUsage = serverAuth
  ```

- `tlsClusterFile` must include `clientAuth` in EKU:

  ```none
  extendedKeyUsage = clientAuth
  ```

- If `tlsClusterFile` is omitted and only `tlsCertificateKeyFile` is configured, then `tlsCertificateKeyFile` must include both `serverAuth` and `clientAuth` in EKU:

  ```none
  extendedKeyUsage = clientAuth, serverAuth
  ```

If X.509 certificates used for `tlsCertificateKeyFile` or `tlsClusterFile` include the Key Usage (KU) extension, set it as follows:

- `tlsCertificateKeyFile` should contain `digitalSignature`, `keyEncipherment`, and `keyAgreement` in its KU extension:

  ```none
  keyUsage = digitalSignature, keyEncipherment, keyAgreement
  ```

- `tlsClusterFile` should contain `digitalSignature` in its KU extension:

  ```none
  keyUsage = digitalSignature
  ```

### MongoDB Configuration for Membership Authentication

You can use TLS for internal authentication between each member of your replica set (each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance) or sharded cluster (each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance).

To use TLS for internal authentication, use the following settings:

- [`security.clusterAuthMode`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-security.clusterAuthMode) or [`--clusterAuthMode`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--clusterAuthMode) set to `x509`

- [`net.tls.clusterFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.clusterFile) or [`--tlsClusterFile`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--clusterAuthMode)

**Important:**

If you set [`--tlsMode`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsMode)  to any value other than `disabled`, MongoDB uses the certificate specified in [`net.tls.certificateKeyFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile) for both server and client authentication in internal replica set connections. This certificate setting applies regardless of whether you set [`security.clusterAuthMode`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-security.clusterAuthMode) to `X.509`.

[`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#std-option-mongos.--tlsCertificateKeyFile) instances use their certificate key files to prove their identity to clients, but certificate key files can also be used for membership authentication. If you do not specify a cluster file, members use their certificate key files for membership authentication. Specify the certificate key file with [`net.tls.certificateKeyFile`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile) or [`--tlsCertificateKeyFile`.](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsCertificateKeyFile)

To use the certificate key file for both client authentication and membership authentication, the certificate must either:

- Omit `extendedKeyUsage` or

- Specify `extendedKeyUsage = serverAuth, clientAuth`