Manage User and Roles¶

On this page

Overview
Prerequisites
Add a User
Create a User-Defined Role
Modify Access for Existing User
Modify Password for Existing User
View a User’s Role
View Role’s Privileges

Overview¶

Changed in version 2.6: MongoDB 2.6 introduces a new authorization model.

MongoDB employs Role-Based Access Control (RBAC) to determine access for users. A user is granted one or more roles that determine the user’s access or privileges to MongoDB resources and the actions that user can perform. A user should have only the minimal set of privileges required to ensure a system of least privilege.

Each application and user of a MongoDB system should map to a distinct application or user. This access isolation facilitates access revocation and ongoing user maintenance.

This tutorial provides examples for user and role management under the MongoDB’s authorization model.

Prerequisites¶

Important

If you have enabled access control for your deployment, you must authenticate as a user with the required privileges specified in each section. A user administrator with the userAdminAnyDatabase role, or userAdmin role in the specific databases, provides the required privileges to perform the operations listed in this tutorial. See Enable Client Access Control for details on adding user administrator as the first user.

Add a User¶

To create a user, specify the user name, password, and roles. For users that authenticate using external mechanisms [1], you do not need to provide the password when creating users.

When assigning roles, select the roles that have the exact required privileges. If the correct roles does not exist, you can create new roles.

[1]	See x.509, Kerberos Authentication, and LDAP Proxy Authority Authentication

Prerequisites¶

To create a new user in a database, you must have createUser action on that database resource.
To grant roles to a user, you must have the grantRole action on the role’s database.

Built-in roles userAdmin and userAdminAnyDatabase provide createUser and grantRole actions on their respective resources.

Procedure¶

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

2

Create the new user.¶

Create the user in the database to which the user will belong. Pass a well formed user document to the db.createUser() method.

The following operation creates a user in the reporting database with the specified name, password, and roles.

use reporting
db.createUser(
    {
      user: "reportsUser",
      pwd: "12345678",
      roles: [
         { role: "read", db: "reporting" },
         { role: "read", db: "products" },
         { role: "read", db: "sales" },
         { role: "readWrite", db: "accounts" }
      ]
    }
)

To authenticate the reportsUser, you must authenticate the user in the reporting database; i.e. specify --authenticationDatabase reporting.

You can create a user without assigning roles, choosing instead to assign the roles later. To do so, create the user with an empty roles array.

Create a User-Defined Role¶

Roles grant users access to MongoDB resources. MongoDB provides a number of built-in roles that administrators can use to control access to a MongoDB system. However, if these roles cannot describe the desired set of privileges, you can create new roles in a particular database.

Except for roles created in the admin database, a role can only include privileges that apply to its database and can only inherit from other roles in its database.

A role created in the admin database can include privileges that apply to the admin database, other databases or to the cluster resource, and can inherit from roles in other databases as well as the admin database.

To create a new role, use the db.createRole() method, specifying the privileges in the privileges array and the inherited roles in the roles array.

MongoDB uses the combination of the database name and the role name to uniquely define a role. Each role is scoped to the database in which you create the role, but MongoDB stores all role information in the admin.system.roles collection in the admin database.

Prerequisites¶

To create a role in a database, you must have:

the createRole action on that database resource.
the grantRole action on that database to specify privileges for the new role as well as to specify roles to inherit from.

Built-in roles userAdmin and userAdminAnyDatabase provide createRole and grantRole actions on their respective resources.

Create a Role to Manage Current Operations¶

The following example creates a role named manageOpRole which provides only the privileges to run both db.currentOp() and db.killOp(). [2]

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

The myUserAdmin has privileges to create roles in the admin as well as other databases.

2

Create a new role to manage current operations.¶

manageOpRole has privileges that act on multiple databases as well as the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "manageOpRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "killop", "inprog" ] },
       { resource: { db: "", collection: "" }, actions: [ "killCursors" ] }
     ],
     roles: []
   }
)

The new role grants permissions to kill any operations.

Warning

Terminate running operations with extreme caution. Only use db.killOp() to terminate operations initiated by clients and do not terminate internal database operations.

[2]	The built-in role `clusterMonitor` also provides the privilege to run `db.currentOp()` along with other privileges, and the built-in role `hostManager` provides the privilege to run `db.killOp()` along with other privileges.

Create a Role to Run `mongostat`¶

The following example creates a role named mongostatRole that provides only the privileges to run mongostat. [3]

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

The myUserAdmin has privileges to create roles in the admin as well as other databases.

2

Create a new role to manage current operations.¶

mongostatRole has privileges that act on the cluster resource. As such, you must create the role in the admin database.

use admin
db.createRole(
   {
     role: "mongostatRole",
     privileges: [
       { resource: { cluster: true }, actions: [ "serverStatus" ] }
     ],
     roles: []
   }
)

[3]	The built-in role `clusterMonitor` also provides the privilege to run `mongostat` along with other privileges.

Modify Access for Existing User¶

Prerequisites¶

You must have the grantRole action on a database to grant a role on that database.
You must have the revokeRole action on a database to revoke a role on that database.
To view a role’s information, you must be either explicitly granted the role or must have the viewRole action on the role’s database.

Procedure¶

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

2

Identify the user’s roles and privileges.¶

To display the roles and privileges of the user to be modified, use the db.getUser() and db.getRole() methods.

For example, to view roles for reportsUser created in Add a User, issue:

use reporting
db.getUser("reportsUser")

To display the privileges granted to the user by the readWrite role on the "accounts" database, issue:

use accounts
db.getRole( "readWrite", { showPrivileges: true } )

3

Identify the privileges to grant or revoke.¶

If the user requires additional privileges, grant to the user the role, or roles, with the required set of privileges. If such a role does not exist, create a new role with the appropriate set of privileges.

To revoke a subset of privileges provided by an existing role: revoke the original role and grant a role that contains only the required privileges. You may need to create a new role if a role does not exist.

4

Modify the user’s access.¶

Revoke a Role¶

Revoke a role with the db.revokeRolesFromUser() method. The following example operation removes the readWrite role on the accounts database from the reportsUser:

use reporting
db.revokeRolesFromUser(
    "reportsUser",
    [
      { role: "readWrite", db: "accounts" }
    ]
)

Grant a Role¶

Grant a role using the db.grantRolesToUser() method. For example, the following operation grants the reportsUser user the read role on the accounts database:

use reporting
db.grantRolesToUser(
    "reportsUser",
    [
      { role: "read", db: "accounts" }
    ]
)

For sharded clusters, the changes to the user are instant on the mongos on which the command runs. However, for other mongos instances in the cluster, the user cache may wait up to 10 minutes to refresh. See userCacheInvalidationIntervalSecs.

Modify Password for Existing User¶

Prerequisites¶

To modify the password of another user on a database, you must have the changeAnyPassword action on that database.

Procedure¶

1

Connect to MongoDB with the appropriate privileges.¶

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

2

Change the password.¶

Pass the user’s username and the new password to the db.changeUserPassword() method.

The following operation changes the reporting user’s password to SOh3TbYhxuLiW8ypJPxmt1oOfL:

db.changeUserPassword("reporting", "SOh3TbYhxuLiW8ypJPxmt1oOfL")

View a User’s Role¶

Prerequisites¶

To view another user’s information, you must have the viewUser action on the other user’s database.

Users can view their own information.

Procedure¶

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

2

Identify the user’s roles.¶

Use the usersInfo command or db.getUser() method to display user information.

For example, to view roles for reportsUser created in Add a User, issue:

use reporting
db.getUser("reportsUser")

In the returned document, the roles field displays all roles for reportsUser:

...
"roles" : [
   { "role" : "readWrite", "db" : "accounts" },
   { "role" : "read", "db" : "reporting" },
   { "role" : "read", "db" : "products" },
   { "role" : "read", "db" : "sales" }
]

View Role’s Privileges¶

Prerequisites¶

To view a role’s information, you must be either explicitly granted the role or must have the viewRole action on the role’s database.

Procedure¶

1

Connect to MongoDB with the appropriate privileges.¶

Connect to mongod or mongos as a user with the privileges specified in the prerequisite section.

The following procedure uses the myUserAdmin created in Enable Client Access Control.

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

2

Identify the privileges granted by a role.¶

For a given role, use the db.getRole() method, or the rolesInfo command, with the showPrivileges option:

For example, to view the privileges granted by read role on the products database, use the following operation, issue:

use products
db.getRole( "read", { showPrivileges: true } )

In the returned document, the privileges and inheritedPrivileges arrays. The privileges lists the privileges directly specified by the role and excludes those privileges inherited from other roles. The inheritedPrivileges lists all privileges granted by this role, both directly specified and inherited. If the role does not inherit from other roles, the two fields are the same.

...
"privileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
],
"inheritedPrivileges" : [
  {
    "resource": { "db" : "products", "collection" : "" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  },
  {
    "resource" : { "db" : "products", "collection" : "system.js" },
    "actions": [ "collStats","dbHash","dbStats","find","killCursors","planCacheRead" ]
  }
]

← Configure Users and Roles Change Your Password and Custom Data →

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.

Manage User and Roles¶

Overview¶

Prerequisites¶

Add a User¶

Prerequisites¶

Procedure¶

Connect to MongoDB with the appropriate privileges.¶

Create the new user.¶

Create a User-Defined Role¶

Prerequisites¶

Create a Role to Manage Current Operations¶

Connect to MongoDB with the appropriate privileges.¶

Create a new role to manage current operations.¶

Create a Role to Run mongostat¶

Connect to MongoDB with the appropriate privileges.¶

Create a new role to manage current operations.¶

Modify Access for Existing User¶

Prerequisites¶

Procedure¶

Connect to MongoDB with the appropriate privileges.¶

Identify the user’s roles and privileges.¶

Identify the privileges to grant or revoke.¶

Modify the user’s access.¶

Revoke a Role¶

Grant a Role¶

Modify Password for Existing User¶

Prerequisites¶

Procedure¶

Connect to MongoDB with the appropriate privileges.¶

Change the password.¶

View a User’s Role¶

Prerequisites¶

Procedure¶

Connect to MongoDB with the appropriate privileges.¶

Identify the user’s roles.¶

View Role’s Privileges¶

Prerequisites¶

Procedure¶

Connect to MongoDB with the appropriate privileges.¶

Identify the privileges granted by a role.¶

Create a Role to Run `mongostat`¶