MongoDB: db.createRole() method

Last update on August 19 2022 21:51:25 (UTC/GMT +8 hours)

db.createRole()

The db.createRole() method is used to create a role in a database and privileges for that role can be specified 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.

Syntax:

db.createRole(role, writeConcern)

Parameters:

Name	Description	Required / Optional	Type
role	A document containing the name of the role and the role definition.	Required	document
writeConcern	The level of write concern to apply to this operation. The writeConcern document uses the same fields as the getLastError command.	Optional	document

The role document has the following form:

{
  role: "<name>",
  privileges: [
     { resource: { <resource> }, actions: [ "<action>", ... ] },
     ...
  ],
  roles: [
     { role: "<role>", db: "<database>" } | "<role>",
      ...
  ]
}

The role document has the following fields:

Field	Description	Type
role	The name of the new role.	string
privileges	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.	array
roles	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.	array

In the roles field, you can specify both built-in roles and user-defined role.

To specify a role that exists in the same database where db.createRole() runs, you can either specify the role with the name of the 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 role with a document.

Example: MongoDB: db.createRole() method

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

use admin
db.createRole(
   {
     role: "myroll1",
     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 }
);

Output:

{
        "role" : "myroll1",
        "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"
                }
        ]
}

Retrieve the restaurants data from here

Behavior

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.

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

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.

Previous: db.getUsers() method
Next: db.updateRole() method