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:

copy

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:

copy

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

copy

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:

copy

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

copy

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:

copy

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

6

Create additional users as needed for your deployment.¶

Deploy New Replica Set with Access Control¶

1

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:

copy

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.

2

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

Copy the mongodb-keyfile to all hosts where the replica set members run.

On UNIX systems, the keyfile must not have group or world permissions:

Ensure that the user running the mongod is the owner of the file.
Set the permissions of these files to 400 so that only the owner of the file can read this file.

3

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:

copy

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

If using a configuration file, set the security.keyFile option to the keyfile’s path, and the replication.replSetName option to the replica set name:

copy

security:
  keyFile: /mysecretdirectory/mongodb-keyfile
replication:
  replSetName: "rs0"

Start the mongod using the configuration file:

copy

mongod --config <path-to-config-file>

For more information on the configuration file, see configuration options.

4

Initiate the replica set.¶

Connect a mongo shell to one member of the replica set and run rs.initiate() method initiates the replica set.

For example:

copy

rs.initiate( {
    _id : "rs0",
    members: [
      { _id : 0, host : "mongo1.example.net:27017" },
      { _id : 1, host : "mongo2.example.net:27017" },
      { _id : 2, host : "mongo3.example.net:27017" }
    ]
 })

The _id must match the --replSet parameter or the replication.replSetName specified during startup.

5

Create administrative users.¶

Connected to the primary, create a root user (siteRootAdmin) that you will use to complete the remainder of the tutorial:

copy

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

6

Authenticate as the newly created user.¶

copy

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

7

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:

copy

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 →