updateRole (original) (raw)

updateRole

Updates a user-defined role. TheupdateRole command must run on the role's database.

Tip

In mongosh, this command can also be run through the db.updateRole() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

An update to a field completely replaces the previous field's values. To grant or remove roles or privileges without replacing all values, use one or more of the following commands:

Warning

An update to the privileges or roles array completely replaces the previous array's values.

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

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Important

This command is not supported in M0, M2, M5, M10+, and Flex clusters. For more information, see Unsupported Commands.

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

To update a role, you must provide the privileges array, rolesarray, or both.

The command uses the following syntax:


db.runCommand(

   {

     updateRole: "<role>",

     privileges:

         [

           { resource: { <resource> }, actions: [ "<action>", ... ] },

           ...

         ],

     roles:

         [

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

           ...

         ],

     authenticationRestrictions:

         [

           {

             clientSource: ["<IP>" | "<CIDR range>", ...],

             serverAddress: ["<IP>", ...]

           },

           ...

         ]

     writeConcern: <write concern document>,

     comment: <any>

   }

 )

The command takes the following fields:

Field	Type	Description
updateRole	string	The name of the user-defined role role to update.
privileges	array	Optional. 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 for specifying a privilege, see the privilegesarray.
roles	array	Optional. 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.
authenticationRestrictions	array	Optional.The authentication restrictions the server enforces on the role. Specifies a list of IP addresses andCIDR ranges users granted this role are allowed to connect to and/or which they can connect from.
writeConcern	document	Optional. The level of write concern for the operation. See Write Concern Specification.
comment	any	Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:mongod log messages, in theattr.command.cursor.comment field.Database profiler output, in the command.comment field.currentOp output, in the command.comment field.A comment can be any valid BSON type(string, integer, object, array, etc).

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

To specify a role that exists in the same database whereupdateRole runs, you can either specify the role with the name of the role:

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.

The authenticationRestrictions document can contain only the following fields. The server throws an error if theauthenticationRestrictions document contains an unrecognized field:

Field Name	Value	Description
clientSource	Array of IP addresses and/orCIDR ranges	If present, when authenticating a user, the server verifies that the client's IP address is either in the given list or belongs to a CIDR range in the list. If the client's IP address is not present, the server does not authenticate the user.
serverAddress	Array of IP addresses and/orCIDR ranges	A list of IP addresses or CIDR ranges to which the client can connect. If present, the server will verify that the client's connection was accepted via an IP address in the given list. If the connection was accepted via an unrecognized IP address, the server does not authenticate the user.

Important

If a user inherits multiple roles with incompatible authentication restrictions, that user becomes unusable.

For example, if a user inherits one role in which theclientSource field is ["198.51.100.0"] and another role in which the clientSource field is ["203.0.113.0"] the server is unable to authenticate the user.

For more information on authentication in MongoDB, seeAuthentication on Self-Managed Deployments.

A role's privileges apply to the database where the role is created. The role can inherit privileges from other roles in its database. A role created on the admin database can include privileges that apply to all databases or to the cluster and can inherit privileges from roles in other databases.

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

You must have the grantRole action on the database of each role in the roles array to update the array.

You must have the grantRole action on the database of each privilege in the privileges array to update the array. If a privilege's resource spans databases, you must have grantRole on theadmin database. A privilege spans databases if the privilege is any of the following:

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

You must have the setAuthenticationRestriction action on the database of the target role to update a role's authenticationRestrictions document.

The following is an example of the updateRole command that updates the myClusterwideAdmin role on the admin database. While the privileges and theroles arrays are both optional, at least one 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.