> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Use X.509 to Authenticate Clients on Self-Managed MongoDB The following procedure sets up X.509 certificate authentication for client authentication on a standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. This is also known as Mutual TLS or mTLS. To use X.509 authentication for replica sets or sharded clusters, see [Verify Cluster Membership with X.509 on Self-Managed MongoDB.](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md) ## Prerequisites A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, in particular X.509 certificates, and Certificate Authority is beyond the scope of this document. This tutorial assumes prior knowledge of TLS/SSL as well as access to valid X.509 certificates. ### 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. To use X.509 authentication, `--tlsCAFile` or `net.tls.CAFile` must be specified unless you are using `--tlsCertificateSelector` or `--net.tls.certificateSelector`. ### Client X.509 Certificate You must have valid X.509 certificates. The client X.509 certificates must meet the [client certificate requirements.](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-client-x509-certificates-requirements) If you specify `--tlsAllowInvalidCertificates` or `net.tls.allowInvalidCertificates: true`, an invalid certificate is sufficient only to establish a TLS connection but it is *insufficient* for authentication. ## Procedure 1. Deploy with X.509 Authentication ### Command Options You can configure a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance for X.509 authentication from the command-line. To configure a standalone [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance, run the following command: ```bash mongod --tlsMode requireTLS \ --tlsCertificateKeyFile \ --tlsCAFile --bind_ip ``` Include additional options as required for your configuration. The X.509 configuration requires: | Option | Notes | | --- | --- | | [`--tlsMode`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsMode) | Specify `requireTLS`. | | [`--tlsCertificateKeyFile`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsCertificateKeyFile) | Specify the instance's X.509 certificate to present to clients. | | [`--tlsCAFile`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsCAFile) | Specify the Certificate Authority file to verify the certificates presented to the instance. | To set up X.509 authentication for replica sets or sharded clusters, see [Verify Cluster Membership with X.509 on Self-Managed MongoDB.](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md#std-label-x509-internal-authentication) 2. Add X.509 Certificate `subject` as a User To authenticate with a client certificate, you must first add the value of the `subject` from the client certificate as a MongoDB user to the `$external` database. Each unique X.509 client certificate corresponds to a single MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user. **Note: Username Requirements** - 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. - The RDNs in the `subject` string must be compatible with the [RFC2253](https://www.ietf.org/rfc/rfc2253.txt) standard. 1. You can retrieve the `RFC2253` formatted `subject` from the client certificate with the following command: ```bash openssl x509 -in -inform PEM -subject -nameopt RFC2253 ``` The command returns the `subject` string and the certificate: ```bash subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry -----BEGIN CERTIFICATE----- # ... -----END CERTIFICATE----- ``` 2. Add the `RFC2253` compliant value of the `subject` as a user. Omit spaces as needed. The following example adds a user and grants the user [`readWrite`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-readWrite) role in the `test` database and the [`userAdminAnyDatabase`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-userAdminAnyDatabase) role: ```javascript db.getSiblingDB("$external").runCommand( { createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", roles: [ { role: "readWrite", db: "test" }, { role: "userAdminAnyDatabase", db: "admin" } ], writeConcern: { w: "majority" , wtimeout: 5000 } } ) ``` See [Manage Users and Roles on Self-Managed Deployments](https://www.mongodb.com/docs/manual/tutorial/manage-users-and-roles.md) for details on adding a user with roles. 3. Authenticate with a X.509 Certificate After you have [added the X.509 client certificate subject as a corresponding MongoDB user](https://www.mongodb.com/docs/manual/tutorial/configure-x509-client-authentication.md#std-label-addX509SubjectUser), you can authenticate with the client certificate: ### CLI Options To authenticate during connection, run the following command: ```bash mongosh --tls --tlsCertificateKeyFile \ --tlsCAFile \ --authenticationDatabase '$external' \ --authenticationMechanism MONGODB-X509 ``` | Option | Notes | | --- | --- | | [`--tls`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--tls) | | | [`--tlsCertificateKeyFile`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--tlsCertificateKeyFile) | Specify the client's X.509 file. | | [`--tlsCAFile`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--tlsCAFile) | Specify the Certificate Authority file to verify the certificate presented by the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. | | [`--authenticationDatabase`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--authenticationDatabase) | Specify `'$external'`. | | [`--authenticationMechanism`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--authenticationMechanism) | Specify `MONGODB-X509`. | ## Next Steps To use X.509 authentication for replica sets or sharded clusters, see [Verify Cluster Membership with X.509 on Self-Managed MongoDB.](https://www.mongodb.com/docs/manual/tutorial/configure-x509-member-authentication.md)