- Security >
- Security Tutorials >
- Configure Users and Roles >
- Manage User and Roles
Manage User and Roles¶
On this page
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¶
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.
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.
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]
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.
The myUserAdmin
has privileges to create roles in the admin
as well as other databases.
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.
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]
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.
The myUserAdmin
has privileges to create roles in the admin
as well as other databases.
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.
[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¶
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.
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:
To display the privileges granted to the user by the
readWrite
role on the "accounts"
database, issue:
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.
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
:
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:
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¶
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.
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
:
See also
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¶
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.
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:
In the returned document, the roles
field displays all roles for reportsUser
:
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¶
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.
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:
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.