Upgrade from Keyfile Authentication to x.509 Authentication

To upgrade clusters that are currently using keyfile authentication to x.509 authentication, use the followingrolling upgrade processes.

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.

Upgrade Procedures (Using tls Options)

Note

Starting in version 4.2, MongoDB provides net.tls settings (andcorresponding —tls command-line options) that corresponds tothe net.ssl settings (and their corresponding —sslcommand-line options). The new tls settings/options provideidentical functionality as the ssl settings/options sinceMongoDB has always supported TLS 1.0 and later.

The procedures in this section use the tls settings/options. Forprocedures using the ssl settings/options, see Upgrade Procedures (Using ssl Options).

Upgrade (Using tls Options) Clusters Using TLS/SSL and Keyfile

Note

The procedure uses the tls settings/options. For proceduresusing the ssl settings/options, seeClusters Currently Using TLS/SSL (Using ssl Options).

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

  • For each member of a cluster, add the following settings to theconfiguration file and restart:

      • security.clusterAuthMode
      • Set to sendKeyFile. With this setting value, each node continuesto send its keyfile to authenticate itself as a member.However, each node can receive either a keyfile or an x.509certificate from other members to authenticate those members.
      • net.tls.clusterFile
      • Set to the appropriate path of the node’s certificate key filefor membership authentication. Themongod/mongos presents this fileto other members of the cluster to identify itself as a member.Include other TLS/SSL options andany other options as appropriate for your specific configuration.

For example:

  1. net:
  2.    tls:
  3.       mode: requireTLS
  4.       certificateKeyFile: /etc/ssl/mongodb.pem
  5.       CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
  6.       clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
  7. security:
  8.    clusterAuthMode: sendKeyFile
  9.    keyFile: /my/securely/located/membershipkey
  10. replication:
  11.    replSetName: myReplicaSet
  12. net:
  13.    bindIp: localhost,mongodb0.example.net
  14.    port: 27017
  15. systemLog:
  16.    destination: file
  17.    path: "/var/log/mongodb/mongod.log"
  18.    logAppend: true
  19. storage:
  20.    dbPath: "/var/lib/mongodb"
  21. processManagement:
  22.    fork: true

Update all nodes of the cluster to include thesecurity.clusterAuthMode andnet.tls.clusterFile settings before continuing.

  1. db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

With sendX509, each node sends itsnet.tls.clusterFile to authenticate itself as a member.However, each node can receive either a keyfile or an x.509certificate from other members to authenticate those members.

Upgrade all nodes of the cluster to this setting before continuing.

  • Optional but recommended. Finally, for each node of the cluster,connect to the node and use the setParameter command toupdate the clusterAuthMode to x509 to only use thex.509 certificate for authentication. [1]
  1. db.adminCommand( { setParameter: 1, clusterAuthMode: "x509" } )
  • After the upgrade of all nodes, edit the configuration file with the appropriate x.509settings to ensure that upon subsequent restarts, the cluster usesx.509 authentication. For example:
  1. net:
  2.    tls:
  3.       mode: requireTLS
  4.       certificateKeyFile: /etc/ssl/mongodb.pem
  5.       CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
  6.       clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
  7. security.clusterAuthMode: x509
  8. replication:
  9.    replSetName: myReplicaSet
  10. net:
  11.    bindIp: localhost,mongodb0.example.net
  12.    port: 27017
  13. systemLog:
  14.    destination: file
  15.    path: "/var/log/mongodb/mongod.log"
  16.    logAppend: true
  17. storage:
  18.    dbPath: "/var/lib/mongodb"
  19. processManagement:
  20.    fork: true

See also

You can also configure mongod andmongos using command-line options instead of theconfiguration file:

Update (Using tls Options) Clusters Using Keyfile but Not TLS/SSL

Note

The procedure uses the tls options. For procedures using thessl settings/options, see Clusters Currently Not Using TLS/SSL (Using ssl Options).

For clusters using keyfile authentication but not TLS/SSL, to upgradeto x.509 membership authentication and TLS/SSL connections:

  • For each member of a cluster, add the following settings to theconfiguration file and restart:

      • net.tls.mode
      • Set to allowTLS. This value allows the node to acceptboth TLS/SSL and non-TLS/non-SSL incoming connections. Itsoutgoing connections do not use TLS/SSL.
      • net.tls.certificateKeyFile
      • Set to the path of the file that contains the TLS/SSLcertificate and key. Themongod/mongos presents this fileto its clients to establish the instance’s identity. Requiredwhen using TLS/SSL.
      • net.tls.clusterFile
      • Set to the appropriate path of the node’s certificate key filefor membership authentication. Themongod/mongos presents this fileto other members of the cluster to identify itself as a member.
      • net.tls.CAFile
      • Set to the path of the file that contains the certificatechain for verifying received certificates.
      • security.clusterAuthMode
      • Set to sendKeyFile. This allows each node continues tosend its keyfile to authenticate itself as a member. However,each node can receive either a keyfile or an x.509 certificatefrom other members to authenticate those members.Include other TLS/SSL options andany other options as appropriate for your specific configuration.

For example:

  1. net:
  2.    tls:
  3.       mode: allowTLS
  4.       certificateKeyFile: /etc/ssl/mongodb.pem
  5.       clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
  6.       CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
  7. security:
  8.    clusterAuthMode: sendKeyFile
  9.    keyFile: /my/securely/located/membershipkey
  10. replication:
  11.    replSetName: myReplicaSet
  12. net:
  13.    bindIp: localhost,mongodb0.example.net
  14.    port: 27017
  15. systemLog:
  16.    destination: file
  17.    path: "/var/log/mongodb/mongod.log"
  18.    logAppend: true
  19. storage:
  20.    dbPath: "/var/lib/mongodb"
  21. processManagement:
  22.    fork: true

Upgrade all nodes of the cluster to include net.tls.mode,net.tls.certificateKeyFile,net.tls.clusterFile, andsecurity.clusterAuthMode.

  • Connect to each node and use thesetParameter command [1] to:

    • Update the tlsModeto preferSSL. With the tlsMode set topreferTLS, the node accepts both TLS/SSL and non-TLS/non-SSLincoming connections, and its outgoing connections use TLS/SSL.
    • Update the clusterAuthMode to sendX509.With the clusterAuthMode set to sendX509, eachnode sends its net.tls.clusterFile to authenticateitself as a member. However, each node continues to accept eithera keyfile or an x.509 certificate from other members toauthenticate those members.
  1. db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } );
  2. db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } );

Upgrade all nodes of the cluster to these settings before continuing.

  • After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSL andx.509 settings to ensure that upon subsequent restarts, the clusteruses x.509 authentication.
  1. net:
  2.    tls:
  3.       mode: preferTLS
  4.       certificateKeyFile: /etc/ssl/mongodb.pem
  5.       clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
  6.       CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
  7. security:
  8.    clusterAuthMode: sendX509
  9. replication:
  10.    replSetName: myReplicaSet
  11. net:
  12.    bindIp: localhost,mongodb0.example.net
  13.    port: 27017
  14. systemLog:
  15.    destination: file
  16.    path: "/var/log/mongodb/mongod.log"
  17.    logAppend: true
  18. storage:
  19.    dbPath: "/var/lib/mongodb"
  20. processManagement:
  21.    fork: true

Note

At this point,

  • The nodes in the cluster use TLS/SSL connections. However, thenodes can accept non-TLS/SSL connections from clientapplications.
  • The nodes send their x.509 certificates for membershipauthentication, but can accept either x.509 certificates orkeyfiles from other nodes to verify the other nodes’ membership.To enforce TLS/SSL connections from client applications as wellas only accept x.509 for membership authentication, see next step.
  • Optional but recommended. Update all nodes to use only TLS/SSLconnections and only x.509 certificate for membership authentication.

Important

This TLS/SSL connection requirement applies to all connections;that is, with the clients as well as with the members of thecluster. That is, clients must specify TLS/SSL connections andpresents its certificate key file when connecting to the cluster.See Connect to MongoDB Instance that Requires Client Certificates (tls Options) for moreinformation on connecting with TLS/SSL. See alsoValidate Only if a Client Presents a Certificate.

Update the net.tls.mode to requireTLS andsecurity.clusterAuthMode to x509.

For example:

  1. net:
  2.    tls:
  3.       mode: requireTLS
  4.       certificateKeyFile: /etc/ssl/mongodb.pem
  5.       clusterFile: "/etc/ssl/myReplMembershipCertificateKeyFile.pem"
  6.       CAFile: /etc/ssl/caToValidateReceivedCertificates.pem
  7. security:
  8.    clusterAuthMode: x509
  9. replication:
  10.    replSetName: myReplicaSet
  11. net:
  12.    bindIp: localhost,mongodb0.example.net
  13.    port: 27017
  14. systemLog:
  15.    destination: file
  16.    path: "/var/log/mongodb/mongod.log"
  17.    logAppend: true
  18. storage:
  19.    dbPath: "/var/lib/mongodb"
  20. processManagement:
  21.    fork: true

See also

You can also configure mongod andmongos using command-line options instead of theconfiguration file:

Upgrade Procedures (Using ssl Options)

Note

Starting in version 4.2, MongoDB provides net.tls settings (andcorresponding command-line options) that corresponds to thenet.ssl settings (and their corresponding command-line options).The tls settings/options provide identical functionality asthe ssl settings/options since MongoDB has always supported TLS1.0 and later.

The procedures in this section use the ssl options. Forprocedures using the tls options, seeUpgrade Procedures (Using tls Options).

Clusters Currently Using TLS/SSL (Using ssl Options)

Note

The procedure uses the ssl options. For procedures using thetls options (available starting in MongoDB 4.2), seeClusters Currently Using TLS/SSL (Using ssl Options).

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

  • 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’scertificate. Include other TLS/SSL options as well as any other options that arerequired for your specific configuration. For example:
  1. mongod --replSet <name> --sslMode requireSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to TLS/SSL Certificate and key PEM file>  --sslCAFile <path to root CA PEM file> --bind_ip localhost,<hostname(s)|ip address(es)>

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

  1. db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )

With this setting, each node uses its x.509 certificate, specifiedwith the —sslClusterFile option in the previous step, toauthenticate itself as a member. However, each node continues toaccept either a keyfile or an x.509 certificate from other membersto authenticate those members. Upgrade all nodes of the cluster tothis setting.

  • Optional but recommended. Finally, for each node of the cluster,connect to the node and use the setParameter command toupdate the clusterAuthMode to x509 to only use thex.509 certificate for authentication. [1]For example:
  1. db.adminCommand( { setParameter: 1, clusterAuthMode: "x509" } )
  • After the upgrade of all nodes, edit the configuration file with the appropriate x.509settings to ensure that upon subsequent restarts, the cluster usesx.509 authentication.

See —clusterAuthMode for the various modes and theirdescriptions.

Clusters Currently Not Using TLS/SSL (Using ssl Options)

Note

The procedure uses the ssl options. For procedures using thetls options (available starting in MongoDB 4.2), seeUpdate (Using tls Options) Clusters Using Keyfile but Not TLS/SSL.

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

  • 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’scertificate. Include other TLS/SSL options as well as any other options that arerequired for your specific configuration. For example:
  1. mongod --replSet <name> --sslMode allowSSL --clusterAuthMode sendKeyFile --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip localhost,<hostname(s)|ip address(es)>

The —sslMode allowSSL setting allows thenode to accept both TLS/SSL and non-TLS/non-SSL incoming connections. Itsoutgoing connections do not use TLS/SSL.

The —clusterAuthMode sendKeyFilesetting allows each node continues to use its keyfile toauthenticate itself as a member. However, each node can now accepteither a keyfile or an x.509 certificate from other members toauthenticate those members.

Upgrade all nodes of the cluster to these settings.

  1. db.adminCommand( { setParameter: 1, sslMode: "preferSSL", clusterAuthMode: "sendX509" } )

With the sslMode set to preferSSL, the node acceptsboth TLS/SSL and non-TLS/non-SSL incoming connections, and its outgoingconnections use TLS/SSL.

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

Upgrade all nodes of the cluster to these settings.

  • Optional but recommended. Finally, for each node of the cluster,connect to the node and use the setParameter command toupdate the sslMode to requireSSL and theclusterAuthMode to x509. [1]For example:
  1. db.adminCommand( { setParameter: 1, sslMode: "requireSSL", clusterAuthMode: "x509" } )

With the sslMode set to requireSSL, the node only usesTLS/SSLs connections.

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

  • After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSL andx.509 settings to ensure that upon subsequent restarts, the clusteruses x.509 authentication.

See —clusterAuthMode for the various modes and theirdescriptions.

[1](1, 2, 3, 4, 5, 6, 7) As an alternative to using thesetParameter command, you can alsorestart the nodes with the appropriate TLS/SSL and x509 options andvalues.