Use x.509 Certificates to Authenticate Clients

Note

Starting in version 4.0, MongoDB disables support for TLS 1.0encryption on systems where TLS 1.1+ is available. Formore details, see Disable TLS 1.0.

MongoDB supports x.509 certificate authentication for use with a secureTLS/SSL connection. The x.509 clientauthentication allows clients to authenticate to servers withcertificates rather than with a usernameand password. The following tutorial outlines the steps to use x.509for client authentication with a standalone mongod instance.

To use x.509 authentication for replica sets or sharded clusters, seeUse x.509 Certificate for Membership Authentication.

Prerequisites

Important

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 certificatesgenerated and signed by a single certificate authority. You or yourorganization can generate and maintain an independent certificateauthority, or use certificates generated by a third-party TLS/SSLvendor. Obtaining and managing certificates is beyond the scope ofthis documentation.

Important

To use x.509 authentication, —tlsCAFile or net.tls.CAFilemust be specified unless using —tlsCertificateSelector or—net.tls.certificateSelector. Or if using the ssl aliases,—sslCAFile or net.ssl.CAFile must be specified unless using—sslCertificateSelector or net.ssl.certificateSelector.

Client x.509 Certificate

Note

You must have valid x.509 certificates.

Starting in MongoDB 4.0, if you specify—sslAllowInvalidCertificates ornet.ssl.allowInvalidCertificates: true (or in MongoDB 4.2, thealias —tlsAllowInvalidateCertificates ornet.tls.allowInvalidCertificates: true) when using x.509authentication, an invalid certificate is only sufficient toestablish a TLS/SSL connection but is insufficient forauthentication.

The client certificate must have the followingproperties:

• A single Certificate Authority (CA) must issue the certificatesfor both the client and the server.

• Client certificates must contain the following fields:

keyUsage = digitalSignature
extendedKeyUsage = clientAuth

• Each unique MongoDB user must have a unique certificate.

• A client x.509 certificate’s subject, which contains theDistinguished Name (DN), must differ from that of aMember x.509 Certificate. Specifically, the subjects mustdiffer with regards to at least one of the following attributes:Organization (O), the Organizational Unit (OU) or theDomain Component (DC).

If the MongoDB deployment hastlsX509ClusterAuthDNOverride set (available startingin MongoDB 4.2), the client x.509 certificate’s subject must alsodiffer from that value.

Warning

If a client x.509 certificate’s subject has the same O,OU, and DC combination as theMember x.509 Certificate (ortlsX509ClusterAuthDNOverride if set), the clientwill be identified as a cluster member and granted fullpermission on the system.

MongoDB Deployment Configured for x.509 (Using TLS Options)

Note

The procedures in this section use the tls settings/option(Available in MongoDB 4.2). For procedures using their sslaliases, see MongoDB Deployment Configured for x.509 (Using SSL Options).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

• Command-Options
• Configuration File

You can configure a mongod instancefor x.509 authentication from the command-line. For example,to configure a standalone mongod instance:

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. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

The x.509 configuration requires:

You can configure mongod for x.509authentication in the configuration file. For example, toconfigure a standalone mongod instance:

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 requiredfor your configuration. For instance, if you wish remote clients toconnect to your deployment or your deployment members are run ondifferent hosts, specify the net.bindIp setting. For moreinformation, see Localhost Binding Compatibility Changes.

The x.509 configuration requires:

To set up x.509 authentication for replica sets or sharded clusters,see Use x.509 Certificate for Membership Authentication.

MongoDB Deployment Configured for x.509 (Using SSL Options)

Note

The procedures in this section use the ssl settings/option. Forprocedures using their tls aliases (Available in MongoDB 4.2),see MongoDB Deployment Configured for x.509 (Using TLS Options).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

• Command-Options
• Configuration File

You can configure a mongod instancefor x.509 authentication from the command-line. For example,to configure a standalone mongod instance:

mongod --sslMode requireSSL --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>  --bind_ip <hostnames>

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

The x.509 configuration for a standalone requires:

You can configure mongodfor x.509 authentication in the configuration file. For example,to configure a standalone mongod instance:

net:
   ssl:
      mode: requireSSL
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Include additional options as requiredfor your configuration. For instance, if you wish remote clients toconnect to your deployment or your deployment members are run ondifferent hosts, specify the net.bindIp setting. For moreinformation, see Localhost Binding Compatibility Changes.

The x.509 configuration for a standalone requires:

To set up x.509 authentication for replica sets or sharded clusters,see Use x.509 Certificate for Membership Authentication.

Procedures

Add x.509 Certificate subject as a User

To authenticate with a client certificate, you must first add the valueof the subject from the client certificate as a MongoDB user to the$external database. Each unique x.509 client certificatecorresponds to a single MongoDB user; i.e. you cannot use a singleclient certificate to authenticate more than one MongoDB user.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

Note

The RDNs in the subject string must be compatible with theRFC2253 standard.

• You can retrieve the RFC2253 formatted subject from the clientcertificate with the following command:

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

The command returns the subject string as well as certificate:

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

• Add the RFC2253 compliant value of the subject as a user.Omit spaces as needed.

For example, the following 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 for details on adding a userwith roles.

Authenticate with a x.509 Certificate (Using tls Options)

Note

The procedures in this section use the tls settings/option(Available in MongoDB 4.2). For procedures using their sslaliases, see Authenticate with a x.509 Certificate (Using ssl Options).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

After you have added the x.509 client certificate subject as acorresponding MongoDB user, you canauthenticate with the client certificate.

• Connect with Authentication
• Authenticate after Connection

To authenticate during connection:

mongo --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 afterconnection.

For example, if using the mongo shell,

• Connect mongo shell to the mongod set up forTLS/SSL:

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

OptionNotes—tls —tlsCertificateKeyFileClient’s x.509 file.—tlsCAFileCertificate Authority file to verify thecertificate presented bymongod/mongosinstance.

• To perform the authentication, use the db.auth() method inthe $external database. For the mechanismfield, specify "MONGODB-X509".

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

Authenticate with a x.509 Certificate (Using ssl Options)

Note

The procedures in this section use the ssl settings/options. Forprocedures using their tls (Available in MongoDB 4.2) aliases,see Authenticate with a x.509 Certificate (Using tls Options).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

After you have added the x.509 client certificate subject as acorresponding MongoDB user, you canauthenticate with the client certificate.

• Connect with Authentication
• Authenticate after Connection

To authenticate during connection:

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>  --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509

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

For example, if using the mongo shell,

• Connect mongo shell to the mongod set up forTLS/SSL:

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>

OptionNotes—ssl —sslPEMKeyFileClient’s x.509 file.—sslCAFileCertificate Authority file to verify thecertificate presented bymongod/mongosinstance.

• To perform the authentication, use the db.auth() method inthe $external database. For the mechanismfield, specify "MONGODB-X509".

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