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

Deploy Replica Set and Configure Authentication and Authorization

Overview

With authentication enabled, MongoDB forces all clients to identify themselves before granting access to the server. Authorization, in turn, allows administrators to define and limit the resources and operations that a user can access. Using authentication and authorization is a key part of a complete security strategy.

All MongoDB deployments support authentication. By default, MongoDB does not require authorization checking. You can enforce authorization checking when deploying MongoDB, or on an existing deployment; however, you cannot enable authorization checking on a running deployment without downtime.

This tutorial provides a procedure for creating a MongoDB replica set that uses the challenge-response authentication mechanism. The tutorial includes creation of a minimal authorization system to support basic operations.

Considerations

Authentication

In this procedure, you will configure MongoDB using the default challenge-response authentication mechanism, using the keyFile to supply the password for inter-process authentication. The content of the key file is the shared secret used for all internal authentication.

All deployments that enforce authorization checking should have one user administrator user that can create new users and modify existing users. During this procedure you will create a user administrator that you will use to administer this deployment.

Architecture

In a production, deploy each member of the replica set to its own machine and if possible bind to the standard MongoDB port of 27017. Use the bind_ip option to ensure that MongoDB listens for connections from applications on configured addresses.

See Replica Set Deployment Architectures for more information.

Connectivity

Ensure that network traffic can pass between all members of the set and all clients in the network securely and efficiently. Consider the following:

  • Establish a virtual private network. Ensure that your network topology routes all traffic between members within a single site over the local area network.
  • Configure access control to prevent connections from unknown clients to the replica set.
  • Configure networking and firewall rules so that incoming and outgoing packets are permitted only on the default MongoDB port and only from within your deployment.

Finally ensure that each member of a replica set is accessible by way of resolvable DNS or hostnames. You should either configure your DNS names appropriately or set up your systems’ /etc/hosts file to reflect this configuration.

Configuration

Specify the run time configuration on each system in a configuration file stored in /etc/mongod.conf or a related location. Create the directory where MongoDB stores data files before deploying MongoDB.

For more information about the run time options used above and other configuration options, see Configuration File Options.

Procedure

This procedure deploys a replica set in which all members use the same key file.

1

Start one member of the replica set.

This mongod should not enable auth.

2

Create administrative users.

The following operations will create two users: a user administrator that will be able to create and modify users (siteUserAdmin), and a root user (siteRootAdmin) that you will use to complete the remainder of the tutorial:

use admin
db.createUser( {
    user: "siteUserAdmin",
    pwd: "<password>",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  });
db.createUser( {
    user: "siteRootAdmin",
    pwd: "<password>",
    roles: [ { role: "root", db: "admin" } ]
  });
3

Stop the mongod instance.

4

Create the key file to be used by each member of the replica set.

Create the key file your deployment will use to authenticate servers to each other.

To generate pseudo-random data to use for a keyfile, issue the following openssl command:

openssl rand -base64 741 > mongodb-keyfile
chmod 600 mongodb-keyfile

You may generate a key file using any method you choose. Always ensure that the password stored in the key file is both long and contains a high amount of entropy. Using openssl in this manner helps generate such a key.

5

Copy the key file to each member of the replica set.

Copy the mongodb-keyfile to all hosts where components of a MongoDB deployment run. Set the permissions of these files to 600 so that only the owner of the file can read or write this file to prevent other users on the system from accessing the shared secret.

6

Start each member of the replica set with the appropriate options.

For each member, start a mongod and specify the key file and the name of the replica set. Also specify other parameters as needed for your deployment. For replication-specific parameters, see Replication Options required by your deployment.

If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

The following example specifies parameters through the --keyFile and --replSet command-line options:

mongod --keyFile /mysecretdirectory/mongodb-keyfile --replSet "rs0"

The following example specifies parameters through a configuration file:

mongod --config $HOME/.mongodb/config

In production deployments, you can configure an init script to manage this process. Init scripts are beyond the scope of this document.

7

Connect to the member of the replica set where you created the administrative users.

Connect to the replica set member you started and authenticate as the siteRootAdmin user. From the mongo shell, use the following operation to authenticate:

use admin
db.auth("siteRootAdmin", "<password>");
8

Initiate the replica set.

Use rs.initiate() on the replica set member:

rs.initiate()

MongoDB initiates a set that consists of the current member and that uses the default replica set configuration.

9

Verify the initial replica set configuration.

Use rs.conf() to display the replica set configuration object:

rs.conf()

The replica set configuration object resembles the following:

{
   "_id" : "rs0",
   "version" : 1,
   "members" : [
      {
         "_id" : 1,
         "host" : "mongodb0.example.net:27017"
      }
   ]
}
10

Add the remaining members to the replica set.

Add the remaining members with the rs.add() method.

The following example adds two members:

rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")

When complete, you have a fully functional replica set. The new replica set will elect a primary.

11

Check the status of the replica set.

Use the rs.status() operation:

rs.status()
12

Create additional users to address operational requirements.

You can use built-in roles to create common types of database users, such as the dbOwner role to create a database administrator, the readWrite role to create a user who can update data, or the read role to create user who can search data but no more. You also can define custom roles.

For example, the following creates a database administrator for the products database:

use products
db.createUser(
  {
    user: "productsDBAdmin",
    pwd: "password",
    roles:
    [
      {
        role: "dbOwner",
        db: "products"
      }
    ]
  }
)

For an overview of roles and privileges, see Authorization. For more information on adding users, see Add a User to a Database.