updateRole

Definition

• updateRole
• Updates a user-defined role. TheupdateRole command 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 commands:

• grantRolesToRole
• grantPrivilegesToRole
• revokeRolesFromRole
• revokePrivilegesFromRole

Warning

An update to the privileges or roles arraycompletely replaces the previous array’s values.

The updateRole command uses the following syntax. Toupdate a role, you must provide the privileges array, rolesarray, or both:

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

The updateRole command has the following fields:

FieldTypeDescriptionupdateRolestringThe name of the user-defined role role to update.privilegesarrayOptional. 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.

writeConcerndocumentOptional. The level of write concern for theupdate operation. The writeConcern document takes the samefields as 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 whereupdateRole 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

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 is an example of the updateRole command thatupdates the myClusterwideAdmin role on the admin database.While the privileges and theroles arrays are both optional, at leastone of the two is required:

db.adminCommand(
   {
     updateRole: "myClusterwideAdmin",
     privileges:
         [
           {
             resource: { db: "", collection: "" },
             actions: [ "find" , "update", "insert", "remove" ]
           }
         ],
     roles:
         [
           { role: "dbAdminAnyDatabase", db: "admin" }
         ],
     writeConcern: { w: "majority" }
   }
)

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