createRole

Definition

• createRole
• Creates a role and specifies its privileges.The role applies to thedatabase on which you run the command. The createRolecommand returns a duplicate role error if the role already exists inthe database.

The createRole command uses the following syntax:

{ createRole: "<new role>",
  privileges: [
    { resource: { <resource> }, actions: [ "<action>", ... ] },
    ...
  ],
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  authenticationRestrictions: [
    {
      clientSource: ["<IP>" | "<CIDR range>", ...],
      serverAddress: ["<IP>" | "<CIDR range>", ...]
    },
    ...
  ],
  writeConcern: <write concern document>
}

The createRole command has the following fields:

FieldTypeDescriptioncreateRolestringThe 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.

writeConcerndocumentOptional. The level of write concern to applyto this operation. The writeConcern document uses the same fieldsas the getLastError command.

Roles

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

To specify a role that exists in the same database wherecreateRole 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

A role’s privileges apply to the database where the role is created. Therole can inherit privileges from other roles in its database. A rolecreated on the admin database can include privileges that apply to alldatabases or to the cluster and can inheritprivileges from roles in other databases.

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 createRole command creates themyClusterwideAdmin role on the admin database:

db.adminCommand({ createRole: "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" }
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
})