diff --git a/draft/core/security.txt b/draft/core/security.txt index 9cc37a64a1c..a44a80e18db 100644 --- a/draft/core/security.txt +++ b/draft/core/security.txt @@ -6,7 +6,7 @@ Authentication and Security 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 solution for 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 @@ -80,7 +80,8 @@ By default, listens for connections on the following ports: ``27017`` This is the default port :program:`mongod` and :program:`mongos` - instances. You can change this port with :setting:`port`. + instances. You can change this port with :setting:`port` or + :option:`--port `. ``27018`` This is the default port when running with :option:`--shardsvr @@ -89,7 +90,7 @@ By default, listens for connections on the following ports: ``27019`` This is the default port when running with :option:`--configsvr - ` runtime operation or :setting:`commonsvr` + ` runtime operation or :setting:`configsvr` setting. ``28017`` @@ -278,7 +279,7 @@ authentication system: - When setting up authentication for the first time you must either: - a. add at least one user to the ``admin`` database before starting + #. 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 @@ -291,10 +292,10 @@ authentication system: Consider the :doc:`/tutorial/use-authentication-to-control-access-to-mongodb` -document which outlines procedures for configuraing and maintaing +document which outlines procedures for configuring and maintaining users and access with MongoDB's authentication system. -.. [#sharded-localhost] Becasue of :issue:`SERVER-6591`, you cannot +.. [#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 @@ -304,19 +305,19 @@ users and access with MongoDB's authentication system. Interfaces ---------- -Simply limiting access to a :program:`mongod` is not a sufficent for -totally controling risk expsorure. Consider the recomendaitons in the +Simply limiting access to a :program:`mongod` is not a sufficient for +totally controlling risk exposure. Consider the recommendations in the following section, for limiting exposure other interface-related risks. -JavaScript and the Security of the ``mongo`` Sell -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +JavaScript and the Security of the ``mongo`` Shell +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Be aware of the following capabilities and behaviors of the :program:`mongo` shell: - :program:`mongo` will evaluate a ``.js`` file passed to the - :option:`mongo --eval` operation. command. The :program:`mongo` + :option:`mongo --eval` option. The :program:`mongo` shell does not validate the input of JavaScript input to :option:`--eval `. @@ -325,10 +326,10 @@ Be aware of the following capabilities and behaviors of the :option:`mongo --norc`` option. On Linux and Unix systems, :program:`mongo` reads the - ``.mongorc.js`` file from ``$HOME/.mongorc.js`` - (i.e. ``~/.mongorc.js``), and Windows :program:`mongo` reads the - ``.mongorc.js`` file from ``%HOME%\.mongorc.js`` or - ``%HOMEDRIVE%\%HOMEPATH%\.mongorc.js``. + :file:`.mongorc.js` file from :file:`{$HOME}/.mongorc.js` + (i.e. :file:`~/.mongorc.js`), and Windows :program:`mongo.exe` reads the + :file:`.mongorc.js` file from :file:`{%HOME%}\.mongorc.js` or + :file:`{%HOMEDRIVE%}\{%HOMEPATH%}\.mongorc.js`. HTTP Status Interface ~~~~~~~~~~~~~~~~~~~~~ @@ -336,14 +337,14 @@ HTTP Status Interface The HTTP status interface provides a web-based interface that includes a variety of operational data, logs, and status reports regarding the :program:`mongod` or :program:`mongos` instance. The HTTP interface is -always avalible on the the port numbered ``1000`` greater than the +always available on the the port numbered ``1000`` greater than the primary :program:`mongod` port. By default this is ``28017``, but is indirectly using the :setting:`port` option which allows you to configure the primary :program:`mongod` port. Without the :setting:`rest` setting, this interface is entirely -read-only, and limited in scope; nevertheless, this iterface may -represent an exposure. To diable the HTTP interface, set the +read-only, and limited in scope; nevertheless, this interface may +represent an exposure. To disable the HTTP interface, set the :setting:`nohttpinterface` run time option or the :option:`--nohttpinterface ` command line option. @@ -372,15 +373,15 @@ the REST API interface: Data Encryption --------------- -To support audit requirements, you may need to envrypt data stored in +To support audit requirements, you may need to encrypt data stored in MongoDB. For best results you can encrypt this data in the application -layer, by encrytping the content of fields that hold secure data. +layer, by encrypting the content of fields that hold secure data. Additionally, `10gen`_ has a `partnership`_ with `Gazzang`_ to encrypt -and secure senitive data within MongoDB. The solution encrypts data in +and secure sensitive data within MongoDB. The solution encrypts data in real time and Gazzang provides advanced key management that ensures -only authorized processes and can access this data. THe Gazzang -software ensures that the cryptogrpahic keys rmeain safe and ensures +only authorized processes and can access this data. The Gazzang +software ensures that the cryptographic keys remain safe and ensures compliance with standards including HIPPA, PCI-DSS, and FERPA. For more information consider the following resources: diff --git a/draft/tutorial/configure-linux-iptables-firewall.txt b/draft/tutorial/configure-linux-iptables-firewall.txt index e4e95e646f7..2164eb20c25 100644 --- a/draft/tutorial/configure-linux-iptables-firewall.txt +++ b/draft/tutorial/configure-linux-iptables-firewall.txt @@ -2,6 +2,8 @@ Configure Linux ``iptables`` Firewall for MongoDB ================================================= +.. default-domain:: mongodb + The ``iptables`` program manages the firewall rules on Linux and typically comes built in with each Linux distribution. For this article we only need to worry about two ``iptables`` chains: diff --git a/draft/tutorial/configure-windows-netsh-firewall.txt b/draft/tutorial/configure-windows-netsh-firewall.txt index 2d45a4b0400..9cf7dd560e2 100644 --- a/draft/tutorial/configure-windows-netsh-firewall.txt +++ b/draft/tutorial/configure-windows-netsh-firewall.txt @@ -2,6 +2,7 @@ Configure Windows ``netsh`` Firewall for MongoDB ================================================ +.. default-domain:: mongodb The Windows Firewall is configured on the cli, using ``netsh``. Here are some example firewall rules for MongoDB traffic - diff --git a/draft/tutorial/use-authentication-to-control-access-to-mongodb.txt b/draft/tutorial/use-authentication-to-control-access-to-mongodb.txt index 4d5f0d88783..24d89641a08 100644 --- a/draft/tutorial/use-authentication-to-control-access-to-mongodb.txt +++ b/draft/tutorial/use-authentication-to-control-access-to-mongodb.txt @@ -3,3 +3,354 @@ Use Authentication to Control Access to MongoDB =============================================== .. default-domain:: mongodb + +Basic authentication and access control is enabled with the +:option:`--auth ` +or +:option:`--keyFile ` +options in versions of MongoDB up to and including version 2.2. + +Some important things to note about authentication: + +* Authentication is off by default. +* Prior to version 2.0, it is not possible to enable authentication + in a sharded environment. + +* Once authenticated, a normal user has full "read and write" access + to the database. You can also create read-only users, who only + have read access. + +Each database contains a "system.users" collection, which contains +all the user information. For example: + +.. code-block:: javascript + + > db.system.users.find() + { "_id": ObjectId("5075362366b2b6e3603b65c9"), "user": "readOnly", "readOnly": true, "pwd": "76841722f39207db6b332e64bfacd4ba" } + Fetched 1 record(s) in 1ms -- Index[none] -- More[false] + + +Role-based access control with MongoDB is simple +with only two roles – "read" and "normal" (i.e. full read/write +access). There are several tickets related to improving the +implementation of authorization within MongoDB: + +* :issue:`SERVER-3198` +* :issue:`SERVER-7122` +* :issue:`SERVER-7124` + +The admin database is special. Several administrative commands +can only run on the admin database (and so can only be run by an +admin user). You can use the `db.admin.command()` shell helper as +one way of running administrative commands. For example, to list +all databases: + +.. code-block:: javascript + + db.adminCommand( { listDatabases : 1 } ) + +Additionally, please be aware that users with access to the admin +database have “read and write” access to all other databases on +the server/cluster. + +Adding Users +------------ + +You must either: + +#. have added a user to the admin db before starting the server with + :option:`--auth `, + +#. added the first user from a localhost connection (you cannot add + the first user from a connection that is not local with respect to + the :program:`mongod` process). + +.. note:: + + Option (2) to add a user via localhost does not work in + sharded clusters running v2.2+ due to :issue:`SERVER-6591`. If you are + running 2.2 with a sharded cluster and want to use secure mode you + must setup the cluster and add an admin user before restarting the + cluster to run with :option:`--keyFile `. + +Configuration +~~~~~~~~~~~~~ + +First create an administrator for the `mongod` instance. This +user is stored under the special `admin` database. + +If there are no admin users, one may access the database from the +localhost interface without authenticating. Therefore, on the +localhost, run the :program:`mongo` shell and configure an admin user: + +.. code-block:: javascript + + > use admin // we are using the admin database + > db.addUser("theadmin", "anadminpassword") + +Now, let’s configure a “regular” user for another database (projectx): + +.. code-block:: javascript + + > use projectx // we are using the a projectx database + > db.addUser("joe", "passwordForJoe") + +Let’s add a read-only user: + +.. code-block:: javascript + + > use projectx + > db.addUser("guest", "passwordForGuest", true) + +Logging in as Admin User + +Although admin user accounts can access any database, you must log +into the admin database. For example, if user ``superAdmin`` has an +admin account, this login will be successful: + +.. code-block:: javascript + + $ mongo + > use admin + > db.auth("superAdmin", "Password123") + +but these commands below will fail: + +.. code-block:: javascript + + > use test + > db.auth("superAdmin", "Password123") + 1 + +In versions up to and including 2.2, be aware that once you have +``admin`` access in the :program:`mongo` shell, you have admin access. +If you try to authenticate to a read-only user, the authentication +will succeed, however, you will still have ``admin``, i.e. write, +permissions. + +For example, authenticate as an admin (notice the shell prompt changes): + +.. code-block:: javascript + + > use admin + switched to db admin + + admin> db.auth("adminUser", "adminPassword") + 1 + + admin> use test + switched to db test + + test> db.system.users.find() + { "_id": ObjectId("5075362366b2b6e3603b65c9"), "user": "readOnly", "readOnly": true, "pwd": "76841722f39207db6b332e64bfacd4ba" } + Fetched 1 record(s) in 1ms -- Index[none] -- More[false] + + +Now, authenticate as ``readOnly``, note that your id does not change +and you will still have ``write`` access: + +.. code-block:: javascript + + test> db.auth("readOnly", "readOnly") + + test> db.coll.insert({foo:'bar'}) // still actually adminUser + Inserted 1 record(s) in 1ms + + test > db.coll.find() + { "_id": ObjectId("50753692492db9d88b98f7dc"), "foo": "bar" } + Fetched 1 record(s) in 1ms -- Index[none] -- More[false] + +Authentication on Localhost +--------------------------- + +.. versionadded:: 2.0 + +The trust model, in this version, dictates that that if the +user has access to running the mongo shell on localhost +(127.0.0.1) then the user has write access to add users +regardless of what authentication is enforced in the :program:`mongod` +configuration, i.e. authentication does not apply to users +logging into `mongod` on localhost. + + +.. versionchanged:: 2.2 + +The trust model changed for MongoDB 2.2. If :program:`mongod` +is started with the :option:`--auth ` option then +authentication is applied to local users. + +For example, below the user connects as a read-only user to the +test database and tries to insert a collection but cannot. + +.. code-block:: sh + + $ mongo localhost/test -u readOnly -p test + +.. code-block:: javascript + + MongoDB shell version: 2.2.0 + connecting to: localhost/test + + test > db.coll.insert({foo:'bar'}) + unauthorized + + test > db.system.users.find() + error: { + "$err": "unauthorized db:test ns:test.system.users lock type:1 client:127.0.0.1", + "code": 10057 + } + +However, when connecting to MongoDB over localhost with +authentication enabled but without any admin users, the user may +access the database from the localhost interface without +authenticating. + +In summary, below is a table of the scenarios for accessing the +database when running with authentication enabled: + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Connection + - Admin Users Exist + - Authentication Required on Accessing Database + * - Localhost + - Yes + - Yes + * - Localhost + - No + - No + * - Remote + - Yes + - Yes + * - Remote + - No + - Yes + +Password Hashing Insecurity +--------------------------- + +In version 2.2.* and earlier, it is possible that if an evil user +“Eve” has admin access to the same database (db1) as another user +“Bob” and Bob is an admin user on another database (db2) and has +used the same password on db2 then Eve can take the hash of Bob’s +password from the system.users collection on db1 to log in as Bob +on db2. + +This authentication schema is working as designed and is +consistent with the MongoDB trust model up to and including 2.2. +Subsequent versions of MongoDB will contain more secure and +enterprise-type authentication models. For further information, +please see :issue:`SERVER-3198` and :issue:`SERVER-7155`. + +Below is a step-by-step walkthrough. + +Eve connects to the “test” database and we see that +both Eve and Bob have accounts with “admin” access: + +.. code-block:: sh + + $ mongo 10.7.100.27/db1 -u eve -p test + +.. code-block:: javascript + + MongoDB shell version: 2.2.0 + connecting to: 10.7.100.27/db1 + test> db.system.users.find() + { "_id": ObjectId("5074202e032a960d16f4394e"), "user": "bob", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } + { "_id": ObjectId("507420ba032a960d16f43951"), "user": "eve", "readOnly": false, "pwd": "5dcc2819b97e68d5cfe51da6cae8a7f6" } + Fetched 2 record(s) in 1ms -- Index[none] -- More[false] + +Bob also has an account on the admin database and has used the same password: + +.. code-block:: javascript + + test> use admin + switched to db admin + test> db.auth("bob", "test") + + admin> db.system.users.find() + { "_id": ObjectId("50742045032a960d16f43950"), "user": "bob", "readOnly": false, "pwd": "ac2061b4a08ef8f2d60a07dc18ab4a0a" } + Fetched 1 record(s) in 1ms -- Index[none] -- More[false] + +Secure Mode on Shards and Replica Sets +-------------------------------------- + +To secure a shard cluster using Secure Mode, you must enable +secure mode on all components of the shard cluster. Use the +:option:`--keyFile ` +option on all routers (:program:`mongos`), +configuration database servers (:program:`mongod --configsvr`), +and shard servers (:program:`mongod --shardsvr`). + +There are two classes of security credentials in a shard cluster: +credentials for "admin" users (i.e. for the "admin" database) and +credentials for all other databases. These credentials reside in +different locations within the shard cluster and have different +roles: + +Admin database credentials reside on the config databases. To +receive admin access to the cluster you must authenticate a +session while connected to a mongos instance using the "admin" +database. + +Other database credentials reside on the primary shard for the +database. + +This means that you can authenticate to these users and databases +while connected directly to the primary shard for a database, +however, for clarity and consistency all interactions between the +client and the database should use a mongos instance. + +Individual shards can store administrative credentials to their +instance, which only permit access to a single shard. These +credentials are stored in the shard’s "admin" database and are +completely distinct from the cluster-wide administrative +credentials described in "1." above. + + +To enable “secure mode” on shards or replica sets, the --auth +option is not sufficient, you must use the `--keyFile` option. + +To enable secure mode, run the mongod process with the `--auth` +option (or --keyFile for replica sets and sharding). For example, + +.. code-block:: sh + + mongod --auth + + mongod --shardsvr --keyFile MySecretKey + + +KeyFile +------- + +A key file must contain at least six Base64 characters and be no +larger than 1KB (whitespace included). Whitespace characters (x0d, +x09, x20) are stripped (mostly for cross-platform convenience), so +to the database, the following keys are identical: + +.. 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 + +As the key is stored in a file, you won't have to type it in much, +so it is a good idea to make it long and with a good degree of +randomness within it – 32 characters long for example. A possible +solution is to generate it with `mkpasswd` plus extra-appended +characters from the administrator setting up the cluster. + +.. warning:: + + If you run mongod with `-v`, the key will be printed in the log. + +The keyFile must be owned and readable by the account running the +MongoDB instance. The MongoDB instance will exit with an error if +the keyFile is readable, writeable or executable by any other +account on the system. + +Currently, permissions are not checked by :program:`mongod.exe` on Windows. \ No newline at end of file