DOCSP-18009: Refactor Security Users section

source/core/authentication.txt

@@ -30,7 +30,8 @@ Getting Started
 To get started using access control, follow these tutorials:
 
 - :ref:`enable-access-control`
-- :ref:`add-new-user`
+- :ref:`create-users`
+- :ref:`authentication-auth-as-user`
 
 .. _available-authentication-mechanisms:
 
@@ -71,3 +72,4 @@ for more information.
    /core/authentication-mechanisms
    /core/authentication-mechanisms-enterprise
    /core/security-internal-authentication
+   /core/localhost-exception

source/core/localhost-exception.txt

@@ -0,0 +1,67 @@
+.. _localhost-exception:
+
+===================
+Localhost Exception
+===================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. important::
+
+   On a :binary:`~bin.mongod` instance, the localhost exception only
+   applies when there are **no users or roles** created in the MongoDB
+   instance.
+
+The localhost exception allows you to enable access control and then
+create the first user or role in the system. After you enable access
+control, connect to the localhost interface and create the first user in
+the ``admin`` database.
+
+If you create a user first, the user must have privileges to create
+other users. The :authrole:`userAdmin` or
+:authrole:`userAdminAnyDatabase` role both confer the privilege to
+create other users.
+
+.. warning::
+
+   Connections using the localhost exception have access to create
+   *only* the **first user or role**.
+
+   Once you create any user or role, the localhost exception is
+   disabled. If you need to create a user and a role, you must create
+   the user first using one of the builtin :authrole:`userAdmin` or
+   :authrole:`userAdminAnyDatabase` roles. If you create a role first,
+   you won't be able to create a user.
+
+The ability to create a role first with the :method:`db.createRole()`
+method is specifically for users authorizing with LDAP. See :ref:`LDAP
+Authorization <security-ldap-external>` for more information.
+
+Localhost Exception for Sharded Clusters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+
+   - On a :binary:`~bin.mongos`, the localhost exception only applies
+     when there are no :ref:`sharded cluster users <sharding-localhost>`
+     or roles created.
+   - In a sharded cluster, the localhost exception applies to each shard
+     individually as well as to the cluster as a whole.
+
+Once you create a sharded cluster and add a :ref:`user administrator
+<create-user-admin>` through the :binary:`~bin.mongos` instance, you
+**must** still prevent unauthorized access to the individual shards. To
+prevent unauthorized access to individual shards, follow one of the
+following steps for each shard in your cluster:
+
+- :ref:`Create a user administrator <create-user-admin>` on the shard's
+  primary.
+- Disable the localhost exception at startup. To disable the localhost
+  exception, set the :parameter:`enableLocalhostAuthBypass` parameter to
+  ``0``.

source/core/security-users.txt

@@ -10,100 +10,100 @@ Users
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
-To authenticate a client in MongoDB, you must add a corresponding user to
-MongoDB.
+To authenticate a client in MongoDB, you must add a corresponding user
+to MongoDB.
 
+User Management
+---------------
 
-User Management Interface
--------------------------
+You can add a user with the :method:`db.createUser()` method using
+:binary:`~bin.mongosh`. The first user you create must have privileges
+to create other users. The :authrole:`userAdmin` or
+:authrole:`userAdminAnyDatabase` role both confer the privilege to
+create other users.
 
-To add a user, MongoDB provides the :method:`db.createUser()` method.
-When adding a user, you can assign :doc:`roles </core/authorization>` to
-the user in order to grant privileges.
-
-.. note::
+.. seealso::
 
-   The first user created in the database should be a user administrator
-   who has the privileges to manage other users. See
-   :doc:`/tutorial/enable-authentication`.
+   :doc:`/tutorial/create-users`
 
-You can also update existing users, such as to change password and grant
-or revoke roles. For a full list of user management methods, see
+You can grant a user privileges by assinging :doc:`roles
+</core/authorization>` to the user when you create the user. You can
+also grant or revoke roles, as well as update passwords, by updating
+existing users. For a full list of user management methods, see
 :ref:`user-management-methods`.
 
+.. seealso::
+
+   :doc:`/tutorial/manage-users-and-roles`
+
 A user is uniquely identified by the user's name and associated
-authentication database. Starting in MongoDB 4.0.9, a users managed by
-MongoDB are assigned a unique ``userId``. [#userid]_
+:ref:`authentication database <authentication-database>`. MongoDB
+associates a user with a unique ``userId`` upon creation in MongoDB.
+
+LDAP Managed Users
+~~~~~~~~~~~~~~~~~~
+
+:ref:`LDAP managed users <security-ldap>` created on an LDAP
+server do not have an associated document in the :doc:`system.users
+</reference/system-users-collection>` collection, and therefore don't
+have a :data:`~admin.system.users.userId` field associated with them.
 
-.. seealso::
 
-   :doc:`/tutorial/create-users`
-
 .. _authentication-database:
 .. _user-authentication-database:
 
 Authentication Database
 -----------------------
 
-When adding a user, you create the user in a specific database. This
-database is the authentication database for the user.
-
-A user can have privileges across different databases; that is, a user's
-privileges are not limited to their authentication database. By assigning
-to the user roles in other databases, a user created in one database can
-have permissions to act on other databases. For more information on
-roles, see :doc:`/core/authorization`.
-
-The user's name and authentication database serve as a unique identifier
-for that user. [#userid]_ That is, if two users have the same name but are created
-in different databases, they are two separate users. If you intend to
-have a single user with permissions on multiple databases, create a
-single user with roles in the applicable databases instead of creating
-the user multiple times in different databases.
+When you add a user, you create the user in a specific database. The
+database you create the user in is the authentication database for the
+user.
 
-.. [#userid]
+However, a user's privileges are not limited to their authentication
+database. Therefore, a user can have privileges across different
+databases. For more information on roles, see
+:doc:`/core/authorization`.
 
-   Starting in version 4.0.9, MongoDB associates a user with a unique
-   ``userId`` upon creation in MongoDB.
-   
-   :ref:`LDAP managed users <security-ldap>` created on the LDAP server
-   do not have an associated document in the :doc:`system.users
-   </reference/system-users-collection>` collection, and hence, do not
-   have a :data:`~admin.system.users.userId` field associated with them.
+A user's name and authentication database serve as a unique identifier
+for that user. MongoDB associates a user with a unique ``userId`` upon
+creation in MongoDB. However, :ref:`LDAP managed users <security-ldap>`
+created on an LDAP server do not have an associated document in the
+:doc:`system.users </reference/system-users-collection>` collection, and
+therefore don't have a :data:`~admin.system.users.userId` field
+associated with them.
 
-.. _authentication-auth-as-user:
-
-Authenticate a User
--------------------
-
-.. include:: /includes/fact-authenticate.rst
+If two users have the same name but are created in different databases,
+they are two separate users. If you want to have a single user with
+permissions on multiple databases, create a single user with a role for
+each applicable database.
 
 Centralized User Data
 ---------------------
 
 For users created in MongoDB, MongoDB stores all user information,
 including :data:`name <admin.system.users.user>`, :data:`password
-<admin.system.users.credentials>`, and the :data:`user's authentication
+<admin.system.users.credentials>`, and the user's :data:`authentication
 database <admin.system.users.db>`, in the :doc:`system.users
 </reference/system-users-collection>` collection in the ``admin``
 database.
 
-Do not access this collection directly but instead use the :ref:`user
-management commands <user-management-commands>`.
-
+Do not modify this collection directly. To manage users, use the
+designated :ref:`user management commands <user-management-commands>`.
 
 .. _sharding-localhost:
 .. _sharding-security:
 
 Sharded Cluster Users
 ---------------------
 
-To create users for a sharded cluster, connect to the
-:binary:`~bin.mongos` instance and add the users. Clients then
-authenticate these users through the :binary:`~bin.mongos` instances.
+To create users for a sharded cluster, connect to a
+:binary:`~bin.mongos` instance and add the users. To authenticate as a
+user created on a :binary:`~bin.mongos` instance, you must authenticate
+through a :binary:`~bin.mongos` instance.
+
 In sharded clusters, MongoDB stores user configuration data in the
 ``admin`` database of the :term:`config servers <config server>`.
 
@@ -112,62 +112,33 @@ In sharded clusters, MongoDB stores user configuration data in the
 Shard Local Users
 ~~~~~~~~~~~~~~~~~
 
-However, some maintenance operations, such as :dbcommand:`cleanupOrphaned`,
-:dbcommand:`compact`, :method:`rs.reconfig()`, require direct connections to
-specific shards in a sharded cluster. To perform these operations, you must
-connect directly to the shard and authenticate as a *shard local*
-administrative user.
-
-To create a *shard local* administrative user, connect directly to the shard
-and create the user. MongoDB stores *shard local* users in the ``admin``
-database of the shard itself.
-
-These *shard local* users are completely independent from the users added to
-the sharded cluster via :binary:`~bin.mongos`. *Shard local* users are local to the
-shard and are inaccessible by :binary:`~bin.mongos`.
-
-Direct connections to a shard should only be for shard-specific maintenance and
-configuration. In general, clients should connect to the sharded cluster
-through the :binary:`~bin.mongos`.
-
-.. _localhost-exception:
-
-Localhost Exception
--------------------
-
-The localhost exception allows you to enable access control and then
-create the first user in the system. With the localhost exception, after
-you enable access control, connect to the localhost interface and create
-the first user in the ``admin`` database. The first user must have
-privileges to create other users, such as a user with the
-:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role.
-Connections using the localhost exception *only* have access to create
-the first user on the ``admin`` database.
-
-.. versionchanged:: 3.4
-
-   MongoDB 3.4 extended the localhost exception to permit execution of the
-   :method:`db.createRole()` method. This method allows users authorizing via
-   LDAP to create a role inside of MongoDB that maps to a role defined
-   in LDAP. See :ref:`LDAP Authorization <security-ldap-external>` for more
-   information.
+Some maintenance operations, such as :dbcommand:`cleanupOrphaned`,
+:dbcommand:`compact`, or :method:`rs.reconfig()`, require direct
+connections to specific shards in a sharded cluster. To perform these
+operations, you must connect directly to the shard and authenticate as a
+*shard local* administrative user.
 
-The localhost exception applies only when there are no users created in the
-MongoDB instance.
+To create a *shard local* administrative user, connect directly to the
+primary of the shard and create the user. For instructions on how to
+create a shard local user administrator see the
+:doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control`
+tutorial.
 
-In the case of a sharded cluster, the localhost exception applies to each shard
-individually as well as to the cluster as a whole. Once you create a sharded
-cluster and add a user administrator through the :binary:`~bin.mongos` instance,
-you must still prevent unauthorized access to the individual shards. Follow one
-of the following steps for each shard in your cluster:
+MongoDB stores *shard local* users in the ``admin`` database of the
+shard itself. These *shard local* users are independent from
+the users added to the sharded cluster through a :binary:`~bin.mongos`.
+*Shard local* users are local to the shard and are inaccessible by
+:binary:`~bin.mongos`.
 
-- Create an administrative user, or
+Direct connections to a shard should only be used for shard-specific
+maintenance and configuration or for targeted analytics workloads. In
+general, clients should connect to the sharded cluster through the
+:binary:`~bin.mongos`.
 
-- Disable the localhost exception at startup. To disable the localhost
-  exception, set the :parameter:`enableLocalhostAuthBypass` parameter to ``0``.
 
 .. toctree::
    :titlesonly:
    :hidden:
 
    /tutorial/create-users
+   /tutorial/authenticate-a-user

source/includes/access-create-user.rst

@@ -6,7 +6,6 @@
   :ref:`action <security-user-actions>` on the role's database.
 
 The :authrole:`userAdmin` and
-:authrole:`userAdminAnyDatabase` built-in roles 
-provide :authaction:`createUser` and
-:authaction:`grantRole` actions on their respective :doc:`resources
-</reference/resource-document>`.
+:authrole:`userAdminAnyDatabase` built-in roles provide
+:authaction:`createUser` and :authaction:`grantRole` actions on their
+respective :doc:`resources </reference/resource-document>`.

source/includes/extracts-create-users-base.yaml

@@ -1,10 +1,10 @@
 ref: _create-user-intro
 content: |
-  Users that will authenticate to MongoDB using an external authentication
-  mechanism, such as {{mechanism}}, must be created in the ``$external`` database,
-  which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` to consult an
-  external source for authentication.
- 
+  Users that authenticate to MongoDB using an external authentication
+  mechanism, such as {{mechanism}}, must be created in the ``$external``
+  database, which allows :binary:`~bin.mongos` or :binary:`~bin.mongod`
+  to consult an external source for authentication.
+
   .. include:: /includes/extracts/sessions-external-username-limit.rst
 
 ...

source/includes/extracts-create-users.yaml

@@ -2,7 +2,7 @@ ref: create-user-intro-kerberos
 inherit:
   ref: _create-user-intro
   file: extracts-create-users-base.yaml
-replacement: 
+replacement:
   mechanism: "Kerberos"
 ---
 ref: create-user-intro-ldap
@@ -18,4 +18,4 @@ inherit:
   file: extracts-create-users-base.yaml
 replacement:
   mechanism: "x.509 Client Certificate Authentication"
-... 
+...

source/includes/extracts-sessions.yaml

@@ -101,11 +101,10 @@ content: |
 ref: sessions-external-username-limit
 content: |
 
-   .. versionchanged:: 3.6.3
+   To use :ref:`sessions` with ``$external`` authentication users
+   (Kerberos, LDAP, or x.509 users), the usernames cannot be greater
+   than 10k bytes.
 
-      To use sessions with ``$external`` authentication users (i.e.
-      Kerberos, LDAP, x.509 users), the usernames cannot be greater
-      than 10k bytes.
 ---
 ref: sessions-cursor-timeout
 content: |