diff --git a/bin/htaccess.yaml b/bin/htaccess.yaml index f887b6caae4..d46b13307bc 100644 --- a/bin/htaccess.yaml +++ b/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' ... diff --git a/source/core/access-control.txt b/source/core/access-control.txt new file mode 100644 index 00000000000..e1c738faa00 --- /dev/null +++ b/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 +<.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 + <.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 +` in the :data:`system.users +<.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 + <.system.users>` changed to accommodate a more + sophisticated user privilege model, as defined in :doc:`privilege + documents `. + +The :data:`system.users <.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. diff --git a/source/core/security.txt b/source/core/security.txt index 3d824de0a75..98c184f70e3 100644 --- a/source/core/security.txt +++ b/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 `, 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 ` 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 ` and :term:`sharded clusters -`) 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 <.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 :doc:`/reference/privilege-documents` for more - information on delegated credentials and :data:`system.users - <.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 diff --git a/source/core/sharded-cluster-security.txt b/source/core/sharded-cluster-security.txt index c1e04176742..95855cd6f74 100644 --- a/source/core/sharded-cluster-security.txt +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/faq/concurrency.txt b/source/faq/concurrency.txt index af6e6979647..087aa0f3d64 100644 --- a/source/faq/concurrency.txt +++ b/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 ` locks the +- :doc:`User authentication ` 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 diff --git a/source/reference/method/db.addUser.txt b/source/reference/method/db.addUser.txt index c7c103214af..5ffe3bdd1ba 100644 --- a/source/reference/method/db.addUser.txt +++ b/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: diff --git a/source/reference/system-collections.txt b/source/reference/system-collections.txt index 710563403a2..4139b72c774 100644 --- a/source/reference/system-collections.txt +++ b/source/reference/system-collections.txt @@ -48,8 +48,9 @@ System collections include these collections stored directly in the database: .. describe:: .system.users The :data:`.system.users` collection stores credentials for - users who have access to the database. For more information on this collection, see - :ref:`security-authentication`. + users who have access to the database. For more information on this + collection, see :doc:`/tutorial/add-user-to-database` and + :data:`.system.users`. .. data:: .system.js diff --git a/source/reference/user-privileges.txt b/source/reference/user-privileges.txt index cdb82d3f147..452e9cade29 100644 --- a/source/reference/user-privileges.txt +++ b/source/reference/user-privileges.txt @@ -16,17 +16,17 @@ Roles .. versionchanged:: 2.4 Roles in MongoDB provide users with a set of specific privileges, on -specific logical databases. Users may have multiple roles, and have +specific logical databases. Users may have multiple roles and may have different roles on different logical database. Roles only grant -privileges and never limit access: :authrole:`read` permissions on -the ``records`` database database and the -:authrole:`readWriteAnyDatabase` permission, that user will be able to +privileges and never limit access: if a user has :authrole:`read` +*and* :authrole:`readWriteAnyDatabase permissions on +the ``records`` database, that user will be able to write data to the ``records`` database. .. note:: By default, MongoDB 2.4 is backwards-compatible with the MongoDB 2.2 - access control roles. You can, however, explicitly disable this + access control roles. You can explicitly disable this backwards-compatibility by setting the :parameter:`supportCompatibilityFormPrivilegeDocuments` option to ``0`` during startup, as in the following command-line invocation of @@ -41,7 +41,8 @@ write data to the ``records`` database. documents are only useful during the upgrade process and while you migrate applications to the updated privilege document form. -See :doc:`/reference/privilege-documents` and :ref:`delegated-credentials` for +See :doc:`privilege documents ` and +:ref:`delegated-credentials` for more information about permissions and authentication in MongoDB. Database User Roles @@ -122,7 +123,7 @@ Database Administration Roles - :dbcommand:`renameCollection` (within a single database.) - :dbcommand:`validate` - Furthermore only :authrole:`dbAdmin` has the ability to read the + Furthermore, only :authrole:`dbAdmin` has the ability to read the :data:`system.profile <.system.profile>` collection. .. - :dbcommand:`storageDetails` (experimental command.) @@ -139,10 +140,10 @@ Database Administration Roles .. authrole:: userAdmin Allows users to read and write data to the :data:`system.users - <.system.users>` collection. of any database. Users with - this role will be able to modify permissions for existing users, + <.system.users>` collection of any database. Users with + this role will be able to modify permissions for existing users and create new users. :authrole:`userAdmin` does not restrict the - permissions that a user can grant, and an :authrole:`userAdmin` + permissions that a user can grant, and a :authrole:`userAdmin` user can grant privileges to themselves or other users in excess of the :authrole:`userAdmin` users' current privileges. @@ -159,7 +160,7 @@ Administrative Roles :authrole:`clusterAdmin` 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 + rather than just a single database. These privileges include but are not limited to :term:`replica set` and :term:`sharded cluster` administrative functions. @@ -228,7 +229,7 @@ Any Database Roles You must specify the following "any" database roles on the ``admin`` databases. These roles apply to all databases in a - :program:`mongod` instance, and are roughly equivalent to their + :program:`mongod` instance and are roughly equivalent to their single-database equivalents. If you add any of these roles to a :doc:`user privilege document diff --git a/source/security.txt b/source/security.txt index 96c4c0dcb3d..295ac2d9eba 100644 --- a/source/security.txt +++ b/source/security.txt @@ -2,40 +2,48 @@ Security ======== -The documents in this section outline basic security practices and -risk management 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. +The documentation in this section outlines basic security, risk +management, and access control, and includes specific tasks for +configuring firewalls, authentication, and system privileges. User roles +in MongoDB provide granular control over user authorization and access. If you believe you have discovered a vulnerability in MongoDB, please see :doc:`/tutorial/create-a-vulnerability-report`. -Strategies and Practices ------------------------- +Security Concepts and Strategies +-------------------------------- .. toctree:: :maxdepth: 1 /core/security + /core/access-control Tutorials --------- +Network Security +~~~~~~~~~~~~~~~~ + .. toctree:: - :maxdepth: 1 + :titlesonly: /tutorial/configure-linux-iptables-firewall /tutorial/configure-windows-netsh-firewall - /tutorial/control-access-to-mongodb-with-authentication - /tutorial/control-access-to-mongodb-with-kerberos-authentication /tutorial/create-a-vulnerability-report +Access Control +~~~~~~~~~~~~~~ + +.. toctree:: + :titlesonly: + + /tutorial/enable-authentication + /tutorial/add-user-administrator + /tutorial/add-user-to-database + /tutorial/generate-key-file + /tutorial/control-access-to-mongodb-with-kerberos-authentication + Reference --------- diff --git a/source/tutorial.txt b/source/tutorial.txt index 8e46cec4528..a0aca959e5c 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -98,8 +98,12 @@ Security - :doc:`/tutorial/configure-linux-iptables-firewall` - :doc:`/tutorial/configure-windows-netsh-firewall` -- :doc:`/tutorial/control-access-to-mongodb-with-authentication` - +- :doc:`/tutorial/enable-authentication` +- :doc:`/tutorial/add-user-administrator` +- :doc:`/tutorial/add-user-to-database` +- :doc:`/tutorial/generate-key-file` +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/create-a-vulnerability-report` .. index:: tutorials; development patterns .. index:: development tutorials diff --git a/source/tutorial/add-user-administrator.txt b/source/tutorial/add-user-administrator.txt new file mode 100644 index 00000000000..f2b444b0266 --- /dev/null +++ b/source/tutorial/add-user-administrator.txt @@ -0,0 +1,90 @@ +================================================== +Create an Administrator with Superuser Credentials +================================================== + +.. default-domain:: mongodb + +A MongoDB superuser is a user with either the +:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role. The user +with either of these roles can create and modify any other users and can +assign them any privileges. The user also can grant *itself* any +privileges. In production deployments, this user should have *no other +roles* and should only administer users and privileges. + +This should be the first user created for a MongoDB deployment and +should be used to create all other users in the system. + +.. important:: The :authrole:`userAdminAnyDatabase` user can grant + itself and any other user full access to anything. The credentials to + log in as this user should be carefully controlled. + +Create an Administrator Superuser +--------------------------------- + +1. Connect to the :program:`mongod` or :program:`mongos` by either: + + - Authenticating as an existing user with the :authrole:`userAdmin` + or :authrole:`userAdminAnyDatabase` role. + + - Authenticating using the :ref:`localhost exception + `. When creating the first user in a + deployment, you must authenticate using the :ref:`localhost exception + `. + +#. Switch to the ``admin`` database: + + .. code-block:: javascript + + db = db.getSiblingDB('admin') + +#. Add the user with either the :authrole:`userAdmin` role or + :authrole:`userAdminAnyDatabase` role, and only that role, by issuing + a command similar to the following, where ```` is the + username and ```` is the password: + + .. code-block:: javascript + + db.addUser( { user: "", + pwd: "", + roles: [ "userAdminAnyDatabase" ] } ) + +.. _localhost-exception: + +Authenticate with Full Administrative Access via Localhost +---------------------------------------------------------- + +If there are no users for the ``admin`` database, you can connect with +full administrative access via the localhost interface. This bypass +exists to support bootstrapping new deployments. This approach is +useful, for example, if you want to run :program:`mongod` or +:program:`mongos` with authentication before creating your first user. + +To authenticate via localhost, connect to the :program:`mongod` or +:program:`mongos` from a client running on the same system. Your +connection will have full administrative access. + +To disable the localhost bypass, set the +:parameter:`enableLocalhostAuthBypass` parameter using +:setting:`setParameter` during startup: + +.. code-block:: javascript + + mongod --setParameter mongod enableLocalhostAuthBypass=1 + +.. note:: + + For versions of MongoDB 2.2 prior to 2.2.4, 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. Connections on localhost are not correctly + granted full access on sharded systems that run those versions. + + MongoDB 2.2.4 resolves this issue. + +.. note:: + + In version 2.2, you cannot add the first user to a sharded cluster + using the ``localhost`` 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`. diff --git a/source/tutorial/add-user-to-database.txt b/source/tutorial/add-user-to-database.txt new file mode 100644 index 00000000000..db956fe5692 --- /dev/null +++ b/source/tutorial/add-user-to-database.txt @@ -0,0 +1,66 @@ +======================== +Add a User to a Database +======================== + +.. default-domain:: mongodb + +To add a user to a database you must authenticate to that database as a +user with the :authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` +role. If you have not first created a user with one of those roles, do +so as described in :doc:`/tutorial/add-user-administrator`. + +When adding a user to multiple databases, you must give the user a +unique username and password combination *for each database*. See +:ref:`password-hashing-security` for important security information. + +To add a user, pass the :method:`db.addUser()` method a well formed +:doc:`privilege 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. + +For the structure of a privilege document, see :data:`system.users +<.system.users>`. For descriptions of user roles, see +:doc:`/reference/user-privileges`. + +.. example:: The following creates a user named ``Alice`` in the + ``products`` database and gives her ``readWrite`` and + ``dbAdmin`` privileges. + + .. code-block:: javascript + + use products + db.addUser( { user: "Alice", + pwd: "Moon1234", + roles: [ "readWrite", "dbAdmin" ] + } ) + +.. example:: The following creates a user named ``Bob`` in the + ``admin`` database. The :data:`privilege document + <.system.users>` uses Bob's credentials from the + ``products`` database and assigns him ``userAdmin`` privileges. + + .. code-block:: javascript + + use admin + db.addUser( { user: "Bob", + userSource: "products", + roles: [ "userAdmin" ] + } ) + +.. 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 + + db = db.getSiblingDB('admin') + db.addUser( { user: "Carlos", + pwd: "Moon1234", + roles: [ "clusterAdmin" ], + otherDBRoles: { config: [ "readWrite" ] + } } ) + + Only the ``admin`` database supports the + :data:`~admin.system.users.otherDBRoles` field. diff --git a/source/tutorial/control-access-to-mongodb-with-authentication.txt b/source/tutorial/control-access-to-mongodb-with-authentication.txt deleted file mode 100644 index 8c26f659839..00000000000 --- a/source/tutorial/control-access-to-mongodb-with-authentication.txt +++ /dev/null @@ -1,301 +0,0 @@ -========================= -Access Control in MongoDB -========================= - -.. default-domain:: mongodb - -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 -`. - -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:`/core/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:`/core/security` document. - -.. [#cli-options] Use the :option:`--auth ` or - :option:`--keyFile ` options on the command - line. - -.. _control-access-add-users: - -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 the first user to the ``admin`` database when connected to the - :program:`mongod` instance from a ``localhost`` connection. - [#sharded-localhost]_ - -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`, in version - 2.2 you cannot add the first user to a sharded cluster using the - ``localhost`` 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 a User with the ``userAdminAnyDatabase`` Role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -The user with the ``userAdminAnyDatabase`` role is effectively a -super-user, as the user can grant itself any role. In production -deployments, this user should have *no other roles* and should only -administer users and privileges. - -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. - -1. Connect to the :program:`mongod` or :program:`mongos` on the - ``localhost`` interface using the :program:`mongo` shell. - -#. Switch to the ``admin`` database: - - .. code-block:: javascript - - use admin - -#. 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: - - .. code-block:: javascript - - db.addUser( { user: "", pwd: "", roles: [ "userAdminAnyDatabase" ] } ) - - For more information on creating a user, see - :ref:`control-access-add-user-to-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`. - -.. _control-access-add-user-to-database: - -Add a User to a Database -~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a user to a database you must authenticate to that database as a -user with the ``userAdmin`` role. - -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. - -For the structure of user privilege documents, see :data:`system.users -<.system.users>`. The following are example documents. - -.. example:: The following creates a user named ``Alice`` in the - ``products`` database and gives her ``readWrite`` and - ``dbAdmin`` privileges. - - .. code-block:: javascript - - use products - db.addUser( { user: "Alice", pwd: "Moon1234", roles: [ "readWrite", "dbAdmin" ] } ) - -.. 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.addUser( { user: "Bob", userSource: "products", roles: [ "userAdmin" ] } ) - -.. 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 admin - db.addUser( { user: "Carlos", pwd: "Moon1234", roles: [ "clusterAdmin" ], otherDBRoles: { config: [ "readWrite" ] } } ) - - Only the ``admin`` database supports the - :data:`~admin.system.users.otherDBRoles` field. - -For more information about user roles, see -:doc:`/reference/user-privileges` and -:doc:`/reference/privilege-documents`. - -.. _auth-localhost-exception: - -Authentication on Localhost ---------------------------- - -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`, and your connection will have -full administrative access. This bypass exists to support -bootstrapping new deployments. To disable the localhost bypass, set -the :parameter:`enableLocalhostAuthBypass` parameter using -:setting:`setParameter` during startup. - -.. note:: - - For version of MongoDB 2.2 before 2.2.4, 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. - - MongoDB 2.2.4 resolves this issue. - -Password Hashing Insecurity ---------------------------- - -In version 2.2 and earlier: - -- 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 - gain access on a second database using a different user's credentials. - -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`` collection. - -.. example: NOT INCLUDED IN OUTPUT. - - Eve connects to the ``db1`` database and views the ``system.users`` - collection, with the following invocation of :program:`mongo`: - - .. code-block:: sh - - mongo /db1 -u eve -p test - - Then, in the :program:`mongo` shell, issues the following - operation: - - .. code-block:: javascript - - db.system.users.find() - - This operation returns the following documents: - - .. code-block:: javascript - - { "_id": ObjectId("5074202e032a960d16f4394e"), "user": "alice", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } - { "_id": ObjectId("507420ba032a960d16f43951"), "user": "eve", "readOnly": false, "pwd": "5dcc2819b97e68d5cfe51da6cae8a7f6" } - - Alice has read and write accounts on both ``db1`` and ``db2`` and - also has access on the ``admin`` database. Consider the following - example where Alice authenticates to the ``admin`` db: - - .. code-block:: javascript - - use admin - db.auth("alice", "pass") - - Consider the output of :method:`find() ` on - the ``system.users`` collection: - - .. code-block:: javascript - - db.system.users.find() - - The following output confirms that the user has the same password and hash: - - .. code-block:: javascript - - { "_id": ObjectId("50742045032a960d16f43950"), "user": "alice", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } - -Thanks to Will Urbanski, from Dell SecureWorks, for identifying this issue. - -Configuration Considerations for Authentication ------------------------------------------------ - -The following sections outline practices for enabling and managing -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 than 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. - -Windows Systems -~~~~~~~~~~~~~~~ - -Use the following ``openssl`` command at the system shell to generate -pseudo-random content for a key file for deployments with Windows -components: - -.. code-block:: sh - - openssl rand -base64 741 - -Linux and Unix Systems -~~~~~~~~~~~~~~~~~~~~~~ - -Use the following ``openssl`` command at the system shell to generate -pseudo-random content for a key file for systems that do not have -Windows components (i.e. OS X, Unix, or Linux systems): - -.. code-block:: sh - - openssl rand -base64 753 - -Key File Properties -~~~~~~~~~~~~~~~~~~~ - -Be aware that MongoDB strips whitespace characters (e.g. ``x0d``, -``x09``, and ``x20``,) for cross-platform convenience. As a result, -the following operations produce identical keys: - -.. code-block:: sh - - echo -e "my secret key" > key1 - echo -e "my secret key\n" > key2 - echo -e "my secret key" > key3 - echo -e "my\r\nsecret\r\nkey\r\n" > key4 diff --git a/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt b/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt index b6ac2ecb585..e1468121556 100644 --- a/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt +++ b/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt @@ -48,7 +48,8 @@ To run MongoDB with Kerberos support, you must: run time options. - If you did not create Kerberos user accounts, you can use the - :ref:`localhost exception ` to create users + :ref:`localhost exception ` + to create users at this point until you create the first user on the ``admin`` database. @@ -190,7 +191,8 @@ If you encounter problems when trying to start :program:`mongod` or you must :ref:`create users ` and grant them privileges within MongoDB. If you have not created users when you start MongoDB with Kerberos you can use the :ref:`localhost - authentication exception ` to add + authentication exception ` + to add users. See the :ref:`kerberos-create-users` section and the :doc:`/reference/user-privileges` document for more information. diff --git a/source/tutorial/enable-authentication-in-sharded-cluster.txt b/source/tutorial/enable-authentication-in-sharded-cluster.txt index 1ca16bcb83b..3baa70bb6c5 100644 --- a/source/tutorial/enable-authentication-in-sharded-cluster.txt +++ b/source/tutorial/enable-authentication-in-sharded-cluster.txt @@ -15,7 +15,7 @@ instances. The content of the key file is arbitrary but must be the same on all cluster members. .. note:: For an overview of authentication, see - :ref:`security-authentication`. For an overview of security, see + :doc:`/core/access-control`. For an overview of security, see :doc:`/security`. Procedure @@ -49,4 +49,4 @@ To enable authentication, do the following: explicitly. #. Add the first administrative user and then add subsequent users. See - :ref:`control-access-add-users`. + :doc:`/tutorial/add-user-administrator`. diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt new file mode 100644 index 00000000000..b4a8f703290 --- /dev/null +++ b/source/tutorial/enable-authentication.txt @@ -0,0 +1,123 @@ +=========================== +Enable Basic Authentication +=========================== + +.. default-domain:: mongodb + +Authentication is enabled by the :setting:`auth` or +:setting:`keyFile` setting. A single-instance deployment uses +:setting:`auth`. Instances with :term:`replica sets ` or +:term:`sharded clusters ` use the :setting:`keyFile` +setting, which implies :setting:`auth` and allows intra-deployment +authentication and operation. + +Authentication requires that you have at least one administrator user in +the ``admin`` database. You can create the user before enabling +authentication or after enabling authentication. + +Create the Administrator and then Enable Authentication +------------------------------------------------------- + +1. Start the :program:`mongod` or :program:`mongos` instance *without* + the :setting:`auth` or :setting:`keyFile` setting. + +#. Create the administrator user as described in + :doc:`/tutorial/add-user-administrator`. + +#. Re-start the :program:`mongod` or :program:`mongos` instance with the + :setting:`auth` or :setting:`keyFile` setting. + +Enable Authentication and then Create Administrator +--------------------------------------------------- + +1. Start the :program:`mongod` or :program:`mongos` instance with + the :setting:`auth` or :setting:`keyFile` setting. + +#. Connect to the instance on the same system so that you can + authenticate using the :ref:`localhost exception + `. + +#. Create the administrator user as described in + :doc:`/tutorial/add-user-administrator`. + +Query Authenticated Users +------------------------- + +If you have the :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role on a database, you can query +authenticated users in that database with the following operation: + +.. code-block:: javascript + + db.system.users.find() + +.. _password-hashing-security: + +Password Hashing Insecurity +--------------------------- + +In version 2.2 and earlier: + +- 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 + gain access on a second database using a different user's credentials. + +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`` collection. + +.. example: NOT INCLUDED IN OUTPUT. + + Eve connects to the ``db1`` database and views the ``system.users`` + collection, with the following invocation of :program:`mongo`: + + .. code-block:: sh + + mongo /db1 -u eve -p test + + Then, in the :program:`mongo` shell, issues the following + operation: + + .. code-block:: javascript + + db.system.users.find() + + This operation returns the following documents: + + .. code-block:: javascript + + { "_id": ObjectId("5074202e032a960d16f4394e"), "user": "alice", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } + { "_id": ObjectId("507420ba032a960d16f43951"), "user": "eve", "readOnly": false, "pwd": "5dcc2819b97e68d5cfe51da6cae8a7f6" } + + Alice has read and write accounts on both ``db1`` and ``db2`` and + also has access on the ``admin`` database. Consider the following + example where Alice authenticates to the ``admin`` db: + + .. code-block:: javascript + + use admin + db.auth("alice", "pass") + + Consider the output of :method:`find() ` on + the ``system.users`` collection: + + .. code-block:: javascript + + db.system.users.find() + + The following output confirms that the user has the same password and hash: + + .. code-block:: javascript + + { "_id": ObjectId("50742045032a960d16f43950"), "user": "alice", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } + +Thanks to Will Urbanski, from Dell SecureWorks, for identifying this issue. diff --git a/source/tutorial/generate-key-file.txt b/source/tutorial/generate-key-file.txt new file mode 100644 index 00000000000..43abe17aefa --- /dev/null +++ b/source/tutorial/generate-key-file.txt @@ -0,0 +1,53 @@ +.. _generate-key-file: + +=================== +Generate a Key File +=================== + +.. default-domain:: mongodb + +This section describes how to generate a key file to store +authentication information. After generating a key file, specify the key +file using the :setting:`keyFile` option when starting a +:program:`mongod` or :program:`mongos` instance. + +A key file must be less than 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. + +Generate a Key File on a Windows System +--------------------------------------- + +Use the following ``openssl`` command at the system shell to generate +pseudo-random content for a key file for deployments with Windows +components: + +.. code-block:: sh + + openssl rand -base64 741 + +Generate a Key File on a Linux or Unix System +---------------------------------------------- + +Use the following ``openssl`` command at the system shell to generate +pseudo-random content for a key file for systems that do not have +Windows components (i.e. OS X, Unix, or Linux systems): + +.. code-block:: sh + + openssl rand -base64 753 + +Key File Properties +------------------- + +Be aware that MongoDB strips whitespace characters (e.g. ``x0d``, +``x09``, and ``x20``,) for cross-platform convenience. As a result, +the following operations produce identical keys: + +.. code-block:: sh + + echo -e "my secret key" > key1 + echo -e "my secret key\n" > key2 + echo -e "my secret key" > key3 + echo -e "my\r\nsecret\r\nkey\r\n" > key4