DOCS-1262 DOCS-1263 DOCS-1264 new access control

source/administration/security.txt

@@ -18,9 +18,21 @@ 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
+deployment practices. See the :ref:`security-reduce-risk` section in this document for
 more information.
 
+For information on controlling user access through MongoDB user
+privileges, see the :ref:`security-authorization` section in this
+document. See also the following documents:
+
+- :doc:`/reference/user-privileges`
+
+- :doc:`/reference/privilege-documents`
+
+For information on Kerberos authentication, which is available in
+MongoDB Enterprise, see
+:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`.
+
 .. _security-reduce-risk:
 
 Strategies for Reducing Risk
@@ -80,10 +92,8 @@ Interfaces and Port Numbers
 
 The following list includes all default ports used by MongoDB:
 
-By default, listens for connections on the following ports:
-
 ``27017``
-   This is the default port :program:`mongod` and :program:`mongos`
+   This is the default port for :program:`mongod` and :program:`mongos`
    instances. You can change this port with :setting:`port` or
    :option:`--port <mongod --port>`.
 
@@ -122,10 +132,8 @@ You can limit the network exposure with the following configuration options:
   Authentication does not control or affect access to this interface.
 
   .. important:: Disable this option for production deployments. If
-     *do* you leave this interface enabled, you should only allow trusted
-     clients to access this port.
-
-  .. todo:: cross reference the above with the firewall rules below.
+     you *do* leave this interface enabled, you should only allow trusted
+     clients to access this port. See :ref:`security-firewalls`.
 
 - the :setting:`port` setting for :program:`mongod` and
   :program:`mongos` instances.
@@ -139,9 +147,7 @@ You can limit the network exposure with the following configuration options:
 
   Whatever port you attach :program:`mongod` and :program:`mongos`
   instances to, you should only allow trusted clients to connect to
-  this port.
-
-  .. todo:: cross reference the above with the firewall rules below.
+  this port. See :ref:`security-firewalls`.
 
 - the :setting:`rest` setting for :program:`mongod`
   and :program:`mongos` instances.
@@ -254,69 +260,49 @@ Authentication
 --------------
 
 MongoDB provides basic support for authentication with the
-:setting:`auth` setting. For multi-instance deployments
-(i.e. :term:`replica sets <replica set>`, and :term:`sharded clusters
+: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. Be aware of the following behaviors of MongoDB's
-authentication system:
+:setting:`auth` and allows intra-deployment authentication and
+operation.
 
-- Authentication is **disabled** by default.
+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:
 
-- MongoDB provisions access on a per-database level. Users either have
-  *read only* access to a database or *normal* access to a database that
-  permits full read and write access to the database. *Normal* access
-  conveys the ability to add additional users to the database.
+- Authentication is **disabled** by default.
 
 - The ``system.users`` collection in each database stores all
-  credentials. You can query the authorized users with the following
+  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()
 
-- The ``admin`` database is unique. Users with *normal* access to the
-  ``admin`` database have read and write access to all databases. Users
-  with *read only* access to the ``admin`` database have read only
-  access to all databases, with the exception of the ``system.users``
-  collection, which is protected to prevent privilege escalation
-  attacks.
-
-  Additionally the ``admin`` database exposes several commands and
-  functionality, such as :dbcommand:`listDatabases`.
-
-- Once authenticated a *normal* user has full read and write access to
-  a database.
-
-- If you have authenticated to a database as a normal, read and write,
-  user; authenticating as a read-only user on the same database will
-  invalidate the earlier authentication, leaving the current
-  connection with read only access.
+- When setting up authentication for the first time you must either:
 
-- If you have authenticated to the ``admin`` database as normal, read
-  and write, user; logging into a *different* database as a read only
-  user will *not* invalidate the authentication to the ``admin``
-  database. In this situation, this client will be able to read and
-  write data to this second database.
+  - add at least one user to the ``admin`` database before starting
+    the :program:`mongod` instance with :setting:`auth`.
 
-- When setting up authentication for the first time you must either:
+  - add the first user to the ``admin`` database when connected to
+    the :program:`mongod` instance from a ``localhost`` connection. [#sharded-localhost]_
 
-  #. add at least one user to the ``admin`` database before starting
-     the :program:`mongod` instance with :setting:`auth`.
+  To add and maintain users, see
+  :doc:`/tutorial/control-access-to-mongodb-with-authentication`.
 
-  #. add the first user to the ``admin`` database when connected to
-     the :program:`mongod` instance from a ``localhost`` connection. [#sharded-localhost]_
+- Support for authentication with sharded clusters.
 
-.. versionadded:: 2.0
-   Support for authentication with sharded clusters. Before 2.0
-   sharded clusters *had* to run with trusted applications and a
-   trusted networking configuration.
+  .. versionadded:: 2.0
 
-Consider the
-:doc:`/tutorial/control-access-to-mongodb-with-authentication`
-document which outlines procedures for configuring and maintaining
-users and access with MongoDB's authentication system.
+  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``
@@ -325,6 +311,58 @@ users and access with MongoDB's authentication system.
    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 :ref:`user-roles`.
+
+- 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`
+
 Interfaces
 ----------
 
@@ -385,7 +423,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 if when running with :setting:`auth` enabled.
+authentication, even when running with :setting:`auth` (authorization) enabled.
 
 See the following documents for instructions on restricting access to
 the REST API interface:

source/administration/sharded-clusters.txt

@@ -401,8 +401,8 @@ To enable authentication, do the following:
 Access a Sharded Cluster with Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To access a sharded cluster as an authenticated admin user, see
-:ref:`control-access-admin-access`.
+To access a sharded cluster as an authenticated user, use the
+appropriate authentication options in :program:`mongo`.
 
 To access a sharded cluster as an authenticated, non-admin user, see
 either of the following:

source/administration/vulnerability-notification.txt

@@ -60,9 +60,8 @@ You may encrypt email using our `public key
 of a any sensitive information in your vulnerability report.
 
 10gen will respond to any vulnerability notification received via
-email with email which will contain a reference number (i.e. a ticket
-from the :issue:`SECURITY` project,) Jira case posted to the :issue:`SECURITY`
-project.
+email with a response email that contains a reference number for a Jira ticket
+posted to the :issue:`SECURITY` project.
 
 Evaluation
 ~~~~~~~~~~

source/reference/user-privileges.txt

@@ -95,6 +95,8 @@ Database User Roles
    - :dbcommand:`mapReduce` (output to a collection.)
    - :dbcommand:`renameCollection` (within the same database.)
 
+.. _database-admin-roles:
+
 Database Administration Roles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -148,6 +150,8 @@ Database Administration Roles
    a specific database. Users with :authrole:`userAdmin` can grant
    themselves all privileges.
 
+.. _admin-roles:
+
 Administrative Roles
 --------------------
 

source/security.txt

@@ -7,6 +7,11 @@ strategies. Additionally, this section includes :ref:`tutorials` that
 outline basic network filter and firewall rules to configure trusted
 environments for MongoDB.
 
+This section also describes the MongoDB role-based access-control
+model. MongoDB provides user roles that authorize users for different
+levels of access to databases and database operations. For more
+information, see the reference pages listed at the bottom of this page.
+
 Strategies and Practices
 ------------------------