Users

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

User Management Interface

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

Note

The first user created in the database should be a user administratorwho has the privileges to manage other users. SeeEnable Access Control.

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

A user is uniquely identified by the user’s name and associatedauthentication database. Starting in MongoDB 4.0.9, a users managed byMongoDB are assigned a unique userId. [1]

Authentication Database

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

A user can have privileges across different databases; that is, a user’sprivileges are not limited to their authentication database. By assigningto the user roles in other databases, a user created in one database canhave permissions to act on other databases. For more information onroles, see Role-Based Access Control.

The user’s name and authentication database serve as a unique identifierfor that user. [1] That is, if two users have the same name but are createdin different databases, they are two separate users. If you intend tohave a single user with permissions on multiple databases, create asingle user with roles in the applicable databases instead of creatingthe user multiple times in different databases.

Authenticate a User

To authenticate as a user, you must provide a username, password, andthe authentication databaseassociated with that user.

To authenticate using the mongo shell, either:

• Use the mongo command-line authentication options(—username,—password, and—authenticationDatabase)when connecting to the mongod ormongos instance, or

• Connect first to the mongod or mongosinstance, and then run the authenticate command or thedb.auth() method against the authentication database.

Important

Authenticating multiple times as different users does not dropthe credentials of previously-authenticated users. This may lead toa connection having more permissions than intended by the user, andcauses operations within alogical session to raise anerror.

For examples of authenticating using a MongoDB driver, see thedriver documentation.

Centralized User Data

Changed in version 2.6.

For users created in MongoDB, MongoDB stores all user information,including name, password, and the user's authenticationdatabase, in the system.users collection in the admindatabase.

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

Sharded Cluster Users

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

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

Shard Local Users

However, some maintenance operations, such as cleanupOrphaned,compact, rs.reconfig(), require direct connections tospecific shards in a sharded cluster. To perform these operations, you mustconnect directly to the shard and authenticate as a _shard local_administrative user.

To create a shard local administrative user, connect directly to the shardand create the user. MongoDB stores shard local users in the admindatabase of the shard itself.

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

Direct connections to a shard should only be for shard-specific maintenance andconfiguration. In general, clients should connect to the sharded clusterthrough the mongos.

Localhost Exception

The localhost exception allows you to enable access control and thencreate the first user in the system. With the localhost exception, afteryou enable access control, connect to the localhost interface and createthe first user in the admin database. The first user must haveprivileges to create other users, such as a user with theuserAdmin or userAdminAnyDatabase role.

Changed in version 3.4: MongoDB 3.4 extended the localhost exception to permit execution of thedb.createRole() method. This method allows users authorizing viaLDAP to create a role inside of MongoDB that maps to a role definedin LDAP. See LDAP Authorization for moreinformation.

Changed in version 3.0: The localhost exception changed so that these connections _only_have access to create the first user on the admindatabase. In previous versions, connections that gained accessusing the localhost exception had unrestricted access to theMongoDB instance.

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

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

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

• Add Users