DOCS-2306 create a root user

source/includes/steps-add-admin-user.yaml

@@ -0,0 +1,68 @@
+title: Connect with the Privileges to Create Users and Grant Roles
+stepnum: 1
+ref: connect-as-admin
+pre: |
+  Connect to the :program:`mongod` or :program:`mongos` as a user with the
+  :authaction:`createUser` *and* :authaction:`grantRole` actions on the
+  ``admin`` database.
+action:
+  pre: |
+    The following example operation connects to the MongoDB instance as a user
+    name ``accountManager``:
+  language: javascript
+  code: |
+    mongo --port 27017 -u accountManager -p 12345678 --authenticationDatabase admin
+post: |
+  As an alternative, if your MongoDB system does not have any
+  users in the ``admin`` database you can connect a client over the
+  localhost interface without authenticating using the :ref:`localhost
+  bypass <localhost-exception>`.
+---
+title: Verify Privileges
+stepnum: 2
+ref: check-privileges
+pre: |
+  Verify that the user you are connected as has the :authaction:`createUser`
+  and :authaction:`grantRole` actions on the ``admin`` database.
+action:
+  pre: |
+    The following example operation checks privileges for the user connected
+    as ``accountManager``:
+  language: javascript
+  code: |
+    db.runCommand(
+       {
+         usersInfo: "accountManager",
+         showPrivileges: true
+       }
+    )
+  post: |
+    :dbcommand:`usersInfo` returns a document that displays the
+    privileges granted to the user.
+---
+title: Create the Administrative User
+stepnum: 3
+ref: create-admin-user
+pre: |
+  In the ``admin`` database, create a new user using the
+  :method:`db.createUser()` method. Give the user the system-defined
+  :authrole:`root` role.
+action:
+  pre: |
+    For example:
+  language: javascript
+  code: |
+    use admin
+    db.createUser(
+        {
+          user: "superuser",
+          pwd: "12345678",
+          roles: [ "root" ]
+        }
+    )
+post: |
+  Authenticate against the ``admin`` database to test the new user
+  account. Use :method:`db.auth()` while using the ``admin`` database
+  or use the :program:`mongo` shell with the :option:`--authenticationDatabase
+  <mongo --authenticateDatabase>` option.
+...

source/includes/toc-security-tutorials-access-control.yaml

@@ -14,6 +14,12 @@ description: |
   Create non-administrator users using MongoDB's role-based
   authentication system.
 ---
+file: /tutorial/add-admin-user
+description: |
+  Create a user with unrestricted access. Create such a user only in unique
+  situations. In general, all users in the system should have no more access
+  than needed to perform their required operations.
+---
 file: /tutorial/define-roles
 description: |
   Create custom role.

source/reference/glossary.txt

@@ -368,6 +368,10 @@ Glossary
       :term:`JSON` with Padding. Refers to a method of injecting JSON
       into applications. **Presents potential security concerns**.
 
+   least privilege
+      An authorization policy that gives a user only the amount of access
+      that is essential to that user's work and no more.
+
    legacy coordinate pairs
       The format used for :term:`geospatial` data prior to MongoDB
       version 2.4. This format stores geospatial data as points on a

source/reference/system-defined-roles.txt

@@ -113,7 +113,7 @@ Database Administration Roles
 
 .. authrole:: userAdmin
 
-   Users with this role can modify permissions for existing users
+   Provides the ability to modify permissions for existing users
    and create new users on the current database. :authrole:`userAdmin`
    does not restrict the permissions that a user can grant, and a
    :authrole:`userAdmin` user can grant privileges to themselves or
@@ -134,7 +134,7 @@ Administrative Roles
 
 .. authrole:: clusterAdmin
 
-   :authrole:`clusterAdmin` grants access to several administration
+   Grants access to several administration
    operations that affect or present information about the whole system,
    rather than just a single database. These privileges include but
    are not limited to :term:`replica set` and :term:`sharded cluster`
@@ -223,19 +223,19 @@ equivalents. You must specify the following "any" database roles on the
 
 .. authrole:: readAnyDatabase
 
-   :authrole:`readAnyDatabase` provides users with the same read-only
+   Provides users with the same read-only
    permissions as :authrole:`read`, except it applies to *all* logical
    databases in the MongoDB environment.
 
 .. authrole:: readWriteAnyDatabase
 
-   :authrole:`readWriteAnyDatabase` provides users with the same read and
+   Provides users with the same read and
    write permissions as :authrole:`readWrite`, except it applies to *all*
    logical databases in the MongoDB environment.
 
 .. authrole:: userAdminAnyDatabase
 
-   :authrole:`userAdminAnyDatabase` provides users with the same
+   Provides users with the same
    access to user administration operations as :authrole:`userAdmin`,
    except it applies to *all* logical databases in the MongoDB
    environment.
@@ -250,11 +250,16 @@ equivalents. You must specify the following "any" database roles on the
 
 .. authrole:: dbAdminAnyDatabase
 
-   :authrole:`dbAdminAnyDatabase` provides users with the same access
+   Provides users with the same access
    to database administration operations as :authrole:`dbAdmin`,
    except it applies to *all* logical databases in the MongoDB
    environment.
 
+.. authrole:: root
+
+   Gives a user access to all the operations and all the resources of *of
+   all other roles combined*. A user with this role is a superuser.
+
 .. Does this need to change with the new user-defined roles?
 
 .. _auth-role-combined:

source/tutorial/add-admin-user.txt

@@ -0,0 +1,52 @@
+======================================================
+Create an Administrative User with Unrestricted Access
+======================================================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+Most users should have only the minimal set of privileges required for
+their operations, in keeping with the policy of :term:`least privilege`.
+However, some authorization architectures may
+require a user with unrestricted access. To support these *super
+users*, you can create users with access to all database :ref:`resources
+<resource-document>` and :ref:`actions <security-user-actions>`.
+
+.. link "creating a user" in the next sentence to the tutorial when
+   it's published.
+
+For many deployments, you may be able to avoid having *any* users with
+unrestricted access by having an administrative user that with the
+:authaction:`createUser` and :authaction:`grantRole` actions as needed
+to support operations.
+
+If users truly need unrestricted access to a MongoDB deployment,
+MongoDB provides a :doc:`system role </reference/system-defined-roles>`
+named :authrole:`root` that grants the combined privileges of all
+system roles. This document describes how to create an administrative
+user with the :authrole:`root` role.
+
+For descriptions of the access each system role provides, see
+:ref:`system-defined roles <system-user-roles>.
+
+Prerequisites
+-------------
+
+.. include:: /includes/access-create-user.rst
+
+The :authrole:`userAdmin` and :authrole:`userAdminAnyDatabase` system roles
+both grant the actions.
+
+A user authenticated using the :ref:`localhost exception
+<localhost-exception>` also has those actions on the ``admin`` database. The
+localhost exception applies if no users yet exist on the ``admin`` database
+and if a user connects to the :program:`mongod` or :program:`mongos` from a
+client running on the same system. For more information, see
+:ref:`localhost-exception`.
+
+Procedure
+---------
+
+.. include:: /includes/steps/add-root-user.rst