db.createRole()

Definition

• db.createRole(role, writeConcern)
• Creates a role in a database. You can specify privileges for therole by explicitly listing the privileges or by having the roleinherit privileges from other roles or both. The role applies tothe database on which you run the method.

The db.createRole() method accepts the following arguments:

ParameterTypeDescriptionroledocumentA document containing the name of the role and the role definition.writeConcerndocumentOptional. The level of write concern to applyto this operation. The writeConcern document uses the same fieldsas the getLastError command.

The role document has the following form:

{
  role: "<name>",
  privileges: [
     { resource: { <resource> }, actions: [ "<action>", ... ] },
     ...
  ],
  roles: [
     { role: "<role>", db: "<database>" } | "<role>",
      ...
  ],
  authenticationRestrictions: [
    {
      clientSource: ["<IP>" | "<CIDR range>", ...],
      serverAddress: ["<IP>" | "<CIDR range>", ...]
    },
    ...
  ]
}

The role document has the following fields:

FieldTypeDescriptionrolestringThe name of the new role.privilegesarrayThe privileges to grant the role. A privilege consists of a resourceand permitted actions. For the syntax of a privilege, see theprivileges array.

You must include the privileges field. Use anempty array to specify no privileges.rolesarrayAn array of roles from which this role inherits privileges.

You must include the roles field. Use an empty array to specifyno roles to inherit from.authenticationRestrictionsarrayOptional.

The authentication restrictions the server enforces on the role.Specifies a list of IP addresses andCIDR ranges users granted thisrole are allowed to connect to and/or which they can connect from.

New in version 3.6.

The db.createRole() method wraps the createRolecommand.

Roles

In the roles field, you can specify bothbuilt-in roles and user-definedroles.

To specify a role that exists in the same database wheredb.createRole() runs, you can either specify the role with the name ofthe role:

"readWrite"

Or you can specify the role with a document, as in:

{ role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the rolewith a document.

Authentication Restrictions

New in version 3.6.

The authenticationRestrictions document can contain only thefollowing fields. The server throws an error if theauthenticationRestrictions document contains an unrecognized field:

Important

If a user inherits multiple roles with incompatible authenticationrestrictions, that user becomes unusable.

For example, if a user inherits one role in which theclientSource field is ["198.51.100.0"] and another role inwhich the clientSource field is ["203.0.113.0"] the server isunable to authenticate the user.

For more information on authentication in MongoDB, seeAuthentication.

Behavior

Replica set

If run on a replica set, db.createRole() is executed using majority write concern by default.

Scope

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

A role created in the admin database can include privileges thatapply to the admin database, other databases or to thecluster resource, and can inherit from rolesin other databases as well as the admin database.

The db.createRole() method returns a duplicate role errorif the role already exists in the database.

Required Access

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

• the createRoleaction onthat database resource.
• the grantRoleaction onthat database to specify privileges for the new role as well as tospecify roles to inherit from.

Built-in roles userAdmin anduserAdminAnyDatabase provide createRole andgrantRole actions on their respective resources.

To create a role with authenticationRestrictions specified, youmust have the setAuthenticationRestrictionaction on thedatabase resource which the role iscreated.

Example

The following db.createRole() method creates themyClusterwideAdmin role on the admin database:

use admin
db.createRole(
   {
     role: "myClusterwideAdmin",
     privileges: [
       { resource: { cluster: true }, actions: [ "addShard" ] },
       { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
       { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
       { resource: { db: "", collection: "" }, actions: [ "find" ] }
     ],
     roles: [
       { role: "read", db: "admin" }
     ]
   },
   { w: "majority" , wtimeout: 5000 }
)