db.createRole()

Definition

db.createRole(role, writeConcern)

Creates a role in a database. You can specify privileges for the role by explicitly listing the privileges or by having the role inherit privileges from other roles or both. The role applies to the database on which you run the method.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the createRole command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

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

Parameter	Type	Description
role	document	A document containing the name of the role and the role definition.
writeConcern	document	Optional. The level of write concern for the operation. See Write Concern Specification.

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:

Field	Type	Description
role	string	The name of the new role.
privileges	array	The privileges to grant the role. A privilege consists of a resource and permitted actions. For the syntax of a privilege, see the privileges array. You must include the privileges field. Use an empty array to specify no privileges.
roles	array	An array of roles from which this role inherits privileges. You must include the roles field. Use an empty array to specify no roles to inherit from.
authenticationRestrictions	array	Optional. The authentication restrictions the server enforces on the role. Specifies a list of IP addresses and CIDR ranges users granted this role are allowed to connect to and/or which they can connect from.

"readWrite"

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

Compatibility

This method is available in deployments hosted in the following environments:

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Behavior

privileges: [
     {
     resource: { db: 'products', collection: 'coll1' },
     actions: [ 'bypassDocumentValidation' ]
     },
     {
     resource: { db: 'products', collection: 'coll2' },
     actions: [ 'bypassDocumentValidation' ]
     }
]

privileges: [
     {
     resource: { db: 'products', collection: '' },
     actions: [ 'bypassDocumentValidation' ]
     }
]

Required Access

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.

Example

The following db.createRole() method creates the myClusterwideAdmin 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 }
)