OPTIONS

Authenticate with x.509 Certificate

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secure SSL connection. The x.509 authentication allows clients to authenticate to servers with certificates instead of with username and password. The x.509 authentication also allows sharded cluster members and replica set members to use x.509 certificates to verify their membership to the cluster or the replica set instead of using keyfiles. The membership authentication is an internal process.

Use x.509 for Client Authentication

Client x.509 Certificate

The client certificate must have the following properties:

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

  • Client certificates must contain the following fields:

    keyUsage = digitalSignature
    extendedKeyUsage = clientAuth
    

Configure MongoDB Server

Configure the MongoDB server from the command line, as in the following:

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

You may also specify these options in the configuration file:

sslMode = requireSSL
sslPEMKeyFile = <path to SSL certificate and key PEM file>
sslCAFile = <path to the root CA PEM file>

Include any additional options, SSL or otherwise, that are required for your specific configuration.

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.

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

    openssl x509 -in <pathToClient PEM> -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-----
    
  2. Add the value of the subject, omitting the spaces, from the certificate as a user.

    For example, in the mongo shell, to add the user with both the readWrite role in the test database and the userAdminAnyDatabase role which is defined only in the admin database:

    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 }
      }
    )
    

    In the above example, to add the user with the readWrite role in the test database, the role specification document specified 'test' in the db field. To add userAdminAnyDatabase role for the user, the above example specified 'admin' in the db field.

    Note

    Some roles are defined only in the admin database, including: clusterAdmin, readAnyDatabase, readWriteAnyDatabase, dbAdminAnyDatabase, and userAdminAnyDatabase. To add a user with these roles, specify 'admin' in the db.

See Add a User to a Database for details on adding a user with roles.

Authenticate with a x.509 Certificate

To authenticate with a client certificate, you must first add a MongoDB user that corresponds to the client certificate. See Add x.509 Certificate subject as a User.

To authenticate, use the db.auth() method in the $external database, specifying "MONGODB-X509" for the mechanism field, and the user that corresponds to the client certificate for the user field.

For example, if using the mongo shell,

  1. Connect mongo shell to the mongod set up for SSL:

    mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file>
    
  2. To perform the authentication, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509", and for the user field, specify the user, or the subject, that corresponds to the client certificate.

    db.getSiblingDB("$external").auth(
      {
        mechanism: "MONGODB-X509",
        user: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry"
      }
    )
    

Use x.509 for Replica Set/Sharded Cluster Member Authentication

Member x.509 Certificate

The member certificate, used for internal authentication to verify membership to the sharded cluster or a replica set, must have the following properties:

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

  • The Distinguished Name (DN), found in the member certificate’s subject, must specify a non-empty value for at least one of the following attributes: Organization (O), the Organizational Unit (OU) or the Domain Component (DC).

  • The Organization attributes (O‘s), the Organizational Unit attributes (OU‘s), and the Domain Components (DC‘s) must match those from the certificates for the other cluster members. To match, the certificate must match all specifications of these attributes, or even the non-specification of these attributes. The order of the attributes does not matter.

    In the following example, the two DN‘s contain matching specifications for O, OU as well as the non-specification of the DC attribute.

    CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
    C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2
    

    However, the following two DN‘s contain a mismatch for the OU attribute since one contains two OU specifications and the other, only one specification.

    CN=host1,OU=Dept1,OU=Sales,O=MongoDB
    CN=host2,OU=Dept1,O=MongoDB
    
  • Either the Common Name (CN) or one of the Subject Alternative Name (SAN) entries must match the hostname of the server, used by the other members of the cluster.

    For example, the certificates for a cluster could have the following subjects:

    subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
    subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
    subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US
    

Configure Clusters

To specify the x.509 certificate for internal cluster member authentication, append the additional SSL options --clusterAuthMode and --sslClusterFile, as in the following example for a member of a replica set:

mongod --replSet <name> --sslMode requireSSL --clusterAuthMode x509 --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>

Include any additional options, SSL or otherwise, that are required for your specific configuration. For instance, if the membership key is encrypted, set the --sslClusterPassword to the passphrase to decrypt the key or have MongoDB prompt for the passphrase. See SSL Certificate Passphrase for details.

Note

You may also specify these options in the configuration file, as in the following example:

sslMode = requireSSL
sslPEMKeyFile = <path to SSL certificate and key PEM file>
sslCAFile = <path to root CA PEM file>
clusterAuthMode = x509
sslClusterFile = <path to membership certificate and key PEM file>

Upgrade from Keyfile Authentication to to x.509 Authentication

To upgrade clusters that are currently using keyfile authentication to x.509 authentication, use a rolling upgrade process.

Clusters Currently Using SSL

For clusters using SSL and keyfile authentication, to upgrade to x.509 cluster authentication, use the following rolling upgrade process:

  1. For each node of a cluster, start the node with the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node’s certificate. Include other SSL options as well as any other options that are required for your specific configuration. For example:

    mongod --replSet <name> --sslMode requireSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL Certificate and key PEM file>  --sslCAFile <path to root CA PEM file>
    

    With this setting, each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

  2. Then, for each node of a cluster, connect to the node and use the setParameter command to update the clusterAuthMode to sendX509. [1] For example,

    db.getSiblingDB('admin').runCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )
    

    With this setting, each node uses its x.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.

  3. Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the clusterAuthMode to x509 to only use the x.509 certificate for authentication. [1] For example:

    db.getSiblingDB('admin').runCommand( { setParameter: 1, clusterAuthMode: "x509" } )
    
  4. After the upgrade of all nodes, edit the configuration file with the appropriate x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

Clusters Currently Not Using SSL

For clusters using keyfile authentication but not SSL, to upgrade to x.509 authentication, use the following rolling upgrade process:

  1. For each node of a cluster, start the node with the option --sslMode set to allowSSL, the option --clusterAuthMode set to sendKeyFile and the option --sslClusterFile set to the appropriate path of the node’s certificate. Include other SSL options as well as any other options that are required for your specific configuration. For example:

    mongod --replSet <name> --sslMode allowSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL certificate and key PEM file>  --sslCAFile <path to root CA PEM file>
    

    The --sslMode allowSSL setting allows the node to accept both SSL and non-SSL incoming connections. Its outgoing connections do not use SSL.

    The --clusterAuthMode sendKeyFile setting allows each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members.

    Upgrade all nodes of the cluster to these settings.

  2. Then, for each node of a cluster, connect to the node and use the setParameter command to update the sslMode to preferSSL and the clusterAuthMode to sendX509. [1] For example:

    db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "preferSSL", clusterAuthMode: "sendX509" } )
    

    With the sslMode set to preferSSL, the node accepts both SSL and non-SSL incoming connections, and its outgoing connections use SSL.

    With the clusterAuthMode set to sendX509, each node uses its x.509 certificate, specified with the --sslClusterFile option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members.

    Upgrade all nodes of the cluster to these settings.

  3. Optional but recommended. Finally, for each node of the cluster, connect to the node and use the setParameter command to update the sslMode to requireSSL and the clusterAuthMode to x509. [1] For example:

    db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "requireSSL", clusterAuthMode: "x509" } )
    

    With the sslMode set to requireSSL, the node only uses SSL connections.

    With the clusterAuthMode set to x509, the node only uses the x.509 certificate for authentication.

  4. After the upgrade of all nodes, edit the configuration file with the appropriate SSL and x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.

See --clusterAuthMode for the various modes and their descriptions.

[1](1, 2, 3, 4) As an alternative to using the setParameter command, you can also restart the nodes with the appropriate SSL and x509 options and values.