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 Access Control.
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.
A user is uniquely identified by the user's name and associated
authentication database. Starting in MongoDB 4.0.9, a users managed by
MongoDB are assigned a unique userId
. [1]
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; that is, a user's privileges are not limited to their 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. [1] 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.
[1] | (1, 2) Starting in version 4.0.9, MongoDB associates a user with a unique
userId upon creation in MongoDB.LDAP managed users created on the LDAP server
do not have an associated document in the system.users collection, and hence, do not
have a userId field associated with them. |
Authenticate a User
To authenticate as a user, you must provide a username, password, and the authentication database associated with that user.
To authenticate using the mongo
shell, either:
Use the
mongo
command-line authentication options (--username
,--password
, and--authenticationDatabase
) when connecting to themongod
ormongos
instance, orConnect first to the
mongod
ormongos
instance, and then run theauthenticate
command or thedb.auth()
method against the authentication database.Important
Authenticating multiple times as different users does not drop the credentials of previously-authenticated users. This may lead to a connection having more permissions than intended by the user, and causes operations within a logical session to raise an error.
For examples of authenticating using a MongoDB driver, see the driver documentation.
Centralized User Data
For users created in MongoDB, 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.
In sharded clusters, MongoDB stores user configuration data in the
admin
database of the config servers.
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.
Connections using the localhost exception only have access to create
the first user on the admin
database.
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.
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 to0
.