db.updateRole()

Definition

• db.updateRole(rolename, update, writeConcern)
• Updates a user-defined role. Thedb.updateRole() method must run on the role’s database.

An update to a field completely replaces the previous field’s values.To grant or remove roles or privileges withoutreplacing all values, use one or more of the following methods:

• db.grantRolesToRole()
• db.grantPrivilegesToRole()
• db.revokeRolesFromRole()
• db.revokePrivilegesFromRole()

Warning

An update to the privileges or roles array completely replacesthe previous array’s values.

The updateRole() method uses the following syntax:

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

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

ParameterTypeDescriptionrolenamestringThe name of the user-defined role to update.updatedocumentA document containing the replacement data for the role. Thisdata completely replaces the corresponding data for the role.writeConcerndocumentOptional. The level of write concern for theupdate operation. The writeConcern document takes the samefields as the getLastError command.

The update document specifies the fields to update and the newvalues. Each field in the update document is optional, but thedocument must include at least one field. The update document has thefollowing fields:

FieldTypeDescriptionprivilegesarrayOptional. Required if you do not specify roles array.The privileges to grant the role. An update to the privilegesarray overrides the previous array’s values. For the syntax forspecifying a privilege, see the privilegesarray.rolesarrayOptional. Required if you do not specify privileges array.The roles from which this role inherits privileges. An update to theroles array overrides the previous array’s values.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.updateRole() method wraps the updateRolecommand.

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.updateRole() 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.updateRole() 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.

Required Access

You must have the revokeRoleaction on all databases in order to update a role.

You must have the grantRoleaction on the database of each role in the roles arrayto update the array.

You must have the grantRoleaction on the database of each privilegein the privileges array to update the array. If a privilege’sresource spans databases, you must have grantRole on theadmin database. A privilege spans databases if the privilege is any ofthe following:

• a collection in all databases
• all collections and all database
• the cluster resource

You must have the setAuthenticationRestrictionaction on the database of the targetrole to update a role’s authenticationRestrictions document.

Example

The following db.updateRole() method replaces theprivileges and theroles for the inventoryControl rolethat exists in the products database. The method runs on thedatabase that contains inventoryControl:

use products
db.updateRole(
    "inventoryControl",
    {
      privileges:
          [
            {
              resource: { db:"products", collection:"clothing" },
              actions: [ "update", "createCollection", "createIndex"]
            }
          ],
      roles:
          [
            {
              role: "read",
              db: "products"
            }
          ]
    },
    { w:"majority" }
)

To view a role’s privileges, use the rolesInfo command.