Manage Users and Roles

On this page

Overview

Prerequisites
Create a User-Defined Role
Modify Access for an Existing User
Modify the Password for an Existing User
View a User's Roles
View a Role's Privileges

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB server.

Overview

This tutorial provides examples for user and role management under the MongoDB's authorization model. Create a User describes how to add a new user to MongoDB.

To create user-defined roles in MongoDB Atlas, see Add a Custom User-Defined Role in MongoDB Atlas.

Prerequisites

To configure custom user-defined database roles in MongoDB Atlas, you must have Organization Owner or Project Owner access to MongoDB Atlas. To learn more, see Configure Custom Database Roles.

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 Access Control for details on adding user administrator as the first user.

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.

Add a Custom User-Defined Role in MongoDB Atlas

You can create custom user-defined roles in MongoDB Atlas when the built-in roles don't include your desired set of privileges. To learn more see, Add Custom Roles in the MongoDB Atlas documentation.

To create a custom database role for your project using the Atlas CLI, run the following command:

atlas customDbRoles create <roleName> [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas customDbRoles create.

To create custom roles through the Atlas Administration API, see Create One Custom Role.

Follow these steps to create a custom role through the Atlas UI:

Open the Add Custom Role dialog

In the Security section of the left navigation, click Database Access.
Click the Custom Roles tab.
Click Add New Custom Role.

Enter the information for the custom role

Field	Description
Custom Role Name	Name of your custom role.
Action or Role	Privileges granted by the role. Click the drop-down menu to view the list of available privilege actions and roles. MongoDB Atlas groups the actions and roles into the following categories: `Collection Actions` `Database Actions and Roles` `Global Actions and Roles` `Custom Roles` (if any) Select the action or role from a single category. Once you select an action or role, MongoDB Atlas disables the other categories with the following exception. If you select an action or role from the Global Actions and Roles, you can still select actions/roles from Custom Roles. To grant actions and roles from a different category, click Add an action or role to add a new row.
Database	Database on which the selected actions and roles are granted, if applicable. MongoDB Atlas requires this field for all roles and actions under the Collection Actions and Database Actions and Roles categories.
Collection	Collection within the specified database on which the actions and roles are granted, if applicable. MongoDB Atlas requires this field for all roles and actions under Collection Actions. To grant the same set of privileges on multiple databases and collections, click Add a database or collection.

Click Add Custom Role

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.

To create a role with authenticationRestrictions specified, you must have the setAuthenticationRestriction action on the database resource which the role is created.

To add custom user-defined roles with mongosh, see the following examples:

Create a Role to Manage Current Operations.
Create a Role to Run mongostat.
Create a Role to Drop system.views Collection across Databases.

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(). [1]

Note

Starting in MongoDB 3.2.9, users do not need any specific privileges to view or kill their own operations on mongod instances. See db.currentOp() and db.killOp() for details.

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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.

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 the db.killOp() method or killOp command to terminate operations initiated by clients and do not terminate internal database operations.

[1]	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. [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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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.

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

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

Create a Role to Drop `system.views` Collection across Databases

The following example creates a role named dropSystemViewsAnyDatabase that provides the privileges to drop the system.views collection in any database.

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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

Create a new role to drop the `system.views` collection in any database.

For the role, specify a privilege that consists of:

an actions array that contains the dropCollection action, and
a resource document that specifies an empty string ("") for the database and the string "system.views" for the collection. See Specify Collections Across Databases as Resource for more information.

use admin
db.createRole(
   {
     role: "dropSystemViewsAnyDatabase", 
     privileges: [
       {
         actions: [ "dropCollection" ],
         resource: { db: "", collection: "system.views" }
       }
     ],
     roles: []
   }
)

Modify Access for an 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

To update roles for a team in the project you specify using the Atlas CLI, run the following command:

atlas projects teams update <teamId> [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas projects teams update.

To update organization roles through the Atlas Administration API, see Update Organization Roles for One MongoDB Cloud User.

To update project roles through the Atlas Administration API, see Update Project Roles for One MongoDB Cloud User.

Go to the Access Manager

Go to the Access Manager for your organization or project.

If it isn't already displayed, select the desired organization from the Organizations menu in the navigation bar.
(Optional) To modify project access:
1. Select your desired project from the list of projects in the Projects page.
2. Click the vertical ellipsis () next to your project name in the upper left corner and select Project Settings.
Click Access Manager in the navigation bar.

Edit an MongoDB Atlas user or team

Click the Users or Teams tab.

Modify the user's access

In the row for the user or team, click Edit.
Select or deselect roles.
To save your changes, click the checkmark button.

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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 Additional Examples, 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 } )

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:

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 the Password for an Existing User

Prerequisites

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

Procedure

To update a database user from your project using the Atlas CLI, run the following command:

atlas dbusers update <username> [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas dbusers update.

You can update database users through the Atlas Administration API. To learn more, see Update One Database User in One Project.

To modify existing users for an MongoDB Atlas project:

Go to the Database Users tab

In the Security section in the left navigation, click Database Access.

The Database Users tab displays.

Modify the user

Click Edit next to the user that you want to modify. You can modify the privileges and authentication details assigned to the user. You can't modify the authentication method.

The following table describes what you can do for each user:

User Type	Action
SCRAM authenticated users	Edit a user's password.
X.509 certificate authenticated users	Download a new certificate.
AWS IAM users	Modify database access privileges.
Temporary users	Modify the time period the user exists or make the user a permanent user, provided the user's expiration date has not already passed.

Note

You can't change a permanent user into a temporary user. If you change a temporary user into a permanent user, you can't make it temporary again.

Click Update User to save the changes

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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

Tip

View a User's Roles

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

To list all MongoDB Atlas database users for your project using the Atlas CLI, run the following command:

atlas dbusers list [options]

To return the details for a single MongoDB Atlas database user in the project you specify using the Atlas CLI, run the following command:

atlas dbusers describe <username> [options]

To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas dbusers list and atlas dbusers describe.

To view MongoDB Atlas database users using the Atlas Administration API, see Return All Database Users from One Project.

To view MongoDB Atlas database users and X.509 certificates in the Atlas UI:

In the Security section in the left navigation, click Database Access.
The Database Users tab displays.
Click Edit next to the user to view their privileges, authentication details, and X.509 certificates.

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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 Additional Examples, 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 a 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

To list all custom database roles for your project using the Atlas CLI, run the following command:

atlas customDbRoles list [options]

To return the details for a single custom database role in the project you specify using the Atlas CLI, run the following command:

atlas customDbRoles describe <roleName> [options]

To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas customDbRoles list and atlas customDbRoles describe.

To view custom roles through the Atlas Administration API, see Return All Custom Roles in One Project.

To view your custom roles through the Atlas UI:

In the Security section of the left navigation, click Database Access.

The Custom Roles tab displays.

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 Access Control.

mongosh --port 27017 -u myUserAdmin -p 'abc123' --authenticationDatabase 'admin'

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

Back

User-Defined Roles

Change Your Password and Custom Data

Manage Users and Roles.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Overview

Prerequisites

Important

Create a User-Defined Role

Add a Custom User-Defined Role in MongoDB Atlas

Open the .css-h15tq0{font-style:normal;font-weight:700;}Add Custom Role dialog

Enter the information for the custom role

Click Add Custom Role

Prerequisites

Create a Role to Manage Current Operations

Note

Connect to MongoDB with the appropriate privileges.

Create a new role to manage current operations.

Warning

Create a Role to Run mongostat

Connect to MongoDB with the appropriate privileges.

Create a new role to manage current operations.

Create a Role to Drop system.views Collection across Databases

Connect to MongoDB with the appropriate privileges.

Create a new role to drop the system.views collection in any database.

Modify Access for an Existing User

Prerequisites

Procedure

Go to the Access Manager

Edit an MongoDB Atlas user or team

Modify the user's access

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 the Password for an Existing User

Prerequisites

Procedure

Go to the Database Users tab

Modify the user

Note

Click Update User to save the changes

Connect to MongoDB with the appropriate privileges.

Change the password.

Tip

See also:

View a User's Roles

Prerequisites

Procedure

Connect to MongoDB with the appropriate privileges.

Identify the user's roles.

View a Role's Privileges

Prerequisites

Procedure

Connect to MongoDB with the appropriate privileges.

Identify the privileges granted by a role.

Manage Users and Roles

Open the Add Custom Role dialog

Create a Role to Run `mongostat`

Create a Role to Drop `system.views` Collection across Databases

Create a new role to drop the `system.views` collection in any database.