Security >
Authentication >
Internal Authentication >
Enforce Authentication in an Existing Sharded Cluster Without Downtime

Enforce Authentication in an Existing Sharded Cluster Without Downtime¶

On this page

Overview¶

Important

The following procedure applies to sharded clusters using MongoDB 3.4 or later.

Earlier versions of MongoDB do not support no-downtime upgrade. For sharded clusters using earlier versions of MongoDB, see Enforce Keyfile Access Control in Sharded Cluster.

A MongoDB sharded cluster can enforce user authentication as well as internal authentication of its components to secure against unauthorized access.

The following tutorial describes a procedure using security.transitionToAuth to transition an existing sharded cluster to enforce authentication without incurring downtime.

Before you attempt this tutorial, please familiarize yourself with the contents of this document.

Considerations¶

Cloud Manager and Ops Manager¶

If you are using Cloud Manager or Ops Manager to manage your deployment, refer to Configure Access Control for MongoDB Deployments in the Cloud Manager manual or Ops Manager manual to enforce authentication.

Internal and Client Authentication Mechanisms¶

This tutorial configures authentication using SCRAM-SHA-1 for client authentication and a keyfile for internal authentication.

Refer to the Authentication documentation for a complete list of available client and internal authentication mechanisms.

Architecture¶

This tutorial assumes that each shard replica set, as well as the config server replica set, can elect a new primary after stepping down its existing primary.

A replica set can elect a primary only if both of the following conditions are true:

A majority of voting replica set members are available after stepping down the primary.
There is at least one available secondary member that is not delayed, hidden, or Priority 0.

Minimum number of `mongos` instances¶

Ensure your sharded cluster has at least two mongos instances available. This tutorial requires restarting each mongos in the cluster. If your sharded cluster has only one mongos instance, this results in downtime during the period that the mongos is offline.

Enforce Keyfile Access Control on an Existing Sharded Cluster¶

Create and Distribute the Keyfile¶

With keyfile authentication, each mongod or mongos instances in the sharded cluster uses the contents of the keyfile as the shared password for authenticating other members in the deployment. Only mongod or mongos instances with the correct keyfile can join the sharded cluster.

The content of the keyfile must be between 6 and 1024 characters long and must be the same for all members of the sharded cluster.

Note

On UNIX systems, the keyfile must not have group or world permissions. On Windows systems, keyfile permissions are not checked.

You can generate a keyfile using any method you choose. For example, the following operation uses openssl to generate a complex pseudo-random 1024 character string to use for a keyfile. It then uses chmod to change file permissions to provide read permissions for the file owner only:

openssl rand -base64 755 > <path-to-keyfile>
chmod 400 <path-to-keyfile>

Copy the keyfile to each server hosting the sharded cluster members. Ensure that the user running the mongod or mongos instances is the owner of the file and can access the keyfile.

Avoid storing the keyfile on storage mediums that can be easily disconnected from the hardware hosting the mongod or mongos instances, such as a USB drive or a network attached storage device.

For more information on using keyfiles for internal authentication, refer to Keyfiles.

Configure Sharded Cluster Admin User and Client Users¶

You must connect to a mongos to complete the steps in this section. The users created in these steps are cluster-level users and cannot be used for accessing individual shard replica sets.

1

Create the adminstrator user.¶

Use the db.createUser() method to create an administrator user and assign it the following roles:

clusterAdmin on the admin database
userAdmin roles on the admin database

Clients performing maintenance operations or user administrative operations on the sharded cluster must authenticate as this user at the completion of this tutorial. Create this user now to ensure that you have access to the cluster after enforcing authentication.

admin = db.getSiblingDB("admin");
admin.createUser(
  {
    user: "admin",
    pwd: "<password>",
    roles: [
      { role: "clusterAdmin", db: "admin" },
      { role: "userAdmin", db: "admin" }
    ]
  }
);

Important

Passwords should be random, long, and complex to prevent or hinder malicious access.

2

Optional: Create additional users for client applications.¶

In addition to the administrator user, you can create additional users before enforcing authentication.. This ensures access to the sharded cluster once you fully enforce authentication.

Example

The following operation creates the user joe on the marketing database, assigning to this user the readWrite role on the marketing database`.

db.getSiblingDB("marketing").createUser(
  {
    "user": "joe",
    "pwd": "<password>",
    "roles": [ { "role" : "readWrite", "db" : "marketing" } ]
  }
)

Clients authenticating as "joe" can perform read and write operations on the marketing database.

See Database User Roles for roles provided by MongoDB.

See the Add Users tutorial for more information on adding users. Consider security best practices when adding new users.

3

Optional: Update client applications to specify authentication credentials.¶

While the sharded cluster does not currently enforce authentication, you can still update client applications to specify authentication credentials when connecting to the sharded cluster. This may prevent loss of connectivity at the completion of this tutorial.

Example

The following operation connects to the sharded cluster using the mongo shell, authenticating as the user joe on the marketing database.

mongo  --username "joe" --password "<password>" \
  --authenticationDatabase "marketing" --host mongos1.example.net:27017

If your application uses a MongoDB driver, see the associated driver documentation for instructions on creating an authenticated connection.

Transition Each `mongos` Instance to Enforce Authentication¶

1

Create a new `mongos` configuration file.¶

For each mongos:

Copy the existing mongos configuration file, giving it a distinct name such as <filename>-secure.conf (or .cfg if using Windows). You will use this new configuration file to transition the mongos to enforce authentication in the sharded cluster. Retain the original configuration file for backup purposes.
To the new configuration file, add the following settings:
- security.transitionToAuth set to true
- security.keyFile set to the keyfile path.
  
  If using a different internal authentication mechanism, specify settings appropriate for the mechanism.
```
security:
   transitionToAuth: true
   keyFile: <path-to-keyfile>
```
The new configuration file should contain all of the configuration settings previously used by the mongos as well as the new security settings.

2

One at a time, restart the `mongos` with the new configuration file.¶

Note

If your cluster has only one mongos, this step results in downtime while the mongos is offline.

Follow the procedure to restart the mongos instance, one mongos at a time:

Connect to the mongos to shutdown.
Use the db.shutdownServer() method against the admin database to safely shut down the mongos.
```
db.getSiblingDB("admin").shutdownServer()
```
Restart mongos with the new configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongos-secure.conf:
```
mongos --config <path>/mongos-secure.conf
```
where <path> represents the system path to the folder containing the new configuration file.

Repeat the restart process for the next mongos instance until all mongos instances in the sharded cluster have been restarted.

At the end of this section, all mongos instances in the sharded cluster are running with security.transitionToAuth and security.keyFile internal authentication.

Transition Config Server Replica Set Members to Enforce Authentication¶

1

Create a new `mongod` configuration file.¶

For each mongod in the config server replica set,

Copy the existing mongod configuration file, giving it a distinct name such as <filename>-secure.conf (or .cfg if using Windows). You will use this new configuration file to transition the mongod to enforce authentication in the sharded cluster. Retain the original configuration file for backup purposes.
To the new configuration file, add the following settings:
- security.transitionToAuth set to true
- security.keyFile set to the keyfile path.
  
  If using a different internal authentication mechanism, specify settings appropriate for the mechanism.
```
security:
   transitionToAuth: true
   keyFile: <path-to-keyfile>
```

2

One at a time, restart the `mongod` with the new configuration file.¶

Restart the replica set, one member at a time, starting with the secondary members.

To restart the secondary members one at a time,
1. Connect to the mongod and use the db.shutdownServer() method against the admin database to safely shut down the mongod.
```
db.getSiblingDB("admin").shutdownServer()
```
2. Restart the mongod with the new configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the new configuration file.
Once this member is up, repeat for the next secondary member.
Once all the secondary members have restarted and are up, restart the primary:
1. Connect to the mongod.
2. Use the rs.stepDown() method to step down the primary and trigger an election.
```
rs.stepDown()
```
  You can use the rs.status() method to ensure the replica set has elected a new primary.
3. Once you step down the primary and a new primary has been elected, shut down the old primary using the db.shutdownServer() method against the admin database.
```
db.getSiblingDB("admin").shutdownServer()
```
4. Restart the mongod with the new configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the new configuration file.

At the end of this section, all mongod instances in the config server replica set is running with security.transitionToAuth and security.keyFile internal authentication.

Transition Each Shard Replica Set Members to Enforce Authentication¶

Create the shard-local administrator¶

In a sharded cluster that enforces authentication, each shard replica set should have its own shard-local administrator. You cannot use a shard-local administrator for one shard to access another shard or the sharded cluster.

Connect to the primary member of each shard replica set and create a user with the db.createUser() method, assigning it the following roles:

clusterAdmin on the admin database
userAdmin roles on the admin database

admin = db.getSiblingDB("admin")
admin.createUser(
  {
    user: "admin",
    pwd: "<password>",
    roles: [
      { role: "clusterAdmin", db: "admin" },
      { role: "userAdmin", db: "admin" }
    ]
  }
)

At the completion of this tutorial, if you want to connect to the shard to perform maintenance operation that require direct connection to a shard, you must authenticate as the shard-local administrator.

Note

Direct connections to a shard should only be for shard-specific maintenance and configuration. In general, clients should connect to the sharded cluster through the mongos.

Procedure¶

Transitioning one shard replica set at a time, repeat these steps for each shard replica set in the sharded cluster.

1

Create a new `mongod` configuration file.¶

For each mongod in the shard replica set,

Copy the existing mongod configuration file, giving it a distinct name such as <filename>-secure.conf (or .cfg if using Windows). You will use this new configuration file to transition the mongod to enforce authentication in the sharded cluster. Retain the original configuration file for backup purposes.
To the new configuration file, add the following settings:
- security.transitionToAuth set to true
- security.keyFile set to the keyfile path.
  
  If using a different internal authentication mechanism, specify settings appropriate for the mechanism.
```
security:
   transitionToAuth: true
   keyFile: <path-to-keyfile>
```

2

One at a time, restart the `mongod` with the new configuration file.¶

Restart the replica set, one member at a time, starting with the secondary members.

To restart the secondary members one at a time,
1. Connect to the mongod and use the db.shutdownServer() method against the admin database to safely shut down the mongod.
```
db.getSiblingDB("admin").shutdownServer()
```
2. Restart the mongod with the new configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the new configuration file.
Once this member is up, repeat for the next secondary member of the replica set until all secondaries have been updated.
Once all the secondary members have restarted and are up, restart the primary:
1. Connect to the mongod.
2. Use the rs.stepDown() method to step down the primary and trigger an election.
```
rs.stepDown()
```
  You can use the rs.status() method to ensure the replica set has elected a new primary.
3. Once you step down the primary and a new primary has been elected, shut down the old primary using the db.shutdownServer() method against the admin database.
```
db.getSiblingDB("admin").shutdownServer()
```
4. Restart the mongod with the new configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the new configuration file.

At this point in the tutorial, every component of the sharded cluster is running with --transitionToAuth and security.keyFile internal authentication. The sharded cluster has at least one administrative user, and each shard replica set has a shard-local administrative user.

The remaining sections involve taking the sharded cluster out of the transition state to fully enforce authentication.

Restart Each `mongos` Instance without `transitionToAuth`¶

Important

At the end of this section, clients must specify authentication credentials to connect to the sharded cluster. Update clients to specify authentication credentials before completing this section to avoid loss of connectivity.

To complete the transition to fully enforcing authentication in the sharded cluster, you must restart each mongos instance without the security.transitionToAuth setting.

1

Remove `transitionToAuth` from the `mongos` configuration files.¶

Remove the security.transitionToAuth key and its value from the mongos configuration files created during this tutorial. Leave the security.keyFile setting added in the tutorial.

security:
   keyFile: <path-to-keyfile>

2

Restart the `mongos` with the updated configuration file.¶

Note

If your cluster has only one mongos, this step results in downtime while the mongos is offline.

Follow the procedure to restart mongos instance, one mongos at a time:

Connect to the mongos to shutdown.
Use the db.shutdownServer() method against the admin database to safely shut down the mongos.
```
db.getSiblingDB("admin").shutdownServer()
```
Restart mongos with the updated configuration file, specifying the path to the config file using --config. For example, if the updated configuration file were named mongos-secure.conf:
```
mongos --config <path>/mongos-secure.conf
```

At the end of this section, all mongos instances enforce client authentication and security.keyFile internal authentication.

Restart Each Config Server Replica Set Member without `transitionToAuth`¶

Important

At the end of this step, clients must specify authentication credentials to connect to the config server replica set. Update clients to specify authentication credentials before completing this section to avoid loss of connectivity.

To complete the transition to fully enforcing authentication in the sharded cluster, you must restart each mongod instance without the security.transitionToAuth setting.

1

Remove `transitionToAuth` from the `mongod` configuration files.¶

Remove the security.transitionToAuth key and its value from the config server configuration files created during this tutorial. Leave the security.keyFile setting added in the tutorial.

security:
   keyFile: <path-to-keyfile>

2

One at a time, restart the `mongod` with the updated configuration file.¶

Restart the replica set, one member at a time, starting with the secondary members.

To restart the secondary members one at a time,
1. Connect to the mongod and use the db.shutdownServer() method against the admin database to safely shut down the mongod.
```
db.getSiblingDB("admin").shutdownServer()
```
2. Restart the mongod with the updated configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the updated configuration file.
Once this member is up, repeat for the next secondary member.
Once all the secondary members have restarted and are up, restart the primary:
1. Connect to the mongod.
2. Use the rs.stepDown() method to step down the primary and trigger an election.
```
rs.stepDown()
```
  You can use the rs.status() method to ensure the replica set has elected a new primary.
3. Once you step down the primary and a new primary has been elected, shut down the old primary using the db.shutdownServer() method against the admin database.
```
db.getSiblingDB("admin").shutdownServer()
```
4. Restart the mongod with the updated configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the updated configuration file.

At the end of this section, all mongod instances in the config server replica set enforce client authentication and security.keyFile internal authentication.

Restart Each Member in Each Shard Replica Set without `transitionToAuth`¶

Important

At the end of this step, clients must specify authentication credentials to connect to the shard replica set. Update clients to specify authentication credentials before completing this section to avoid loss of connectivity.

To complete the transition to fully enforcing authentication in the sharded cluster, you must restart every member of every shard replica set in the sharded cluster without the security.transitionToAuth setting.

Transitioning one shard replica set at a time, repeat these steps for each shard replica set in the sharded cluster.

1

Remove `transitionToAuth` from the `mongod` configuration files.¶

Remove the security.transitionToAuth key and its value from the config server configuration files created during this tutorial. Leave the security.keyFile setting added in the tutorial.

security:
   keyFile: <path-to-keyfile>

2

One at a time, restart the `mongod` with the updated configuration file.¶

Restart the replica set, one member at a time, starting with the secondary members.

To restart the secondary members one at a time,
1. Connect to the mongod and use the db.shutdownServer() method against the admin database to safely shut down the mongod.
```
db.getSiblingDB("admin").shutdownServer()
```
2. Restart the mongod with the updated configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the updated configuration file.
Once this member is up, repeat for the next secondary member.
Once all the secondary members have restarted and are up, restart the primary:
1. Connect to the mongod.
2. Use the rs.stepDown() method to step down the primary and trigger an election.
```
rs.stepDown()
```
  You can use the rs.status() method to ensure the replica set has elected a new primary.
3. Once you step down the primary and a new primary has been elected, shut down the old primary using the db.shutdownServer() method against the admin database.
```
db.getSiblingDB("admin").shutdownServer()
```
4. Restart the mongod with the updated configuration file, specifying the path to the config file using --config. For example, if the new configuration file were named mongod-secure.conf:
```
mongod --config <path>/mongod-secure.conf
```
  where <path> represents the system path to the folder containing the updated configuration file.

At the end of this section, all mongos and mongod instances in the sharded cluster enforce client authentication and security.keyFile internal authentication. Clients can only connect to the sharded cluster by using the configured client authentication mechanism. Additional components can only join the cluster by specifying the correct keyfile.

x.509 Certificate Internal Authentication¶

MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. Sharded cluster members and replica set members can use x.509 certificates to verify their membership to the cluster or the replica set instead of using Keyfiles.

For details on using x.509 certificates for internal authentication, see Use x.509 Certificate for Membership Authentication.

Upgrade from Keyfile Authentication to x.509 Authentication describes how to upgrade a deployment’s internal auth mechanism from keyfile-based authentication to x.509 certificate-based auth.

← Enforce Keyfile Access Control in Sharded Cluster Deploy Sharded Cluster with Keyfile Access Control →

Enforce Authentication in an Existing Sharded Cluster Without Downtime¶

Overview¶

Considerations¶

Cloud Manager and Ops Manager¶

Internal and Client Authentication Mechanisms¶

Architecture¶

Minimum number of mongos instances¶

Enforce Keyfile Access Control on an Existing Sharded Cluster¶

Create and Distribute the Keyfile¶

Configure Sharded Cluster Admin User and Client Users¶

Create the adminstrator user.¶

Optional: Create additional users for client applications.¶

Optional: Update client applications to specify authentication credentials.¶

Transition Each mongos Instance to Enforce Authentication¶

Create a new mongos configuration file.¶

One at a time, restart the mongos with the new configuration file.¶

Transition Config Server Replica Set Members to Enforce Authentication¶

Create a new mongod configuration file.¶

One at a time, restart the mongod with the new configuration file.¶

Transition Each Shard Replica Set Members to Enforce Authentication¶

Create the shard-local administrator¶

Procedure¶

Create a new mongod configuration file.¶

One at a time, restart the mongod with the new configuration file.¶

Restart Each mongos Instance without transitionToAuth¶

Remove transitionToAuth from the mongos configuration files.¶

Restart the mongos with the updated configuration file.¶

Restart Each Config Server Replica Set Member without transitionToAuth¶

Remove transitionToAuth from the mongod configuration files.¶

One at a time, restart the mongod with the updated configuration file.¶

Restart Each Member in Each Shard Replica Set without transitionToAuth¶

Remove transitionToAuth from the mongod configuration files.¶

One at a time, restart the mongod with the updated configuration file.¶

x.509 Certificate Internal Authentication¶

Minimum number of `mongos` instances¶

Transition Each `mongos` Instance to Enforce Authentication¶

Create a new `mongos` configuration file.¶

One at a time, restart the `mongos` with the new configuration file.¶

Create a new `mongod` configuration file.¶

One at a time, restart the `mongod` with the new configuration file.¶

Create a new `mongod` configuration file.¶

One at a time, restart the `mongod` with the new configuration file.¶

Restart Each `mongos` Instance without `transitionToAuth`¶

Remove `transitionToAuth` from the `mongos` configuration files.¶

Restart the `mongos` with the updated configuration file.¶

Restart Each Config Server Replica Set Member without `transitionToAuth`¶

Remove `transitionToAuth` from the `mongod` configuration files.¶

One at a time, restart the `mongod` with the updated configuration file.¶

Restart Each Member in Each Shard Replica Set without `transitionToAuth`¶

Remove `transitionToAuth` from the `mongod` configuration files.¶

One at a time, restart the `mongod` with the updated configuration file.¶