Navigation
This version of the documentation is archived and no longer supported.

Upgrade from Keyfile Authentication to x.509 Authentication

On this page

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

Clusters Currently Using TLS/SSL

For clusters using TLS/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 TLS/SSL options as well as any other options that are required for your specific configuration. For example:

    copy 
    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>

    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,

    copy 
    db.adminCommand( { 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:

    copy 
    db.adminCommand( { 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 TLS/SSL

For clusters using keyfile authentication but not TLS/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 TLS/SSL options as well as any other options that are required for your specific configuration. For example:

    copy 
    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>

    The --sslMode allowSSL setting allows the node to accept both TLS/SSL and non-TLS/non-SSL incoming connections. Its outgoing connections do not use TLS/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:

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

    With the sslMode set to preferSSL, the node accepts both TLS/SSL and non-TLS/non-SSL incoming connections, and its outgoing connections use TLS/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:

    copy 
    db.adminCommand( { setParameter: 1, sslMode: "requireSSL", clusterAuthMode: "x509" } )

    With the sslMode set to requireSSL, the node only uses TLS/SSLs 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 TLS/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 TLS/SSL and x509 options and values.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.