DOCS-1980, DOCS-1934, DOCS-1935, DOCS-1936: new user and role features

source/core/access-control.txt

@@ -16,8 +16,8 @@ Authentication
 MongoDB provisions authentication, or verification of the user
 identity, on a per-database level. Authentication disables anonymous
 access to the database. For basic authentication, MongoDB stores the
-user credentials in a database's :data:`system.users
-<<database>.system.users>` collection.
+user credentials in the ``admin`` database's :data:`system.users
+<admin.system.users>` collection.
 
 Authentication is **disabled** by default. To enable authentication for
 a given :program:`mongod` or :program:`mongos` instance, use the
@@ -51,37 +51,14 @@ Authorization
 
 MongoDB provisions authorization, or access to databases and
 operations, on a per-database level. MongoDB uses a role-based approach
-to authorization, storing each user's roles in a :doc:`privilege
-document </reference/user-privileges>` in a database's
-:data:`system.users <<database>.system.users>` collection. For more
-information on privilege documents and available user roles, see
-:doc:`/reference/privilege-documents` and
-:doc:`/reference/user-privileges`.
-
-.. important:: The ``admin`` database provides roles that are
-   *unavailable* in other databases, including a role that effectively
-   makes a user a MongoDB system superuser. See
-   :ref:`database-admin-roles` and :ref:`admin-roles`.
-
-To assign roles to users, you must be a user with administrative role
+to authorization, storing each user's role assignments in the ``admin``
+database's :data:`system.users <admin.system.users>` collection. For
+more information on roles, see :doc:`/reference/user-privileges`.
+
+To assign roles to users, you must be a user with an administrative role
 in the database. As such, you must first create an administrative user.
 For details, see :doc:`/tutorial/add-user-administrator` and
 :doc:`/tutorial/add-user-to-database`.
 
-``system.users`` Collection
----------------------------
-
-A database's :data:`system.users <<database>.system.users>` collection
-stores information for authentication and authorization to that
-database. Specifically, the collection stores user credentials for
-authentication and user privilege information for authorization.
-MongoDB requires authorization to access the :data:`system.users
-<<database>.system.users>` collection in order to prevent privilege
-escalation attacks. To access the collection, you must have either
-:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role.
-
-.. versionchanged:: 2.4 
-   The schema of :data:`system.users <<database>.system.users>` changed
-   to accommodate a more sophisticated authorization using user
-   privilege model, as defined in :doc:`privilege documents
-   </reference/user-privileges>`.
+MongoDB requires authorization to manage users in order to prevent
+privilege escalation attacks.

source/includes/manpage-options-auth.rst

@@ -13,10 +13,8 @@
 
    .. include:: /includes/fact-authentication-source-tool.rst
 
-   See :data:`~<database>.system.users.userSource`,
-   :doc:`/reference/privilege-documents` and
-   :doc:`/reference/user-privileges` for more information about
-   delegated authentication in MongoDB.
+   See :doc:`/reference/user-privileges` for more information about
+   authentication in MongoDB.
 
 .. option:: --authenticationMechanism <name>
 

source/includes/ref-toc-command-user-role.yaml

@@ -0,0 +1,64 @@
+name: :dbcommand:`createUser`
+file: /reference/command/createUser
+description: "Creates a new user in the database where the command is run."
+---
+name: :dbcommand:`updateUser`
+file: /reference/command/updateUser
+description: "Updates the user's profile in the database where the command is run."
+---
+name: :dbcommand:`dropUser`
+file: /reference/command/dropUser
+description: "Removes the user from the database on which you run the command."
+---
+name: :dbcommand:`dropUsersFromDatabase`
+file: /reference/command/dropUsersFromDatabase
+description: "Deletes all users from the database on which you run the command."
+---
+name: :dbcommand:`grantRolesToUser`
+file: /reference/command/grantRolesToUser
+description: "Grants a role and its privileges to a user."
+---
+name: :dbcommand:`revokeRolesFromUser`
+file: /reference/command/revokeRolesFromUser
+description: "Removes a role from a user."
+---
+name: :dbcommand:`usersInfo`
+file: /reference/command/usersInfo
+description: "Returns information about the specified users."
+---
+name: :dbcommand:`createRole`
+file: /reference/command/createRole
+description: "Creates a role and specifies its privileges."
+---
+name: :dbcommand:`updateRole`
+file: /reference/command/updateRole
+description: "Updates the role on the database on which you run the command."
+---
+name: :dbcommand:`dropRole`
+file: /reference/command/dropRole
+description: "Deletes the role from the database on which you run the command."
+---
+name: :dbcommand:`dropRolesFromDatabase`
+file: /reference/command/dropRolesFromDatabase
+description: "Deletes all roles from the database on which you run the command."
+---
+name: :dbcommand:`grantPrivilegesToRole`
+file: /reference/command/grantPrivilegesToRole
+description: "Assigns privileges to a role."
+---
+name: :dbcommand:`revokePrivilegesFromRole`
+file: /reference/command/revokePrivilegesFromRole
+description: "Removes the specified privileges from the role."
+---
+name: :dbcommand:`grantRolesToRole`
+file: /reference/command/grantRolesToRole
+description: "Specifies roles from which a role inherits privileges."
+---
+name: :dbcommand:`revokeRolesFromRole`
+file: /reference/command/revokeRolesFromRole
+description: "Removes child roles from a role."
+---
+name: :dbcommand:`rolesInfo`
+file: /reference/command/rolesInfo
+description: "Lists the privileges and child roles that a role contains."
+...

source/includes/toc-security-reference.yaml

@@ -2,10 +2,14 @@ file: /reference/user-privileges
 description: |
   Reference on user privilege roles and corresponding access.
 ---
-file: /reference/privilege-documents
+file: /reference/roles-collection
 description: |
-  Reference on documents used to store user credentials and privilege
-  roles.
+  Describes the collection that stores custom user roles.
+---
+file: /reference/users-collection
+description: |
+  Describes the collection that stores each user's credentials and
+  role assignments.
 ---
 file: /reference/default-mongodb-port
 description: |

source/reference/command.txt

@@ -77,6 +77,23 @@ Authentication Commands
 
       /reference/command/nav-authentication
 
+.. _user-management-commands:
+.. _role-management-commands:
+
+User and Role Management Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. only:: website
+
+   .. include:: /includes/toc/table-command-user-role.rst
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /reference/command/nav-user-role
+
 Replication Commands
 ~~~~~~~~~~~~~~~~~~~~
 

source/reference/command/createRole-field.yaml

@@ -0,0 +1,59 @@
+object:
+  name: createRole
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: createRole
+type: string
+position: 1
+description: |
+  The name of the new role.
+---
+object:
+  name: createRole
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: privileges
+type: array
+position: 2
+description: |
+description: |
+  The privileges to grant the role. A privilege consists of a resource
+  and permitted actions. For the syntax for specifying a privilege, see
+  the :data:`~admin.system.roles.privileges` array.
+---
+object:
+  name: createRole
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: roles
+type: array
+position: 3
+description: |
+  Roles from which this role inherits privileges. You can specify both
+  :ref:`system roles <system-user-roles>` and custom roles created with
+  :dbcommand:`createRole`. The array can take both documents and
+  strings. Specify a role as a document if the role exists in another
+  database. Specify the role as a string name if it exists in the
+  current database. For more information on specifying roles, see
+  the :data:`~admin.system.roles.roles` array.
+---
+object:
+  name: createRole
+  type: dbcommand
+field:
+  optional: true
+  type: field
+name: writeConcern
+type: document
+position: 4
+description: |
+  The level of :doc:`write concern </reference/write-concern>` to apply
+  to this operation. The ``writeConcern`` document uses the same fields
+  as the :dbcommand:`getLastError` command.
+...

source/reference/command/createRole.txt

@@ -0,0 +1,71 @@
+==========
+createRole
+==========
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. dbcommand:: createRole
+
+   Creates a role and specifies its privileges. The role applies to the
+   database on which you run the command. The :dbcommand:`createRole`
+   command returns a duplicate role error if the role already exists in
+   the database.
+
+   To create a role, you must have the :authaction:`createRole` action
+   on the database.
+
+   To specify a privilege to the role, you must have the
+   :authaction:`grantAnyRole` action on the database the privilege
+   targets. If the privilege targets multiple databases or the
+   ``cluster`` resource , you must have the :authaction:`grantAnyRole`
+   action on the ``admin`` database.
+
+   To grant a child role to the role, you must have the
+   :authaction:`grantAnyRole` action on the child role's database.
+
+   The :dbcommand:`createRole` command uses the following syntax:
+
+   .. code-block:: javascript
+
+      { createRole: "<new role>",
+        privileges: [
+          { resource: { <resource> }, actions: [ "<action>", ... ] },
+          ...
+        ],
+        roles: [
+          { role: "<role>", db: "<database>" },
+          ...
+        ],
+        writeConcern: <write concern document>
+      }
+
+   Both the ``privileges`` and ``roles`` fields must be present. If you
+   choose not to specify privileges or roles, you must provide an empty
+   array for that field.
+
+   The :dbcommand:`createRole` command has the following fields:
+
+   .. include:: /reference/command/createRole-field.rst
+
+Example
+-------
+
+The following is an example of the :dbcommand:`createRole` command:
+
+.. code-block:: javascript
+
+   { createRole: "myClusterwideAdmin",
+     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" }
+     ],
+     writeConcern: { w: "majority" , wtimeout: 5000 }
+   }

source/reference/command/createUser-field.yaml

@@ -0,0 +1,75 @@
+object:
+  name: createUser
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: createUser
+type: string
+position: 1
+description: |
+  The name of the new user.
+---
+object:
+  name: createUser
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: pwd
+type: string
+position: 2
+description: |
+  The user's password. The password is sent to the server in cleartext.
+  To encrypt the password in transit use SSL. The ``pwd`` field is not
+  required if you run :dbcommand:`createUser` on the ``$external``
+  database. Users created on ``$external`` are assumed to have
+  credentials stored externally to MongoDB, as, for example, with
+  :doc:`MongoDB Enterprise installations that use Kerberos
+  </tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
+---
+object:
+  name: createUser
+  type: dbcommand
+field:
+  optional: true
+  type: any
+name: customData
+type: document
+position: 3
+description: |
+  Any arbitrary information.
+---
+object:
+  name: createUser
+  type: dbcommand
+field:
+  optional: false
+  type: field
+name: roles
+type: array
+position: 4
+description: |
+  The roles granted to the user. You can specify both :ref:`system roles
+  <system-user-roles>` and custom roles created with
+  :dbcommand:`createRole`. The array can take both documents and
+  strings. Specify a role as a document if the role exists in another
+  database. Specify the role as a string name if it exists in the
+  current database. To create a user without roles, specify an empty
+  ``roles`` array. For more information on specifying a role, see
+  the :data:`~admin.system.users.roles` array.
+---
+object:
+  name: createUser
+  type: dbcommand
+field:
+  optional: true
+  type: field
+name: writeConcern
+type: document
+position: 5
+description: |
+  The level of :doc:`write concern </reference/write-concern>` to apply
+  to this operation. The ``writeConcern`` document uses the same fields
+  as the :dbcommand:`getLastError` command.
+...