Enable Access Control

Overview

Enabling access control on a MongoDB deployment enforcesauthentication, requiring users to identify themselves. When accessinga MongoDB deployment that has access control enabled, users can onlyperform actions as determined by their roles.

The following tutorial enables access control on a standalonemongod instance and uses the defaultauthentication mechanism. For allsupported authentication mechanisms, seeAuthentication Mechanisms.

User Administrator

With access control enabled, ensure you have a user withuserAdmin or userAdminAnyDatabase role in theadmin database. This user can administrate user and roles such as:create users, grant or revoke roles from users, and create or modifycustoms roles.

Procedure

The following procedure first adds a user administrator to a MongoDBinstance 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 . Theexample assumes the existence of the data directory/var/lib/mongodb. Specify a different data directory asappropriate.

Start MongoDB without access control.

Start a standalone mongod instance without accesscontrol.

For example, open a terminal and issue the following:

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

Connect to the instance.

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

mongo --port 27017

Specify additional command line options as appropriate to connect themongo shell to your deployment, such as —host.

Create the user administrator.

From the mongo shell, add a user with theuserAdminAnyDatabase role in the admin database. Include additional roles asneeded for this user. For example, the followingcreates the user myUserAdmin in the admin database with theuserAdminAnyDatabase role and thereadWriteAnyDatabase role.

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

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 wouldauthenticate to this database, the user canhave roles in other databases; i.e. the user’s authenticationdatabase does not limit the user’s privileges.

Re-start the MongoDB instance with access control.

• Shut down the mongod instance. For example, fromthe mongo shell, issue the following command:

db.adminCommand( { shutdown: 1 } )

• Exit the mongo shell.

• From the terminal, re-start the mongod instancewith the —auth command line option or, if using aconfiguration file, the security.authorization setting.

mongod --auth --port 27017 --dbpath /var/lib/mongodb

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

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 thedb.auth() method to authenticate.

• Authenticate during Connection
• Authenticate after Connection

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

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

Enter your password when prompted.

Connect the mongo shell to themongod:

mongo --port 27017

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

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

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

Enter the password when prompted.

Create additional users as needed for your deployment.

Once authenticated as the user administrator, usedb.createUser() to create additional users. You can assignany built-in roles oruser-defined roles to theusers.

The following operation adds a user myTester to the testdatabase who has readWrite role in the testdatabase as well as read role in the reportingdatabase.

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

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 wouldauthenticate to this database, the user can have roles in otherdatabases; i.e. the user’s authentication database does not limitthe user’s privileges.

After creating the additional users, disconnect themongo shell.

Connect to the instance and authenticate as myTester.

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

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

• Authenticate during Connection
• Authenticate after Connection

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

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

Enter the password for the user when prompted.

Connect the mongo shell to themongod:

mongo --port 27017

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

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

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

Enter the password for the user when prompted.

Insert a document as myTester.

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

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 authenticationbetween 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. Ifyou enable access control before creating any user, MongoDB provides alocalhost exception which allows you tocreate a user administrator in the admin database. Once created,you must authenticate as the user administrator to create additionalusers as needed.