Use X.509 Certificates to Authenticate Clients on Self-Managed Deployments (original) (raw)

The following procedure sets up X.509 certificate authentication for client authentication on a standalone mongod instance. This is also known as Mutual TLS or mTLS.

To use X.509 authentication for replica sets or sharded clusters, seeUse X.509 Certificates for Membership Authentication with Self-Managed MongoDB.

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.

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.CAFilemust be specified unless you are using --tlsCertificateSelectoror --net.tls.certificateSelector.

You must have valid X.509 certificates. The client X.509 certificates must meet the client certificate requirements.

If you specify --tlsAllowInvalidCertificates ornet.tls.allowInvalidCertificates: true, an invalid certificate is sufficient only to establish a TLS connection but it is_insufficient_ for authentication.

You can configure a mongod instance for X.509 authentication from the command-line.

To configure a standalone mongod instance, run the following command:

mongod --tlsMode requireTLS \

    --tlsCertificateKeyFile <path to TLS/SSL certificate and key PEM file> \

    --tlsCAFile <path to root CA PEM file> --bind_ip <hostnames>

Include additional options as required for your configuration.

The X.509 configuration requires:

You can configure a mongod for X.509 authentication in the configuration file.

To configure a standalone mongod instance, add the following configuration options to your configuration file:

net:

   tls:

      mode: requireTLS

      certificateKeyFile: <path to TLS/SSL certificate and key PEM file>

      CAFile: <path to root CA PEM file>

Include additional options as required for your configuration.

The X.509 configuration requires:

To set up X.509 authentication for replica sets or sharded clusters, see Use X.509 Certificates for Membership Authentication with Self-Managed MongoDB.

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 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 theRFC2253 standard.

1. You can retrieve the RFC2253 formatted subject from the client certificate with the following command:

openssl x509 -in <pathToClientPEM> -inform PEM -subject -nameopt RFC2253  

The command returns the subject string and the certificate:

subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry  
-----BEGIN CERTIFICATE-----  
# ...  
-----END CERTIFICATE-----  

1. Add the RFC2253 compliant value of the subject as a user. Omit spaces as needed.
   The following example adds a user and grants the userreadWrite role in the test database and theuserAdminAnyDatabase role:

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 for details on adding a user with roles.

After you have added the X.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate:

To authenticate during connection, run the following command:

mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \

    --tlsCAFile <path to root CA PEM file> \

    --authenticationDatabase '$external' \

    --authenticationMechanism MONGODB-X509

You can connect without authentication and use thedb.auth() method to authenticate after connection.

For example, if using mongosh,

1. Connect mongosh to themongod:

mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \  
    --tlsCAFile <path to root CA PEM file>  

1. To authenticate, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509".

db.getSiblingDB("$external").auth(  
  {  
    mechanism: "MONGODB-X509"  
  }  
)  

To use X.509 authentication for replica sets or sharded clusters, seeUse X.509 Certificates for Membership Authentication with Self-Managed MongoDB.