diff --git a/source/administration/security.txt b/source/administration/security.txt index 6a41af648d0..833245a93ea 100644 --- a/source/administration/security.txt +++ b/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 `. @@ -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 `, 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 ` and :term:`sharded clusters `) 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 <.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 <.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: diff --git a/source/administration/sharded-clusters.txt b/source/administration/sharded-clusters.txt index 9dc9764219c..d6b31f087ae 100644 --- a/source/administration/sharded-clusters.txt +++ b/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: diff --git a/source/administration/vulnerability-notification.txt b/source/administration/vulnerability-notification.txt index ab21d703da6..840291872e2 100644 --- a/source/administration/vulnerability-notification.txt +++ b/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 ~~~~~~~~~~ diff --git a/source/reference/user-privileges.txt b/source/reference/user-privileges.txt index 593537389eb..9e57db46d85 100644 --- a/source/reference/user-privileges.txt +++ b/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 -------------------- diff --git a/source/security.txt b/source/security.txt index d7405a08e2d..400075e826c 100644 --- a/source/security.txt +++ b/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 ------------------------ diff --git a/source/tutorial/control-access-to-mongodb-with-authentication.txt b/source/tutorial/control-access-to-mongodb-with-authentication.txt index b95a4f91008..2396d9625c7 100644 --- a/source/tutorial/control-access-to-mongodb-with-authentication.txt +++ b/source/tutorial/control-access-to-mongodb-with-authentication.txt @@ -1,22 +1,29 @@ -======================================================= -Control Access to MongoDB Instances with Authentication -======================================================= +========================= +Access Control in MongoDB +========================= .. default-domain:: mongodb -MongoDB provides a basic authentication system, that you can enable -with the :setting:`auth` and :setting:`keyFile` configuration -settings. [#cli-options]_ See the :ref:`authentication -` section of the :doc:`/administration/security` document. - -This document contains an overview of all operations related to -authentication and managing a MongoDB deployment with authentication. - -.. see:: The :ref:`configuration-security` section of the - :doc:`/administration/configuration` document for more information - on configuring authentication. +This document describes how to set up and manage basic authentication +and authorization. For information on Kerberos authentication, which is +available in MongoDB Enterprise, see +:doc:`Kerberos Authentication +`. -.. [#cli-options] Use the :option:`--auth ` +MongoDB provides a basic access control system that you can enable +with the :setting:`auth` and :setting:`keyFile` configuration +settings [#cli-options]_. For an overview, +see the :ref:`security-authentication` section of the +:doc:`/administration/security` document. For additional configuration +settings that affect security, see the :ref:`configuration-security` +section of the :doc:`/administration/configuration` document. + +MongoDB also provides role-based privileges through each database's +:data:`system.users <.system.users>` collection. For an +overview, see the :ref:`security-authorization` section of the +:doc:`/administration/security` document. + +.. [#cli-options] Use the :option:`--auth ` or :option:`--keyFile ` options on the command line. @@ -25,143 +32,158 @@ authentication and managing a MongoDB deployment with authentication. Add Users --------- +.. versionchanged:: 2.4 + The schema of :data:`system.users <.system.users>` + changed in 2.4 to accommodate a more sophisticated :doc:`user + privilege model `. + 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 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]_ +- add the first user to the ``admin`` database when connected to the + :program:`mongod` instance from a ``localhost`` connection. + [#sharded-localhost]_ -Begin by setting up the first administrative user for the -:program:`mongod` instance. +The first user to a MongoDB deployment should be a user with the +``userAdminAnyDatabase`` role in the ``admin`` database. -.. [#sharded-localhost] Because of :issue:`SERVER-6591`, you cannot +.. [#sharded-localhost] Because of :issue:`SERVER-6591`, in version 2.2 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 + connection. 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`. -Add an Administrative User -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. admonition:: About administrative users +Add a User with the ``userAdminAnyDatabase`` Role +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Administrative users are those users that have "normal" or read and - write access to the ``admin`` database. +The first user created for a MongoDB deployment should have the +``userAdminAnyDatabase`` role, which allows the user to create other +users with any roles. Use this user to create all other users in the +system. -If this is the first administrative user, -[#auth-disabled-maintenance]_ connect to the :program:`mongod` on the -``localhost`` interface using the :program:`mongo` shell. Then, issue -the following command sequence to switch to the ``admin`` database -context and add the administrative user: +The user with the ``userAdminAnyDatabase`` role is effectively a +super-user, as the user can grant itself any role. But as a best practice, +this user should have *no other roles* and should be used only for user +administration. -.. code-block:: javascript +As this user can grant itself and any other user full access to +anything, the credentials to log in as this user should be carefully +controlled. - use admin - db.addUser("", "") +1. Connect to the :program:`mongod` or :program:`mongos` on the ``localhost`` interface using + the :program:`mongo` shell. -Replace ```` and ```` with the credentials for -this administrative user. +#. Switch to the ``admin`` database: -.. [#auth-disabled-maintenance] You can also use this procedure if - authentication is *not* enabled so that your databases has an - administrative user when you enable :setting:`auth`. - -Add a Normal User to a Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: javascript -To add a user with read and write access to a specific database, in -this example the ``records`` database, connect to the -:program:`mongod` instance using the :program:`mongo` shell, and issue -the following sequence of operations: + use admin -.. code-block:: javascript +#. Add the user with the ``userAdminAnyDatabase`` role, and only that + role, by issuing a command similar to the following, where + ```` is the username and ```` is the password: - use records - db.addUser("", "") + .. code-block:: javascript -Replace ```` and ```` with the credentials for -this user. + db.addUser( { user: "", pwd: "", roles: [ "userAdminAnyDatabase" ] } ) -Add a Read Only User to a Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + For more information on creating a user, see + :ref:`control-access-add-user-to-database`. -To add a user with read only access to a specific database, in -this example the ``records`` database, connect to the -:program:`mongod` instance using the :program:`mongo` shell, and issue -the following sequence of operations: +.. [#auth-disabled-maintenance] You can also use this procedure if + authentication is *not* enabled so that your databases has an + administrative user when you enable :setting:`auth`. -.. code-block:: javascript +.. _control-access-add-user-to-database: - use records - db.addUser("", "", true) +Add a User to a Database +~~~~~~~~~~~~~~~~~~~~~~~~ -Replace ```` and ```` with the credentials for -this user. +To add a user to a database you must be logged into that database as a +user with the ``userAdmin`` role. -.. _control-access-admin-access: +To add a user, pass the :method:`db.addUser()` method a +well-formed :data:`system.users <.system.users>` document that +contains the user's credentials and privileges. The +:method:`db.addUser()` method adds the document to the database's +:data:`system.users <.system.users>` collection. -Administrative Access in MongoDB --------------------------------- +For the structure of user privilege documents, see :data:`system.users +<.system.users>`. The following are example documents. -Although administrative accounts have access to all databases, these -users must authenticate against the ``admin`` database before changing -contexts to a second database, as in the following example: +.. example:: The following creates a user named ``Alice`` in the + ``products`` database and gives her ``readWrite`` and + ``dbAdmin`` privileges. -.. example:: + .. code-block:: javascript - Given the ``superAdmin`` user with the password ``Password123``, - and access to the ``admin`` database. + use products + db.addUser( { user: "Alice", pwd: "Moon1234", roles: [ "readWrite", "dbAdmin" ] } ) - The following operation in the :program:`mongo` shell will succeed: +.. example:: The following creates a user named ``Bob`` in the + ``admin`` database. The :data:`system.users + <.system.users>` document uses Bob's credentials from + ``products`` database and assigns him ``userAdmin`` privileges. .. code-block:: javascript use admin - db.auth("superAdmin", "Password123") + db.addUser( { user: "Bob", userSource: "products", roles: [ "userAdmin" ] } ) - However, the following operation will fail: +.. example:: The following creates a user named ``Carlos`` in the + ``admin`` database and gives him ``readWrite`` access to the + ``config`` database, which lets him change certain settings for + sharded clusters, such as to disable the balancer. .. code-block:: javascript - use test - db.auth("superAdmin", "Password123") + use admin + db.addUser( { user: "Carlos", pwd: "Moon1234", roles: [ "clusterAdmin" ], otherDBRoles: { config: [ "readWrite" ] } } ) + + The :data:`~admin.system.users.otherDBRoles` field is supported only + on the ``admin`` database. + +For more information about user roles, see the following: -.. note:: + - :doc:`/reference/user-privileges` - 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. + - :doc:`/reference/privilege-documents` .. _auth-localhost-exception: Authentication on Localhost --------------------------- -The behavior of :program:`mongod` running with :setting:`auth`, when -connecting from a client over the localhost interface (i.e. a client -running on the same system as the :program:`mongod`,) varies slightly -between before and after version 2.2. +If there are no users for the ``admin`` database, you may connect via +the localhost interface. That is, if running :program:`mongod` or +:program:`mongos` with :setting:`auth` or :setting:`keyFile`, you can +connect from a client running on the same system as the +:program:`mongod` or :program:`mongos`. -In general if there are no users for the ``admin`` database, you may -connect via the localhost interface. For sharded clusters running -version 2.2, if :program:`mongod` is running with :setting:`auth` then -all users connecting over the localhost interface must authenticate, -even if there aren't any users in the ``admin`` database. +.. note:: There is an issue in MongoDB versions 2.2.0 through 2.2.3 + that means that connections on localhost are not correctly granted + full access on sharded systems that + run those versions. For those versions, if :program:`mongos` is + running with :setting:`keyFile`, then all users connecting over the + localhost interface must authenticate, even if there aren't any users + in the ``admin`` database. + + This issue is fixed as of version 2.2.4. Password Hashing Insecurity --------------------------- In version 2.2 and earlier: -- the *normal* users of a database all have access to the - ``system.users`` collection, which contains the user names and - user password hashes. [#read-and-write-system-users]_ +- the read-write users of a database all have access to the + ``system.users`` collection, which contains the user names and user + password hashes. [#read-and-write-system-users]_ + + .. note:: In 2.4, only users with the ``userAdmin`` role have access + to the ``system.users`` collection. - if a user has the same password for multiple databases, the hash will be the same. A malicious user could exploit this to @@ -170,8 +192,8 @@ In version 2.2 and earlier: As a result, always use unique username and password combinations for each database. -.. [#read-and-write-system-users] Read only users do not have access - to the ``system.users`` database. +.. [#read-and-write-system-users] Read-only users do not have access + to the ``system.users`` collection. .. example: NOT INCLUDED IN OUTPUT.