Reorg access control 1320

bin/htaccess.yaml

@@ -1312,4 +1312,47 @@ code: 301
 outputs:
   - 'manual'
   - 'master'
+---
+redirect-path: '/tutorial/control-access-to-mongodb-with-authentication'
+url-base: '/tutorial/enable-authentication'
+type: 'redirect'
+code: 301
+outputs:
+  - 'manual'
+  - 'after-v2.2'
+---
+redirect-path: '/tutorial/enable-authentication'
+url-base: '/tutorial/control-access-to-mongodb-with-authentication'
+type: 'redirect'
+code: 301
+outputs:
+  - 'v2.2'
+---
+redirect-path: '/tutorial/add-user-administrator'
+url-base: '/tutorial/control-access-to-mongodb-with-authentication'
+type: 'redirect'
+code: 301
+outputs:
+  - 'v2.2'
+---
+redirect-path: '/tutorial/add-user-to-database'
+url-base: '/tutorial/control-access-to-mongodb-with-authentication'
+type: 'redirect'
+code: 301
+outputs:
+  - 'v2.2'
+---
+redirect-path: '/tutorial/generate-key-file'
+url-base: '/tutorial/control-access-to-mongodb-with-authentication'
+type: 'redirect'
+code: 301
+outputs:
+  - 'v2.2'
+---
+redirect-path: '/core/access-control'
+url-base: '/core/security'
+type: 'redirect'
+code: 301
+outputs:
+  - 'v2.2'
 ...

source/core/access-control.txt

@@ -0,0 +1,84 @@
+==============
+Access Control
+==============
+
+.. default-domain:: mongodb
+
+MongoDB provides support for authentication and authorization by storing
+a user's credentials and privileges in a database's :data:`system.users
+<<database>.system.users>` collection. MongoDB provisions authentication
+and access on a per-database level. Users exist in the context of a
+single logical database.
+
+For MongoDB Enterprise installations, MongoDB also provides support for
+authentication using a Kerberos service. See
+:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`.
+
+Authentication
+--------------
+
+MongoDB provides support for basic authentication by:
+
+- storing user credentials in a database's :data:`system.users
+  <<database>.system.users>` collection, and
+
+- providing the :setting:`auth` and :setting:`keyFile` configuration
+  settings to enable authentication for a given :program:`mongod` or
+  :program:`mongos` instance.
+
+Authentication is **disabled** by default.
+
+.. versionadded 2.0: Before 2.0 sharded clusters *had* to run with
+   trusted applications and a trusted networking configuration.
+
+To enable authentication, see the following:
+
+- :doc:`/tutorial/enable-authentication`
+
+- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
+
+Authorization
+-------------
+
+MongoDB supports role-based access to databases and database operations
+by storing each user's roles in a :doc:`privilege document
+</reference/user-privileges>` in the :data:`system.users
+<<database>.system.users>` collection. For a description of privilege
+documents and of available roles, see :doc:`/reference/user-privileges`.
+
+.. versionchanged:: 2.4 The schema of :data:`system.users
+   <<database>.system.users>` changed to accommodate a more
+   sophisticated user privilege model, as defined in :doc:`privilege
+   documents </reference/user-privileges>`.
+
+The :data:`system.users <<database>.system.users>` collection is
+protected to prevent privilege escalation attacks. To access the
+collection, you must have the :authrole:`userAdmin` or
+:authrole:`userAdminAnyDatabase` role.
+
+To assign user roles, you must first create an admin user in the
+database. Then you create additional users, assigning them appropriate
+user roles.
+
+To assign user roles, see the following:
+
+- :doc:`/tutorial/add-user-administrator`
+
+- :doc:`/tutorial/add-user-to-database`
+
+User Roles in the admin Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``admin`` database provides roles not available in other databases,
+including a role that effectively makes a user a MongoDB system
+superuser. See :ref:`database-admin-roles` and :ref:`admin-roles`.
+
+Authentication to One Database at a Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can log in as only one user for a given database, including
+the ``admin`` database. If you authenticate to a database as one user
+and later authenticate on the same database as a different user, the
+second authentication invalidates the first. Logging into a *different*
+database, however, does not invalidate authentication on other
+databases.

source/core/security.txt

@@ -4,31 +4,25 @@ Security Practices and Management
 
 .. default-domain:: mongodb
 
+This document describes risk mitigation in MongoDB deployments.
 As with all software running in a networked environment,
 administrators of MongoDB must consider security and risk
 exposures for a MongoDB deployment. There are no magic solutions for risk
 mitigation, and maintaining a secure MongoDB deployment is an ongoing
 process. This document takes a *Defense in Depth* approach to securing
-MongoDB deployments, and addresses a number of different methods for
-managing risk and reducing risk exposure
+MongoDB deployments and addresses a number of different methods for
+managing risk and reducing risk exposure.
 
-The intent of *Defense In Depth* approaches are to ensure there are no
+The intent of a *Defense In Depth* approach is to ensure there are no
 exploitable points of failure in your deployment that could allow an
 intruder or un-trusted party to access the data stored in the MongoDB
 database. The easiest and most effective way to reduce the risk of
 exploitation is to run MongoDB in a trusted environment, limit access,
 follow a system of least privilege, and follow best development and
-deployment practices. See the :ref:`security-reduce-risk` section for
-more information.
+deployment practices. See the :ref:`security-reduce-risk` section.
 
-For information on controlling user access through MongoDB user
-privileges, see the :ref:`security-authorization` section in this
-document. See :doc:`/reference/user-privileges` and
-:doc:`/reference/privilege-documents` for more information. 
-
-To use Kerberos authentication, which is available in `MongoDB
-Enterprise <http://www.10gen.com/products/mongodb-enterprise>`, see
-:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`.
+For an outline of all security, authentication, and authorization
+documentation, see :doc:`/security`.
 
 .. _security-reduce-risk:
 
@@ -52,11 +46,11 @@ strategies to control access:
 
 You may further reduce risk by:
 
-- requiring authentication for access to MongoDB instances.
+- requiring :doc:`authentication </core/access-control>` for
+  access to MongoDB instances.
 
 - requiring strong, complex, single purpose authentication credentials.
-  This should be part of your internal security policy but is not
-  currently configurable in MongoDB.
+  This should be part of your internal security policy.
 
 - deploying a model of least privilege, where all users have *only* the
   amount of access they need to accomplish required tasks, and no
@@ -79,6 +73,12 @@ seriously. If you discover a vulnerability in MongoDB or another
 reporting and response process, see the
 :doc:`/tutorial/create-a-vulnerability-report` document.
 
+Runtime Security Configuration
+------------------------------
+
+For configuration settings that affect security, see
+:ref:`configuration-security`.
+
 Networking Risk Exposure
 ------------------------
 
@@ -238,8 +238,7 @@ Always run the :program:`mongod` or :program:`mongos` process as a
 *unique* user with the minimum required permissions and access. Never
 run a MongoDB program as a ``root`` or administrative users. The
 system users that run the MongoDB processes should have robust
-authentication credentials that prevent unauthorized or casual
-access.
+authentication credentials that prevent unauthorized or casual access.
 
 To further limit the environment, you can run the :program:`mongod` or
 :program:`mongos` process in a ``chroot`` environment. Both user-based
@@ -248,120 +247,7 @@ conventions for administering all daemon processes on Unix-like
 systems.
 
 You can disable anonymous access to the database by enabling
-authentication using the :setting:`auth` as detailed in the
-:ref:`security-authentication` section.
-
-.. _security-authentication:
-
-Authentication
---------------
-
-MongoDB provides basic support for authentication with the
-:setting:`auth` and :setting:`keyFile` configuration settings.
-To require authentication on a single-instance deployment, start the
-:program:`mongod` instance with the :setting:`auth` setting.
-For multi-instance deployments
-(i.e. :term:`replica sets <replica set>` and :term:`sharded clusters
-<sharded cluster>`) use the :setting:`keyFile` setting, which implies
-:setting:`auth` and allows intra-deployment authentication and
-operation.
-
-For MongoDB Enterprise installations, MongoDB also supports
-authentication using a Kerberos service. See
-:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`.
-
-For basic authentication, be aware of the following behaviors:
-
-- Authentication is **disabled** by default.
-
-- The ``system.users`` collection in each database stores all
-  credentials. If you have the ``userAdmin`` role on a database, you can
-  query authenticated users in that database with the following
-  operation:
-
-  .. code-block:: javascript
-
-     db.system.users.find()
-
-- When setting up authentication for the first time you must either:
-
-  - add at least one user to the ``admin`` database before starting
-    the :program:`mongod` instance with :setting:`auth`.
-
-  - add the first user to the ``admin`` database when connected to the
-    :program:`mongod` instance from a ``localhost``
-    connection. [#sharded-localhost]_
-
-  To add and maintain users, see
-  :doc:`/tutorial/control-access-to-mongodb-with-authentication`.
-
-- Support for authentication with sharded clusters.
-
-  .. versionadded:: 2.0
-
-  Before 2.0 sharded clusters *had* to run with trusted applications and
-  a trusted networking configuration.
-
-.. [#sharded-localhost] Because of :issue:`SERVER-6591`, you cannot
-   add the first user to a sharded cluster using the ``localhost``
-   connection in 2.2. If you are running a 2.2 sharded cluster, and
-   want to enable authentication, you must deploy the cluster and add
-   the first user to the ``admin`` database before restarting the
-   cluster to run with :setting:`keyFile`.
-
-.. _security-authorization:
-
-Authorization
--------------
-
-.. versionchanged:: 2.4
-
-MongoDB provides role-based access to databases and database operations
-through each database's :data:`system.users <<database>.system.users>`
-collection.
-
-Be aware of the following behaviors:
-
-- MongoDB provisions access on a per-database level. Users exist in the
-  context of a single logical database.
-
-- Roles determine the user's access to the database. For a list of
-  available roles, see :ref:`user-roles`.
-
-- User documents in the :data:`system.users <<database>.system.users>`
-  collection in one database can grant access to users defined in
-  another database. See :doc:`/reference/privilege-documents` for more
-  information on delegated credentials and :data:`system.users
-  <<database>.system.users>` documents.
-
-- The ``admin`` database provides roles not available in other
-  databases. You can assign ``admin`` users roles that effectively make
-  them MongoDB system superusers. See :ref:`database-admin-roles` and
-  :ref:`admin-roles`.
-
-- The ``system.users`` collection in each database stores all users and
-  their roles. If you have the ``userAdmin`` role on a database, you can
-  query authorized users in that database with the following operation:
-
-  .. code-block:: javascript
-
-     db.system.users.find()
-
-- The ``system.users`` collection is protected to prevent privilege
-  escalation attacks by requiring you to have the ``userAdmin`` role.
-
-- You can be logged in as only one user for a given database, including
-  the ``admin`` database. If you authenticate to a database as one user
-  and later authenticate on the same database as a different user, the
-  second authentication invalidates the first. Logging into a
-  *different* database, however, does not invalidate authentication on
-  other databases.
-
-For more information on controlling user access, see the following:
-
-- :doc:`/reference/user-privileges`
-
-- :doc:`/reference/privilege-documents`
+MongoDB authentication. See :doc:`/core/access-control`.
 
 Interfaces
 ----------
@@ -423,7 +309,7 @@ accessibility represents a vulnerability in a secure environment.
 
 If you must use the REST API, please control and limit access to the
 REST API. The REST API does not include any support for
-authentication, even when running with :setting:`auth` (authorization)
+authentication, even when running with :setting:`auth`
 enabled.
 
 See the following documents for instructions on restricting access to

source/core/sharded-cluster-security.txt

@@ -22,7 +22,7 @@ instances.
 
 This section describes authentication specific to sharded
 clusters. For information on authentication across MongoDB, see
-:ref:`security-authentication`.
+:doc:`/core/access-control`.
 
 Access Control Privileges in Sharded Clusters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -31,7 +31,7 @@ In sharded clusters, MongoDB provides separate administrative
 privileges for the sharded cluster and for each shard. Beyond these
 administration privileges, privileges for sharded cluster deployments
 are functionally the same as any other MongoDB deployment. See,
-:ref:`security-authentication` for more information.
+:doc:`/core/access-control` for more information.
 
 For sharded clusters, MongoDB provides these separate administrative
 privileges:
@@ -53,7 +53,7 @@ privileges:
   and access for that shard only. These credentials are *completely*
   distinct from the cluster-wide administrative credentials.
 
-For more information on privileges, see :ref:`security-authentication`.
+For more information on privileges, see :doc:`/core/access-control`.
 
 Access a Sharded Cluster with Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/faq/concurrency.txt

@@ -169,7 +169,7 @@ The following MongoDB operations lock multiple databases:
   all databases for short intervals. All databases share a single
   journal.
 
-- :ref:`User authentication <security-authentication>` locks the
+- :doc:`User authentication </core/access-control>` locks the
   ``admin`` database as well as the database the user is accessing.
 
 - All writes to a replica set's :term:`primary` lock both the database

source/reference/method/db.addUser.txt

@@ -64,8 +64,13 @@ db.addUser()
 
          db.addUser( { user: "author", userSource: "users", roles: [ "readWrite" ] } )
 
-   .. seealso:: :doc:`/reference/user-privileges`, and
-     :doc:`/reference/privilege-documents`.
+   .. seealso::
+
+      - :doc:`/tutorial/add-user-to-database`
+
+      - :doc:`/reference/user-privileges`
+
+      - :doc:`/reference/privilege-documents`
 
    .. _v2.2-style-addUser: