Enable Internal Authentication¶

On this page

Overview
Considerations
Procedures
x.509 Internal Authentication

Overview¶

When authentication is enabled on a replica set or a sharded cluster, members of the replica set or the sharded clusters must provide credentials to authenticate.

To enable authentication on a replica set or a sharded cluster, you must enable authentication individually for each member. For a sharded cluster, this means enabling authentication on each mongos and each mongod, including the config servers and each member of a shard’s replica set.

The following tutorial uses a keyfile to enable internal authentication. You can also use x.509 certificate for internal authentication. For details on using x.509, see Use x.509 Certificate for Membership Authentication.

Considerations¶

Access Control¶

Enabling internal authentication enables access control. The following tutorial assumes no users have been created in the system before enabling internal authentication, and uses Localhost Exception to add a user administrator after access control has been enabled.

If you prefer, you can create the users before enabling internal authentication.

Sharded Cluster¶

It is not possible to convert an existing sharded cluster that does not enforce access control to require authentication without taking all components of the cluster offline for a short period of time.

For sharded clusters, the Localhost Exception will apply to the individual shards unless you either create an administrative user or disable the localhost exception on each shard.

Procedures¶

Update Existing Deployment¶

1

Create a keyfile.¶

Create the keyfile your deployment will use to authenticate to members to each other. You can generate a keyfile using any method you choose. Ensure that the password stored in the keyfile is both long and contains a high amount of randomness.

For example, the following operation uses openssl command to generate pseudo-random data to use for a keyfile:

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

2

Enable authentication for each member of the sharded cluster or replica set.¶

For each mongod in the replica set or for each mongos and mongod in the sharded cluster, including all config servers and shards, specify the keyfile using either a configuration file or a command line option.

In a configuration file, set the security.keyFile option to the keyfile’s path and then start the component, as in the following example:

security:
  keyFile: /srv/mongodb/keyfile

Include any other settings as appropriate for your deployment.

Or, when starting the component, specify the --keyFile option. For example, for a mongod

mongod --keyfile /srv/mongodb/mongodb-keyfile --dbpath <path to data>

Include any other options as appropriate for your deployment.

Enabling internal authentication enables access control.

3

Connect to the MongoDB instance via the localhost exception.¶

To add the first user using Localhost Exception:

For a replica set, connect a mongo shell to the primary. Run the mongo shell from the same host as the primary.
For a sharded cluster, connect a mongo shell to the mongos. Run the mongo shell from same host as the mongos.

4

Add first user.¶

Add a user with the userAdminAnyDatabase role. For example, the following creates the user myUserAdmin on the admin database:

use admin
db.createUser(
  {
    user: "myUserAdmin",
    pwd: "abc123",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

After you create the user administrator, for a replica set, the localhost exception is no longer available.

For sharded clusters, you must still prevent unauthorized access to the individual shards. Follow one of the following steps for each shard in your cluster:

Create an administrative user, or
Disable the Localhost Exception at startup. To disable the localhost exception, set the enableLocalhostAuthBypass to 0.

5

Authenticate as the user administrator.¶

Either connect a new mongo shell to the MongoDB instance with the -u <username>, -p <password>, and the --authenticationDatabase <database>:

mongo --port 27017 -u "myUserAdmin" -p "abc123" --authenticationDatabase "admin"

The mongo shell executes a number of commands at start up. As a result, when you log in as the user administrator, you may see authentication errors from one or more commands. You may ignore these errors, which are expected, because the userAdminAnyDatabase role does not have permissions to run some of the start up commands.

Or, in the mongo shell connected without authentication, switch to the authentication database, and use db.auth() method to authenticate:

use admin
db.auth("myUserAdmin", "abc123" )

6

Create additional users as needed for your deployment.¶

Deploy New Replica Set with Access Control¶

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 (myUserAdmin), and a root user (siteRootAdmin) that you will use to complete the remainder of the tutorial:

use admin
db.createUser( {
    user: "myUserAdmin",
    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 a 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 one and only one member of the replica set:

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. You must be connected to the primary to add members to a replica set.

rs.add() can, in some cases, trigger an election. If the mongod you are connected to becomes a secondary, you need to connect the mongo shell to the new primary to continue adding new replica set members. Use rs.status() to identify the primary in the replica set.

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 Role-Based Access Control. For more information on adding users, see Manage User and Roles.

x.509 Internal Authentication¶

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

To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.

← Enable Client Access Control Authentication Mechanisms →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.