fixes to various auth pages a la 2.5.3 redux as they say in the movies

Author: kay-kim

bin/builddata/htaccess-next.yaml

@@ -206,7 +206,7 @@ outputs:
   - 'manual'
   - 'before-v2.4'
 ---
-redirect-path: '/reference/command/dropRolesFromDatabase'
+redirect-path: '/reference/command/dropAllRolesFromDatabase'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
@@ -222,7 +222,7 @@ outputs:
   - 'manual'
   - 'before-v2.4'
 ---
-redirect-path: '/reference/command/dropUsersFromDatabase'
+redirect-path: '/reference/command/dropAllUsersFromDatabase'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
@@ -254,7 +254,15 @@ outputs:
   - 'manual'
   - 'before-v2.4'
 ---
-redirect-path: '/reference/command/nav-user-role'
+redirect-path: '/reference/command/nav-role-management'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/command/nav-user-management'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
@@ -381,4 +389,51 @@ code: 303
 outputs:
   - 'manual'
   - 'before-v2.4'
-...
+---
+redirect-path: '/reference/resource-document'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/privilege-actions'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/system-defined-roles'
+url-base: '/reference/user-privileges'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/user-privileges'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'after-v2.4'
+---
+redirect-path: '/reference/system-roles-collection'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/system-users-collection'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+...

source/core/access-control.txt

@@ -51,14 +51,70 @@ 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 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 authorization. A role grants privileges to users, where
+privileges specify the :doc:`actions </reference/privilege-actions>`
+permitted on various :ref:`resources <resource-document>`.
 
-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
+.. _user-defined-roles:
+
+User-Defined Roles
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.6
+
+In addition to the MongoDB :doc:`system-defined roles
+</reference/system-defined-roles>`, MongoDB provides the ability to create
+and manage custom roles. To create a role is to define its privileges
+by pairing :ref:`resources <resource-document>` (e.g. database,
+collection) with :doc:`actions </reference/privilege-actions>` (e.g.
+``insert``, ``find``), and/or by specifying other roles from which the
+role inherits privileges. 
+
+To create and manage roles, MongoDB provides :ref:`role management
+commands <role-management-commands>`. MongoDB scopes each role to the
+database in which it is created and uniquely identifies each role by
+the pairing of its name and its database. MongoDB stores the
+user-defined roles information in the :doc:`system.roles collection
+</reference/system-roles-collection>` of the ``admin`` database.
+
+.. seealso:: :dbcommand:`createRole` and :ref:`role-management-commands`.
+
+.. _collection-level-access-control:
+
+Collection-Level Access Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.6
+
+MongoDB provides the ability to specify user privileges at a
+collection-level granularity. To specify collection-level access
+control, create a custom role that pairs its actions to a particular
+collection in a specific database in the :ref:`resource document
+<resource-document>`. 
+
+The MongoDB :doc:`system-defined roles </reference/system-defined-roles>`
+grant privileges at a database-level only, and thus cannot be used to
+control privileges at the collection-level.
+
+Role Assignment to Users
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can have multiple roles and can have different roles on different
+resources. Assigning roles to a user authorizes the user to have only
+the privileges granted by the roles. Roles always grant privileges and
+never limit access. For example, if a user has both :authrole:`read`
+*and* :authrole:`readWriteAnyDatabase` roles on a database, the greater
+access prevails. A user's role assignments can include
+:ref:`system-defined roles <system-user-roles>` provided by MongoDB or
+a :ref:`custom roles <user-defined-roles>` defined by the user.
+
+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`.
 
-MongoDB requires authorization to manage users in order to prevent
-privilege escalation attacks.
+MongoDB stores each user's role assignments in the ``admin`` database's
+:doc:`system.users collection </reference/system-users-collection>`. To
+manage data in this collection, MongoDB provides :ref:`user management
+commands <user-management-commands>`, which require proper
+authorization to use in order to prevent privilege escalation attacks.

source/core/sharded-cluster-security.txt

@@ -33,7 +33,7 @@ privileges for the sharded cluster and for each shard.
    reside on the config servers.
 
    Users can access to the cluster according to their
-   :doc:`permissions </reference/user-privileges>`. To receive
+   :doc:`permissions </core/access-control>`. To receive
    privileges for the cluster, you must authenticate while connected
    to a :program:`mongos` instance.
 

source/includes/access-create-role.rst

@@ -7,6 +7,6 @@ targets. If the privilege targets multiple databases or the
 ``cluster`` resource , the user must have access that includes the :authaction:`grantAnyRole`
 action on the ``admin`` database.
 
-To add a role to the :data:`~admin.system.roles.roles` array, a
+To specify roles from which the new role inherits from, a
 user must have access that includes the
-:authaction:`grantAnyRole` action on the contained role's database.
+:authaction:`grantAnyRole` action on the inherited role's database.

source/includes/fact-roles-array-contents.rst

@@ -1,9 +1,15 @@
-.. the including document should define a |local-cmd-name| replacement.
-
-In the ``roles`` field you can specify both
-:ref:`system roles <system-user-roles>` and custom roles created
-with |local-cmd-name|. The ``roles`` 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.
+.. the including document should define a |local-cmd-name| replacement
+
+In the ``roles`` field, you can specify both
+:ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+role <user-defined-roles>`. In general, when used with
+|local-cmd-name|, specify the role with a document, as in:
+
+.. code-block:: javascript
+
+   { role: "<role>", db: "<database>" }
+
+However, to refer to a role that exists in the same database the
+command is run, you can specify the role either with a role document
+(e.g. ``{ role: "readWrite", db: "sameDB" }`` ) or with just the role
+name (e.g. ``"readWrite"``).

source/includes/manpage-options-auth.rst

@@ -13,7 +13,7 @@
 
    .. include:: /includes/fact-authentication-source-tool.rst
 
-   See :doc:`/reference/user-privileges` for more information on
+   See :doc:`/core/access-control` for more information on
    authentication in MongoDB.
 
 .. option:: --authenticationMechanism <name>

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

@@ -0,0 +1,36 @@
+name: :dbcommand:`createRole`
+file: /reference/command/createRole
+description: "Creates a role and specifies its privileges."
+---
+name: :dbcommand:`updateRole`
+file: /reference/command/updateRole
+description: "Updates a user-defined role."
+---
+name: :dbcommand:`dropRole`
+file: /reference/command/dropRole
+description: "Deletes the user-defined role."
+---
+name: :dbcommand:`dropAllRolesFromDatabase`
+file: /reference/command/dropAllRolesFromDatabase
+description: "Deletes all user-defined roles from a database."
+---
+name: :dbcommand:`grantPrivilegesToRole`
+file: /reference/command/grantPrivilegesToRole
+description: "Assigns privileges to a user-defined role."
+---
+name: :dbcommand:`revokePrivilegesFromRole`
+file: /reference/command/revokePrivilegesFromRole
+description: "Removes the specified privileges from a user-defined role."
+---
+name: :dbcommand:`grantRolesToRole`
+file: /reference/command/grantRolesToRole
+description: "Specifies roles from which a user-defined role inherits privileges."
+---
+name: :dbcommand:`revokeRolesFromRole`
+file: /reference/command/revokeRolesFromRole
+description: "Removes specified inherited roles from a user-defined role."
+---
+name: :dbcommand:`rolesInfo`
+file: /reference/command/rolesInfo
+description: "Returns information for the specified role or roles."
+...

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

@@ -0,0 +1,28 @@
+name: :dbcommand:`createUser`
+file: /reference/command/createUser
+description: "Creates a new user."
+---
+name: :dbcommand:`updateUser`
+file: /reference/command/updateUser
+description: "Updates a user privilege document."
+---
+name: :dbcommand:`dropUser`
+file: /reference/command/dropUser
+description: "Removes a single user."
+---
+name: :dbcommand:`dropAllUsersFromDatabase`
+file: /reference/command/dropAllUsersFromDatabase
+description: "Deletes all users associated with a database."
+---
+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."
+...

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

@@ -1,16 +1,24 @@
-file: /reference/user-privileges
+file: /reference/system-defined-roles
 description: |
-  Reference on user privilege roles and corresponding access.
+  Reference on MongoDB provided roles and corresponding access.
 ---
-file: /reference/roles-collection
+file: /reference/system-roles-collection
 description: |
-  Describes the content of the collection that stores custom user roles.
+  Describes the content of the collection that stores user-defined roles.
 ---
-file: /reference/users-collection
+file: /reference/system-users-collection
 description: |
   Describes the content of the collection that stores users' credentials and
   role assignments.
 ---
+file: /reference/resource-document
+description: |
+  Describes the resource document for roles.
+---
+file: /reference/privilege-actions
+description: |
+  List of the actions available for privileges.
+---
 file: /reference/default-mongodb-port
 description: |
   List of default ports used by MongoDB.