Users¶

On this page

To authenticate a client in MongoDB, you must add a corresponding user to MongoDB.

User Management Interface¶

To add a user, MongoDB provides the db.createUser() method. When adding a user, you can assign roles to the user in order to grant privileges.

Note

The first user created in the database should be a user administrator who has the privileges to manage other users. See Enable Auth.

You can also update existing users, such as to change password and grant or revoke roles. For a full list of user management methods, see User Management.

Authentication Database¶

When adding a user, you create the user in a specific database. This database is the authentication database for the user.

A user can have privileges across different databases; i.e. a user’s privileges are not limited to the authentication database. By assigning to the user roles in other databases, a user created in one database can have permissions to act on other databases. For more information on roles, see Role-Based Access Control.

The user’s name and authentication database serve as a unique identifier for that user. That is, if two users have the same name but are created in different databases, they are two separate users. If you intend to have a single user with permissions on multiple databases, create a single user with roles in the applicable databases instead of creating the user multiple times in different databases.

Authenticate a User¶

To authenticate a user, either

Use the command line authentication options (e.g. -u, -p, --authenticationDatabase) when connecting to the mongod or mongos instance, or
Connect first to the mongod or mongos instance, and then run the authenticate command or the db.auth() method against the authentication database.

To authenticate, the client must authenticate the user against the user’s authentication database.

For instance, if using the mongo shell as a client, you can specify the authentication database for the user with the --authenticationDatabase option.

Centralized User Data¶

Changed in version 2.6.

MongoDB stores all user information, including name, password, and the user's authentication database, in the system.users collection in the admin database.

Do not access this collection directly but instead use the user management commands.

Sharded Cluster Users¶

To create users for a sharded cluster, connect to the mongos instance and add the users. Clients then authenticate these users through the mongos instances.

Changed in version 2.6: MongoDB stores these sharded cluster user data in the admin database of the config servers. Previously, the credentials for authenticating to a database on a sharded cluster resided on the primary shard for that database.

Shard Local Users¶

However, some maintenance operations, such as cleanupOrphaned, compact, rs.reconfig(), require direct connections to specific shards in a sharded cluster. To perform these operations, you must connect directly to the shard and authenticate as a shard local administrative user.

To create a shard local administrative user, connect directly to the shard and create the user. MongoDB stores shard local users in the admin database of the shard itself.

These shard local users are completely independent from the users added to the sharded cluster via mongos. Shard local users are local to the shard and are inaccessible by mongos.

Direct connections to a shard should only be for shard-specific maintenance and configuration. In general, clients should connect to the sharded cluster through the mongos.

Localhost Exception¶

The localhost exception allows you to enable access control and then create the first user in the system. With the localhost exception, after you enable access control, connect to the localhost interface and create the first user in the admin database. The first user must have privileges to create other users, such as a user with the userAdmin or userAdminAnyDatabase role.

Changed in version 3.4: MongoDB 3.4 extended the localhost exception to permit execution of the db.createRole() method. This method allows users authorizing via LDAP to create a role inside of MongoDB that maps to a role defined in LDAP. See LDAP Authorization for more information.

Changed in version 3.0: The localhost exception changed so that these connections only have access to create the first user on the admin database. In previous versions, connections that gained access using the localhost exception had unrestricted access to the MongoDB instance.

The localhost exception applies only when there are no users created in the MongoDB instance.

In the case of a sharded cluster, the localhost exception applies to each shard individually as well as to the cluster as a whole. Once you create a sharded cluster and add a user administrator through the mongos instance, you must still prevent unauthorized access to the individual shards. Follow one of the following steps for each shard in your cluster:

Create an administrative user, or
Disable the localhost exception at startup. To disable the localhost exception, set the enableLocalhostAuthBypass parameter to 0.

← Authentication Add Users →