Navigation

Enable Access Control

On this page

Overview

Enabling access control on a MongoDB deployment enforces authentication, requiring users to identify themselves. When accessing a MongoDB deployment that has access control enabled, users can only perform actions as determined by their roles.

The following tutorial enables access control on a standalone mongod instance and uses the default authentication mechanism. For all supported authentication mechanisms, see Authentication Mechanisms.

User Administrator

With access control enabled, ensure you have a user with userAdmin or userAdminAnyDatabase role in the admin database. This user can administrate user and roles such as: create users, grant or revoke roles from users, and create or modify customs roles.

Procedure

The following procedure first adds a user administrator to a MongoDB instance running without access control and then enables access control.

Note

The example MongoDB instance uses port 27017 and the data directory /var/lib/mongodb directory . The example assumes the existence of the data directory /var/lib/mongodb. Specify a different data directory as appropriate.

1

Start MongoDB without access control.

Start a standalone mongod instance without access control.

For example, open a terminal and issue the following:

copy 
mongod --port 27017 --dbpath /var/lib/mongodb
2

Connect to the instance.

For example, open a new terminal and connect a mongo shell to the instance:

copy 
mongo --port 27017

Specify additional command line options as appropriate to connect the mongo shell to your deployment, such as --host.

3

Create the user administrator.

From the mongo shell, add a user with the userAdminAnyDatabase role in the admin database. Include additional roles as needed for this user. For example, the following creates the user myUserAdmin in the admin database with the userAdminAnyDatabase role and the readWriteAnyDatabase role.

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy 
use admin
db.createUser(
  {
    user: "myUserAdmin",
    pwd: passwordPrompt(), // or cleartext password
    roles: [ { role: "userAdminAnyDatabase", db: "admin" }, "readWriteAnyDatabase" ]
  }
)

Note

The database where you create the user (in this example, admin) is the user’s authentication database. Although the user would authenticate to this database, the user can have roles in other databases; i.e. the user’s authentication database does not limit the user’s privileges.

4

Re-start the MongoDB instance with access control.

  1. Shut down the mongod instance. For example, from the mongo shell, issue the following command:

    copy 
    db.adminCommand( { shutdown: 1 } )

  2. Exit the mongo shell.

  3. Start the mongod with access control enabled.

Clients that connect to this instance must now authenticate themselves as a MongoDB user. Clients can only perform actions as determined by their assigned roles.

5

Connect and authenticate as the user administrator.

Using the mongo shell, you can:

  • Connect with authentication by passing in user credentials, or
  • Connect first without authentication, and then issue the db.auth() method to authenticate.

Start a mongo shell with the -u <username>, -p, and the --authenticationDatabase <database> command line options:

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

Enter your password when prompted.

Connect the mongo shell to the mongod:

copy 
mongo --port 27017

In the mongo shell, switch to the authentication database (in this case, admin), and use db.auth(<username>, <pwd>) method to authenticate:

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy 
use admin
db.auth("myUserAdmin", passwordPrompt()) // or cleartext password

Enter the password when prompted.

6

Create additional users as needed for your deployment.

Once authenticated as the user administrator, use db.createUser() to create additional users. You can assign any built-in roles or user-defined roles to the users.

The following operation adds a user myTester to the test database who has readWrite role in the test database as well as read role in the reporting database.

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy 
use test
db.createUser(
  {
    user: "myTester",
    pwd:  passwordPrompt(),   // or cleartext password
    roles: [ { role: "readWrite", db: "test" },
             { role: "read", db: "reporting" } ]
  }
)

Note

The database where you create the user (in this example, test) is that user’s authentication database. Although the user would authenticate to this database, the user can have roles in other databases; i.e. the user’s authentication database does not limit the user’s privileges.

After creating the additional users, disconnect the mongo shell.

7

Connect to the instance and authenticate as myTester.

After disconnecting the mongo shell as myUserAdmin, reconnect as myTester. You can:

  • Connect with authentication by passing in user credentials, or
  • Connect first withouth authentication, and then issue the db.auth() method to authenticate.

Start a mongo shell with the -u <username>, -p, and the --authenticationDatabase <database> command line options:

copy 
mongo --port 27017 -u "myTester" --authenticationDatabase "test" -p

Enter the password for the user when prompted.

Connect the mongo shell to the mongod:

copy 
mongo --port 27017

In the mongo shell, switch to the authentication database (in this case, test), and use db.auth(<username>, <pwd>) method to authenticate:

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy 
use test
db.auth("myTester", passwordPrompt())  // or cleartext password

Enter the password for the user when prompted.

8

Insert a document as myTester.

As myTester, you have privileges to perform read and write operations in the test database (as well as perform read operations in the reporting database). Once authenticated as myTester, insert a document into a collection in test database. For example, you can perform the following insert operation in the test database:

copy 
db.foo.insert( { x: 1, y: 1 } )

See also

Manage Users and Roles.

Additional Considerations

Replica Sets and Sharded clusters

Replica sets and sharded clusters require internal authentication between members when access control is enabled. For more details, please see Internal/Membership Authentication.

Localhost Exception

You can create users either before or after enabling access control. If you enable access control before creating any user, MongoDB provides a localhost exception which allows you to create a user administrator in the admin database. Once created, you must authenticate as the user administrator to create additional users as needed.

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