User and Role Management

Create a User Administrator – User administrators create users and create and assigns roles. A user administrator can grant any privilege in the database and can create new ones. In a MongoDB deployment, create the user administrator as the first user. Then let this user create all other users. To provide user administrators, MongoDB has userAdmin and userAdminAnyDatabase roles, which grant access to actions that support user and role management. Following the policy of least privilege userAdmin and userAdminAnyDatabase confer no additional privileges.

Carefully control access to these roles. A user with either of these roles can grant itself unlimited additional privileges. Specifically, a user with the userAdmin role can grant itself any privilege in the database. A user assigned either the userAdmin role on the admin database or the userAdminAnyDatabase can grant itself any privilege in the system. The prerequisites are

You must have the createUser action on a database to create a new user on that database.
You must have the grantRole action on a role’s database to grant the role to another user.
If you have the userAdmin or userAdminAnyDatabase role, or if you are authenticated using the localhost exception, you have those actions.

Procedure

Connect to MongoDB with the appropriate privileges- Connect to the mongod or mongos as a user with the privileges required in the Prerequisites section. The following example operation connects to MongoDB as an authenticated user named manager:

mongo –port 27017 -u manager -p 12345678 –authenticationDatabase admin

Verify your privileges – Use the usersInfo command with the showPrivileges option. The following example operation checks privileges for a user connected as manager:

db.runCommand( { usersInfo:”manager”,

showPrivileges:true

} )

The resulting user’s document displays the privileges granted to manager.

Create the system user administrator – Add the user with the userAdminAnyDatabase role, and only that role. The following example creates the user siteUserAdmin user on the admin database:

use admin

db.createUser( {

user: “siteUserAdmin”,

pwd: “password”,

roles:

[ {

role: “userAdminAnyDatabase”,

db: “admin”

} ] } )

Create a user administrator for a single database – Optionally, you may want to create user administrators that only have access to administer users in a specific database by way of the userAdmin role. The following example creates the user recordsUserAdmin on the records database:

use products

db.createUser(

{ user: “recordsUserAdmin”,

pwd: “password”,

roles:

[ {

role: “userAdmin”,

db: “records”

} ] } )

Add a User to a Database – Each application and user of a MongoDB system should map to a distinct application or administrator. This access isolation facilitates access revocation and ongoing user maintenance. At the same time users should have only the minimal set of privileges required to ensure a system of least privilege. To create a user, you must define the user’s credentials and assign that user roles. Credentials verify the user’s identity to a database, and roles determine the user’s access to database resources and operations. 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 with the specified name, password, and roles:

db.createUser(

{ user: “reportsUser”,

pwd: “12345678”,

roles: [ “reportingRole”, “readWriteAnyDatabase” ]

}

)

Create an Administrative User with Unrestricted Access – Most users should have only the minimal set of privileges required for their operations, in keeping with the policy of least privilege. However, some authorization architectures may require a user with unrestricted access. To support these super users, you can create users with access to all database resources and actions. For many deployments, you may be able to avoid having any users with unrestricted access by having an administrative user that with the createUser and grantRole actions as needed to support operations. If users truly need unrestricted access to a MongoDB deployment, MongoDB provides a built-in role named root that grants the combined privileges of all built-in roles. This document describes how to create an administrative user with the root role. In the admin database, create a new user using the db.createUser() method. Give the user the built-in root role. For example:

use admin

db.createUser(

{

user: “superuser”,

pwd: “12345678”,

roles: [ “root” ]

}

)

Authenticate against the admin database to test the new user account. Use db.auth() while using the admin database or use the mongo shell with the –authenticationDatabase option.

Create a Role – Roles grant users access to MongoDB resources. By default, MongoDB provides a number of built-in roles that administrators may use to control access to a MongoDB system. However, if these roles cannot describe the desired privilege set of a particular user type in a deployment, you can define a new, customized role. A role’s privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases. The combination of the database name and the role name uniquely defines a role in MongoDB. The pre-requisites are

You must have the createRole action on a database to create a role on that database.
You must have the grantRole action on the database that a privilege targets in order to grant that privilege to a role. If the privilege targets multiple databases or the cluster resource , you must have the grantRole action on the admin database.
You must have the grantRole action on a role’s database to grant the role to another role.
To view a role’s information, you must be explicitly granted the role or must have the viewRole action on the role’s database.

Define the privileges to grant to the role – Decide which resources to grant access to and which actions to grant on each resource. When creating the role, you will enter the resource-action pairings as documents in the privileges array, as in the following example:

{ db: “products”, collection: “electronics” }

Check whether an existing role provides the privileges – If an existing role contains the exact set of privileges, the new role can inherit those privileges. To view the privileges provided by existing roles, use the rolesInfo command, as in the following:

db.runCommand( { rolesInfo: 1, showPrivileges: 1 } )

Create the role – To create the role, use the createRole command. Specify privileges in the privileges array and inherited roles in the roles array. The following example creates the myClusterwideAdmin role in the admin database:

use admin

db.createRole(

{ role: “myClusterwideAdmin”,

privileges:

[

{ resource: { cluster: true }, actions: [ “addShard” ] },

{ resource: { db: “config”, collection: “” }, actions: [ “find”, “update”, “insert” ] },

{ resource: { db: “users”, collection: “usersCollection” }, actions: [ “update” ] },

{ resource: { db: “”, collection: “” }, actions: [ “find” ] }

roles:

[

{ role: “read”, db: “admin” }

writeConcern: { w: “majority” , wtimeout: 5000 }

}

)

The operation defines myClusterwideAdmin role’s privileges in the privileges array. In the roles array, myClusterwideAdmin inherits privileges from the admin database’s read role.

Assign a User a Role – A role provides a user privileges to perform a set of actions on a resource. A user can have multiple roles. In MongoDB systems with authorization enforced, you must grant a user a role for the user to access a database resource. To assign a role, first determine the privileges the user needs and t hen determine the role that grants those privileges. The steps are

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. To display the privileges granted by siteRole01 on the current database, issue:

db.getRole( “siteRole01”, { showPrivileges: true } )

Identify the privileges to grant or revoke – Determine which role contains the privileges and only those privileges. If such a role does not exist, then to grant the privileges will require creating a new role with the specific set of privileges. To revoke a subset of privileges provided by an existing role: revoke the original role, create a new role that contains the privileges to keep, and then grant that role to the user.

Grant a role to a user – Grant the user the role using the db.grantRolesToUser() method. For example:

use admin

db.grantRolesToUser(

“accountAdmin01”,

[ { role: “readWrite”, db: “products”

{ role: “readAnyDatabase”, db:”admin”

} ]

)

Modify a User’s Access – When a user’s responsibilities change, modify the user’s access to include only those roles the user requires. This follows the policy of least privilege. To change a user’s access, first determine the privileges the user needs and then determine the roles that grants those privileges. Grant and revoke roles using the method:db.grantRolesToUser() and db.revokeRolesFromUser methods. The steps are

Modify the user’s access

Revoke a Role – Revoke a role with the db.revokeRolesFromUser() method. Access revocations apply as soon as the user tries to run a command. On a mongos revocations are instant on the mongos on which the command ran, but there is up to a 10-delay before the user cache is updated on the other mongos instances in the cluster. The following example operation removes the readWrite role on the accounts database from the accountUser01 user’s existing roles:

use accounts

db.revokeRolesFromUser(

“accountUser01”,

[

{ role: “readWrite”, db: “accounts” }

]

)

Grant a Role – Grant a role using the db.grantRolesToUser() method. For example, the following operation grants the accountUser01 user the read role on the records database:

use accounts

db.grantRolesToUser(

“accountUser01”,

[

{ role: “read”, db: “records” }

]

)

Change a User’s Password – Strong passwords help prevent unauthorized access, and all users should have strong passwords. You can use the openssl program to generate unique strings for use in passwords, as in the following command:

openssl rand -base64 48

Pass the user’s username and the new password to the db.changeUserPassword() method. The following operation changes the reporting user’s password to Oh3TbYhxuLiW8ypJPxmt1oOfL:

db.changeUserPassword(“reporting”, “SOh3TbYhxuLiW8ypJPxmt1oOfL”)

Change Your Password and Custom Data – Users with appropriate privileges can change their own passwords and custom data. Custom data stores optional user information. Pass your username, new password, and new custom data to the updateUser command. For example, the following operation changes a user’s password to KNlZmiaNUp0B and custom data to { title: “Senior Manager” }:

db.runCommand(

{ updateUser: “manager”,

pwd: “KNlZmiaNUp0B”,

customData: { title: “Senior Manager” }

}

)