DOCS-699 authentication on sharded clusters

source/administration/sharded-clusters.txt

@@ -286,59 +286,125 @@ To route a query to a :term:`cluster <sharded cluster>`,
 Sharded Cluster Security Considerations
 ---------------------------------------
 
-.. note::
+MongoDB controls access to :term:`sharded clusters <sharded cluster>`
+through key files that store authentication information. The components
+of sharded clusters use key files when authenticating to each other. You
+create key files and then point your :program:`mongos` and
+:program:`mongod` instances to the files, as described later in this
+section.
+
+In addition to the MongoDB security described in this section, you
+should run your sharded clusters only in trusted networking environments
+that control access to the cluster using network rules. Your networking
+environments should use restrictions that ensure only known traffic
+reaches your :program:`mongos` and :program:`mongod` instances.
+
+This section describes authentication specific to sharded clusters. For
+information on authentication across MongoDB, see
+:ref:`security-authentication`.
+
+Access Control Privileges in Sharded Clusters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In sharded clusters, MongoDB provides separate administrative privileges
+for the sharded cluster and for each shard. Aside from that, the
+available privileges are the same as for any MongoDB instance, as
+described in :ref:`security-authentication`.
+
+For sharded clusters, MongoDB provides these separate administrative privileges:
+
+- Administrative privileges for the sharded cluster. These privileges
+  provide read-and-write access to the clusters's :term:`admin <admin
+  database>`, which lets the user run all administrative commands.
+  Administrative privileges also give the user read-and-write access to
+  all the cluster's databases.
+
+  The credentials for administrative privileges on the cluster reside on
+  the config servers. To receive admin access to the cluster, you must
+  authenticate a session while connected to a :program:`mongos` instance
+  using the admin database.
+
+- Administrative privileges for an individual shard. A shard is a
+  :program:`mongod` instance for which sharding has been enabled. Each
+  shard has its own admin database that stores administrative
+  credentials and access for that shard only. These credentials are
+  *completely* distinct from the cluster-wide administrative
+  credentials.
+
+  As with all :program:`mongod` instances, MongoDB provides two types of
+  administrative privileges for a shard:
+
+  - Normal administrative privileges, which provide read-and-write
+    access to the admin database and access to all administrative
+    commands, and which provide read-and-write accees to all other
+    databases on that shard.
+
+  - Read-only administrative privileges, which provide read-only access
+    to the admin database and to all other databases on that shard.
+
+Also, as with all :program:`mongod` instances, a MongoDB sharded cluster
+provides the following non-administrative user privileges:
+
+- Normal privileges, which provide read-and-write access to a specific
+  database. Users with normal privilege can add users to the database.
+
+- Read-only privileges, which provide read-only access to a specific
+  database.
 
-   You should always run all :program:`mongod` components in trusted
-   networking environments that control access to the cluster using
-   network rules and restrictions to ensure that only known traffic
-   reaches your :program:`mongod` and :program:`mongos` instances.
+For more information on privileges, see :ref:`security-authentication`.
 
-.. warning::  Limitations
+Enable Authentication in a Sharded Cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. versionchanged:: 2.2
-      Read only authentication is fully supported in shard
-      clusters. Previously, in version 2.0, sharded clusters would not
-      enforce read-only limitations.
+.. versionadded:: 2.0
+   Support for authentication with sharded clusters.
 
-   .. versionchanged:: 2.0
-      Sharded clusters support authentication. Previously, in version
-      1.8, sharded clusters will not support authentication and access
-      control. You must run your sharded systems in trusted
-      environments.
+To control access to a sharded cluster, you create key files and then
+set the :setting:`keyFile` option on *all* components of the sharded
+cluster (all :program:`mongos` instances, all config server
+:program:`mongod` instances, and all shard :program:`mongod` instances). The content of
+the key file is arbitrary but must be the same on all cluster members.
 
-To control access to a sharded cluster, you must set the
-:setting:`keyFile` option on all components of the sharded cluster. Use
-the :option:`--keyFile <mongos --keyFile>` run-time option or the
-:setting:`keyFile` configuration option for all :program:`mongos`,
-configuration instances, and shard :program:`mongod` instances.
+To enable authentication, do the following:
 
-There are two classes of security credentials in a sharded cluster:
-credentials for "admin" users (i.e. for the :term:`admin database`) and
-credentials for all other databases. These credentials reside in
-different locations within the cluster and have different roles:
+1. Generate a key file to store authentication information, as described
+   in :ref:`generate-key-file`.
 
-- Admin database credentials reside on the config servers, to receive
-  admin access to the cluster you *must* authenticate a session while
-  connected to a :program:`mongos` instance using the :term:`admin
-  database`.
+#. On each component in the sharded cluster, enable authentication by
+   doing one of the following:
 
-- Each shard has its own :term:`admin database`, which stores
-  administrative credentials and access for that shard only.
+   - In the configuration file, set the :setting:`keyFile` option to the
+     key file's path and then start the component.
 
-- Other database credentials reside on the *primary* shard for the
-  database.
+     The following is an example :setting:`keyFile` option and path:
 
-This means that you *can* authenticate to these users and databases
-while connected directly to the *primary* shard for a database. You
-**cannot** authenticate to a database in a sharded cluster that is not
-the primary for that database. However, for clarity and consistency
-all interactions between the client and the database should use a
-:program:`mongos` instance.
+     .. code-block:: cfg
 
-.. note::
+        keyFile = /srv/mongodb/keyfile
+
+   - When starting the component, set :option:`--keyFile <mongos --keyFile>` option,
+     which is an option for both :program:`mongos` instances and
+     :program:`mongod` instances. Set the :option:`--keyFile <mongos --keyFile>`
+     to the key file's path.
+
+   .. note:: The :setting:`keyFile` setting implies :setting:`auth`, which
+      means in most cases you do not need to set :setting:`auth`.
+
+#. Add the first administrative user and then add subsequent users. See
+   :ref:`control-access-add-users`.
+
+Access a Sharded Cluster for which Authentication is Enabled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To access a sharded cluster as an authenticated admin user, see
+:ref:`control-access-admin-access`.
+
+To access a sharded cluster as an authenticated, non-admin user, see
+either of the following:
+
+- :dbcommand:`authenticate`
+
+- :method:`db.auth()`
 
-   Individual shards can store administrative credentials to their
-   instance, which only permit access to a single shard. MongoDB
-   stores these credentials in the shards' :term:`admin databases
-   <admin database>` and these credentials are *completely* distinct
-   from the cluster-wide administrative credentials.
+To terminate an authenticated session, see the :dbcommand:`logout`
+command.

source/tutorial/control-access-to-mongodb-with-authentication.txt

@@ -20,8 +20,10 @@ authentication and managing a MongoDB deployment with authentication.
    :option:`--keyFile <mongod --keyFile>` options on the command
    line.
 
-Adding Users
-------------
+.. _control-access-add-users:
+
+Add Users
+---------
 
 When setting up authentication for the first time you must either: 
 
@@ -100,6 +102,8 @@ the following sequence of operations:
 Replace ``<username>`` and ``<password>`` with the credentials for
 this user.
 
+.. _control-access-admin-access:
+
 Administrative Access in MongoDB
 --------------------------------
 
@@ -223,9 +227,16 @@ authentication with specific MongoDB deployments:
 - :ref:`replica-set-security`
 - :ref:`sharding-security` 
 
+.. _generate-key-file:
+
 Generate a Key File
 -------------------
 
+The key file must be less one kilobyte in size and may only contain
+characters in the base64 set. The key file must not have group or "world"
+permissions on UNIX systems. Key file permissions are not checked on
+Windows systems.
+
 Use the following command at the system shell to generate pseudo-random
 content for a key file: