• Security >
• Control Access to MongoDB Instances with Authentication

Control Access to MongoDB Instances with Authentication

MongoDB provides a basic authentication system, that you can enable with the auth and keyFile configuration settings. [1] See the authentication section of the Security Practices and Management document.

This document contains an overview of all operations related to authentication and managing a MongoDB deployment with authentication.

See

The Security Considerations section of the Run-time Database Configuration document for more information on configuring authentication.

[1]	Use the --auth --keyFile options on the command line.

Add Users

When setting up authentication for the first time you must either:

1. add at least one user to the admin database before starting the mongod instance with auth.
2. add the first user to the admin database when connected to the mongod instance from a localhost connection. [2]

Begin by setting up the first administrative user for the mongod instance.

[2]

Because of 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 keyFile.

Add an Administrative User

About administrative users

Administrative users are those users that have “normal” or read and write access to the admin database.

If this is the first administrative user, [3] connect to the mongod on the localhost interface using the mongo shell. Then, issue the following command sequence to switch to the admin database context and add the administrative user:

copy

use admin
db.addUser("<username>", "<password>")

Replace <username> and <password> with the credentials for this administrative user.

[3]	You can also use this procedure if authentication is not enabled so that your databases has an administrative user when you enable auth.

Add a Normal User to a Database

To add a user with read and write access to a specific database, in this example the records database, connect to the mongod instance using the mongo shell, and issue the following sequence of operations:

copy

use records
db.addUser("<username>", "<password>")

Replace <username> and <password> with the credentials for this user.

Add a Read Only User to a Database

To add a user with read only access to a specific database, in this example the records database, connect to the mongod instance using the mongo shell, and issue the following sequence of operations:

copy

use records
db.addUser("<username>", "<password>", true)

Replace <username> and <password> with the credentials for this user.

Administrative Access in MongoDB

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

Given the superAdmin user with the password Password123, and access to the admin database.

The following operation in the mongo shell will succeed:

copy

use admin
db.auth("superAdmin", "Password123")

However, the following operation will fail:

copy

use test
db.auth("superAdmin", "Password123")

Note

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.

Authentication on Localhost

The behavior of mongod running with auth, when connecting from a client over the localhost interface (i.e. a client running on the same system as the mongod,) varies slightly between before and after version 2.2.

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 mongod is running with auth then all users connecting over the localhost interface must authenticate, even if there aren’t any users in the admin database.

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 a hash of all user’s passwords. [4]
• if a user has the same password in multiple databases, the hash will be the same on all database. A malicious user could exploit this to gain access on a second database use a different users’ credentials.

As a result, always use unique username and password combinations on for each database.

[4]	Read only users do not have access to the system.users database.

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:

• Security Considerations for Replica Sets
• Sharded Cluster Security Considerations

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:

copy

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):

copy

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:

copy

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

←   Configure Windows netsh Firewall for MongoDB Core MongoDB Operations (CRUD)  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.