• Security >
• Role-Based Access Control >
• Enable Client Access Control

Enable Client Access Control

Overview

Enabling access control requires authentication of every user. Once authenticated, users only have the privileges as defined in the roles granted to the users.

To enable access control, use either the command line option --auth or security.authorization configuration file setting.

Note

The tutorial enables access control and uses the default authentication mechanism. To specify a different authentication mechanism, see Authentication Mechanisms.

You can also enable client access control by enforcing internal authentication for replica sets or sharded clusters.

Considerations

With access control enabled, ensure you have a user with userAdmin or userAdminAnyDatabase role in the admin database.

This tutorial assumes a standalone environment. See Internal Authentication for replica set and sharded cluster security tutorials that include steps for creating users.

You can create users before enabling access control or you can create users 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, authenticate as the user administrator to create additional users as needed.

Procedures

Add Users Before Enabling Access Control

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

1

Start MongoDB without access control.

For example, the following starts a standalone mongod instance without access control.

mongod --port 27017 --dbpath /data/db1

For details on starting a mongod or mongos, see Manage mongod Processes or Deploy a Sharded Cluster.

2

Connect to the instance.

For example, connect a mongo shell to the instance.

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.

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" } ]
  }
)

4

Re-start the MongoDB instance with access control.

Re-start the mongod instance with the --auth command line option or, if using a configuration file, the security.authorization setting.

mongod --auth --port 27017 --dbpath /data/db1

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" )

5

Create additional users as needed for your deployment.

If you need to disable access control for any reason, restart the MongoDB instance without the --auth command line option, or if using a configuration file, the security.authorization setting.

Add Users After Enabling Access Control

The following procedure first enables access control, and then uses localhost exception to add a user administrator.

1

Start the MongoDB instance with access control.

Start the mongod instance with the --auth command line option or, if using a configuration file, the security.authorization setting.

mongod --auth --port 27017 --dbpath /data/db1

2

Connect to the MongoDB instance via the localhost exception.

To add the first user using Localhost Exception, connect a mongo shell to the mongod instance. Run the mongo shell from the same host as the mongod instance.

3

Create the system user administrator.

Add the user with the userAdminAnyDatabase role, and only that role.

The following example creates the user myUserAdmin user on the admin database:

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

After you create the user administrator, the localhost exception is no longer available.

4

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" )

5

Create additional users as needed for your deployment.

Additional Information

See also Manage Users and Roles.

←   Role-Based Access Control Built-In Roles  →

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