From c6276f3fa6128b2dace20b64e4454afd88e45ecb Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 27 Nov 2013 15:25:51 -0500 Subject: [PATCH] DOCS-2246 add updateRole method --- bin/builddata/htaccess-next.yaml | 8 ++ source/includes/access-update-role.rst | 18 +++ .../ref-toc-method-role-management.yaml | 10 +- .../reference/command/updateRole-field.yaml | 1 + source/reference/command/updateRole.txt | 82 +++++++------- .../reference/method/db.updateRole-param.yaml | 28 +++++ .../method/db.updateRole-update-fields.yaml | 8 ++ source/reference/method/db.updateRole.txt | 103 ++++++++++++++++++ 8 files changed, 214 insertions(+), 44 deletions(-) create mode 100644 source/includes/access-update-role.rst create mode 100644 source/reference/method/db.updateRole-param.yaml create mode 100644 source/reference/method/db.updateRole-update-fields.yaml create mode 100644 source/reference/method/db.updateRole.txt diff --git a/bin/builddata/htaccess-next.yaml b/bin/builddata/htaccess-next.yaml index df5ba29ebb4..df5fb30a29c 100644 --- a/bin/builddata/htaccess-next.yaml +++ b/bin/builddata/htaccess-next.yaml @@ -609,6 +609,14 @@ redirect-path: '/reference/method/db.revokePrivilegesFromRole' url-base: '/reference/security' type: 'redirect' code: 303 +outputs: + - 'manual' + - 'before-v2.4' +--- +redirect-path: '/reference/method/db.updateRole' +url-base: '/reference/security' +type: 'redirect' +code: 303 outputs: - 'manual' - 'before-v2.4' diff --git a/source/includes/access-update-role.rst b/source/includes/access-update-role.rst new file mode 100644 index 00000000000..8e437d2c239 --- /dev/null +++ b/source/includes/access-update-role.rst @@ -0,0 +1,18 @@ +A user must have the :authaction:`revokeRole` :ref:`action +` on all databases in order to update a role. + +A user must have the :authaction:`grantRole` :ref:`action +` on the database of each role in the ``roles`` array +to update the array. + +A user must have the :authaction:`grantRole` action on the database of each +privilege in the ``privileges`` array to update the array. If a privilege's +resource spans databases, the user must have :authaction:`grantRole` on the +``admin`` 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 diff --git a/source/includes/ref-toc-method-role-management.yaml b/source/includes/ref-toc-method-role-management.yaml index c2ad028c828..d5d3db62497 100644 --- a/source/includes/ref-toc-method-role-management.yaml +++ b/source/includes/ref-toc-method-role-management.yaml @@ -3,11 +3,11 @@ # description: | # Creates a role and specifies its privileges. # --- -# name: :method:`db.updateRole()` -# file: /reference/method/db.updateRole -# description: | -# Updates a user-defined role. -# --- +name: :method:`db.updateRole()` +file: /reference/method/db.updateRole +description: | + Updates a user-defined role. +--- name: :method:`db.dropRole()` file: /reference/method/db.dropRole description: | diff --git a/source/reference/command/updateRole-field.yaml b/source/reference/command/updateRole-field.yaml index 527041cbb4a..85dae17e04a 100644 --- a/source/reference/command/updateRole-field.yaml +++ b/source/reference/command/updateRole-field.yaml @@ -1,3 +1,4 @@ +#content from this page is included in /reference/method/db.updateRole-update-fields.yaml object: name: updateRole type: dbcommand diff --git a/source/reference/command/updateRole.txt b/source/reference/command/updateRole.txt index d664804e6e2..90ebbed5888 100644 --- a/source/reference/command/updateRole.txt +++ b/source/reference/command/updateRole.txt @@ -9,16 +9,22 @@ Definition .. dbcommand:: updateRole - Updates the role on the database on which you run the command. An - update to a field **completely replaces** the previous field's - values. + Updates a ref:`user-defined role `. The + :dbcommand:`updateRole` 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 without replacing all values, use + one or more of the following commands: + + - :command:`grantRolesToRole` + - :command:`grantPrivilegesToRole` + - :command:`revokeRolesFromRole` + - :command:`revokePrivilegesFromRole` .. warning:: - When you update the ``privileges`` or ``roles`` arrays, you - completely replace the previous array's values. To add roles - without replacing the existing roles, use the - :dbcommand:`grantRolesToRole` command. + An update to the ``privileges`` or ``roles`` array + completely replaces the previous array's values. The :dbcommand:`updateRole` command uses the following syntax. To update a role, you must provide the ``privileges`` array, ``roles`` @@ -26,16 +32,20 @@ Definition .. code-block:: javascript - { updateRole: "", - privileges: [ - { resource: { }, actions: [ "", ... ] }, - ... - ], - roles: [ - { role: "", db: "" }, - ... - ], + { + updateRole: "", + privileges: + [ + { resource: { }, actions: [ "", ... ] }, + ... + ], + roles: + [ + { role: "", db: "" }, + ... + ], writeConcern: + } The :dbcommand:`updateRole` command has the following fields: @@ -47,20 +57,7 @@ Definition Required Access --------------- -To run the :dbcommand:`updateRole` command, a user must have privileges -that include the :authaction:`revokeRole` action on all databases, -as well as: - -- To update the ``roles`` array, a user must have privileges that - include the :authaction:`grantRole` action on the database for - every role in the updated array. - -- To update the ``privileges`` array, a user must have - :authaction:`grantRole` on the database for each privilege in the - updated array. If the resource for the privilege is a collection in - all databases, or all collections and all database, or the - ``cluster`` resource, you must have :authaction:`grantRole` on - the ``admin`` database. +.. include:: /includes/access-update-role.rst Example ------- @@ -72,13 +69,20 @@ the two is required: .. code-block:: javascript - { updateRole: "myClusterwideAdmin", - privileges: [ - { resource: { db: "", collection: "" }, - actions: [ "find" , "update", "insert", "remove" ] } - ], - roles: [ - { role: "dbAdminAnyDatabase", db: "admin" } - ], - writeConcern: { w: "majority" , wtimeout: 5000 } + { + 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 :dbcommand:`rolesInfo` command. diff --git a/source/reference/method/db.updateRole-param.yaml b/source/reference/method/db.updateRole-param.yaml new file mode 100644 index 00000000000..7af4504f29e --- /dev/null +++ b/source/reference/method/db.updateRole-param.yaml @@ -0,0 +1,28 @@ +object: + name: db.updateRole() + type: method +field: + optional: false + type: param +name: rolename +type: string +position: 1 +description: | + The name of the role to update. +--- +object: + name: db.updateRole() + type: method +field: + optional: false + type: param +name: update +type: document +position: 2 +description: | + A document containing the role data to replace with new data. +--- +file: /reference/command/updateRole-field.yaml +name: writeConcern +position: 3 +... diff --git a/source/reference/method/db.updateRole-update-fields.yaml b/source/reference/method/db.updateRole-update-fields.yaml new file mode 100644 index 00000000000..b478628b148 --- /dev/null +++ b/source/reference/method/db.updateRole-update-fields.yaml @@ -0,0 +1,8 @@ +file: /reference/command/updateRole-field.yaml +name: privileges +position: 1 +--- +file: /reference/command/updateRole-field.yaml +name: roles +position: 2 +... diff --git a/source/reference/method/db.updateRole.txt b/source/reference/method/db.updateRole.txt new file mode 100644 index 00000000000..ecc79f46515 --- /dev/null +++ b/source/reference/method/db.updateRole.txt @@ -0,0 +1,103 @@ +=============== +db.updateRole() +=============== + +.. default-domain:: mongodb + +Definition +---------- + +.. method:: db.updateRole( rolename, update, writeConcern ) + + Updates a ref:`user-defined role `. The + :method:`db.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 without replacing all values, use + one or more of the following methods: + + - :method:`db.grantRolesToRole()` + - :method:`db.grantPrivilegesToRole()` + - :method:`db.revokeRolesFromRole()` + - :method:`db.revokePrivilegesFromRole()` + + .. warning:: + + An update to the ``privileges`` or ``roles`` array completely replaces + the previous array's values. + + The :method:`updateRole()` method uses the following syntax: + + .. code-block:: javascript + + db.updateRole( + "", + { + privileges: + [ + { resource: { }, actions: [ "", ... ] }, + ... + ], + roles: + [ + { role: "", db: "" }, + ... + ] + }, + { } + ) + + The :method:`db.updateRole()` method takes the following arguments. + + .. include:: /reference/method/db.updateRole-param.rst + + The ``update`` document specifies the fields to update and the new + values. Each field in the ``update`` document is optional, but the + document must include at least one field. The ``update`` document has the + following fields: + + .. include:: /reference/method/db.updateRole-update-fields.rst + + .. |local-cmd-name| replace:: :method:`db.updateRole()` + .. include:: /includes/fact-roles-array-contents.rst + + The :method:`db.updateRole()` method wraps the :dbcommand:`updateRole` + command. + +Required Access +--------------- + +.. include:: /includes/access-update-role.rst + +Example +------- + +The following :method:`db.updateRole()` method replaces the +:data:`~admin.system.roles.privileges` and the +:data:`~admin.system.roles.roles` for the ``inventoryControl`` role. The +method runs on the database that contains ``inventoryControl``: + +.. code-block:: javascript + + 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 :dbcommand:`rolesInfo` command.