Security and Authentication

MongoDB includes basic authentication functionality. By default, authentication is off. When off, it is then required that one runs the database in a trusted (network restricted) environment.

Authentication is not available with sharding before v2.0. Older sharded environments must run with the database in a trusted environment.

Please also see the replica set authentication documentation.

Running Without Security (Trusted Environment)

Trusted environment is the default option and is recommended. It is often valid to run the database in a trusted environment with no in-database security and authentication (much like how one would use, say, memcached).  Of course, in such a configuration, one must be sure only trusted machines can access database TCP ports.

Firewall Rules

Given the default ports here are the basic firewall rules needed.

• Replica Sets
  • All clients need to connect to all non-hidden nodes and all nodes need to communicate with each other.
• Sharding
  • Mongos must be able to connect to all config servers and shards (every replica set member)
  • All shards (all replicas if a set) must connect to each other, and the config servers

Mongo Security

The current version of Mongo supports only basic security.  You authenticate a username and password in the context of a particular database.  Once authenticated, a normal user has full read and write access to the database. You can also create read-only users that only have read access.

The admin database is special.  Several administrative commands can only run on the admin database (so can only be run by an admin user). Also, authentication on admin gives a user read and write access to all databases on the server.

Logging in using an admin account Although admin user accounts can access any database, you must log into the admin database. For example, if someAdminUser has an admin account, this login will fail: > use test > db.auth("someAdminUser", password) This one will succeed: > use admin > db.auth("someAdminUser", password)

To enable security, run the database (mongod process) with the --auth option (or --keyFile for replica sets and sharding). You must either have added a user to the admin db before starting the server with authentication, or add the first user from the localhost interface (you cannot add the first user from a connection that is not local with respect to mongod).

Configuring Authentication and Security

We should first create an administrator user for the entire db server process. 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. Thus, from the server running the database (and thus on localhost), run the database shell and configure an administrative user:

$ ./mongo
> use admin
> db.addUser("theadmin", "anadminpassword")

We now have a user created for database admin. Note that if we have not previously authenticated, we now must if we wish to perform further operations, as there is now an admin user.

> db.auth("theadmin", "anadminpassword")

Now, let's configure a "regular" user for another database.

> use projectx
> db.addUser("joe", "passwordForJoe")

Finally, let's add a readonly user. (only supported in 1.3.2+)

> use projectx
> db.addUser("guest", "passwordForGuest", true)

Viewing Users

User information is stored in each database's system.users collection. For example, on a database projectx, projectx.system.users will contain user information.

We can view existing users for the current database with the query:

> db.system.users.find()

Changing Passwords

The shell addUser command may also be used to update a password: if the user already exists, the password simply updates.

Some Mongo drivers provide a helper function equivalent to the db shell's addUser method.

Deleting Users

To delete a user:

db.removeUser( username )

or

db.system.users.remove( { user: username } )

Replica Set and Sharding Authentication

The keyFile is required! You are required to use the keyFile option for sharding or replica set authentication. Just using the auth option will not work.

Replica sets and sharding can use authentication in v1.9.1+ (replica sets without sharding in v1.8). From the client's perspective, it is identical to using single-server authentication: connect to your mongos, create users, authenticate when you make connections.

The only difference is that the servers use a key file to authenticate internal communication. A key file is basically a plaintext file which is hashed and used as an internal password.

To set up replica sets and/or sharding with authentication:

1. Create a key file that can be copied to each server in the set. A key file is composed of characters in the Base64 set, plus whitespace and newlines (see About the Key File for details).
2. Modify this file's permissions to be only readable by the current user.
3. Start each server in the cluster (including all replica set members, all config servers, and all mongos processes) with the --keyFile /path/to/file option.
4. Each client connection to the database must be authenticated before it can be used, as with single-server authentication.

You do not need to use the --auth option, too (although there's no harm in doing so), --keyFile implies --auth. --auth does not imply --keyFile.

Sharded Security

When you enable authentication on the sharded cluster you will be securing connections via the mongos instances and not on individual resources directly like with a single server or a replica set. This is partly because the security information is stored in the sharding config database and not directly on the shards for the admin users. It is also important in a sharded cluster to always have clients connect through a mongos instance and not directly to any resource like the shard servers or config server.

If you do add individual users on sharded resources, the individual shard members, then those users are separate from the sharding "admin" users. These two users sources are different between the sharded cluster and the shards for admin users; care should be taken not to confuse the two or to think that they are same set of users.

Sharded Database Users

Users are stored on the primary shard so authentication can be done there. This may lead to a bit of confusion when you have sharded collections because it may not be obvious that the there is no "system.users" collection on the non-primary shards.

Enabling/disabling authentication on an existing cluster

To enable authentication on an existing cluster, shut down all members and restart them with the --keyFile option. Remember that you must add users before you can access the data remotely.

You can disable authentication by restarting all members without the --keyFile option.

About the Key File

A key file must contain at least 6 Base64 characters and be no larger than 1KB (whitespace included). Whitespace characters are stripped (mostly for cross-platform convenience), so the following keys are identical to the database:

$ 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

If you run mongod with -v, the key will be printed in the log.

Key file permissions

On *NIX, group and everyone must have 0 permissions (up to 700 is allowed). If the permissions are too open on the key file, MongoDB will exit with an error to that effect.

At the moment, permissions are not checked by mongod on Windows.

Ports

Default TCP port numbers for MongoDB processes are as follows:

• Standalone mongod : 27017
• mongos : 27017
• shard server (mongod --shardsvr) : 27018
• config server (mongod --configsvr) : 27019
• web stats page for mongod : add 1000 to port number (28017, by default).  Most stats pages in the HTTP UI are unavailable unless the --rest option is specified.  To disable the "home" stats page use --nohttpinterface.  (This port should be secured, if used, however, the information on the stats home page is read only regardless.)

You can change the port number using the 'port' option when starting mongod.

Do not rely on a non-standard port as a way to secure a Mongo server. Vulnerability scanners will scan across many port numbers looking for a response.

IP Address Binding

By default, a mongod server will listen on all available IP addresses on a machine. You can restrict this to a single IP address with the 'bind_ip' configuration option for mongod.

Typically, this would be set to 127.0.0.1, the loopback interface, to require that mongod only listen to requests from the same machine (localhost).

To enable listening on all interfaces, remove the bind_ip option from your server configuration file.

To accept requests on external interfaces you may also have to modify your computer's firewall configuration to allow access to the ports used by mongo (see above).

Report a Security Issue

If you have discovered any potential security issues in MongoDB, please email security@10gen.com with any and all relevant information.

FAQ

• Are passwords sent over the wire encrypted?
  • Yes. (Actually a nonce-based digest is passed.)

• Are database operations, after authenticating, passed over the wire encrypted?
  • No.