Authentication¶

On this page

Client Users
Authentication Mechanisms
Authentication Behavior

Authentication is the process of verifying the identity of a client. When access control, i.e. authorization, is enabled, MongoDB requires all clients to authenticate themselves first in order to determine the access for the client.

Although authentication and authorization are closely connected, authentication is distinct from authorization. Authentication verifies the identity of a user; authorization determines the verified user’s access to resources and operations.

MongoDB supports a number of authentication mechanisms that clients can use to verify their identity. These mechanisms allow MongoDB to integrate into your existing authentication system. See Authentication Mechanisms for details.

In addition to verifying the identity of a client, MongoDB can require members of replica sets and sharded clusters to authenticate their membership to their respective replica set or sharded cluster. See Authentication Between MongoDB Instances for more information.

Client Users¶

To authenticate a client in MongoDB, you must add a corresponding user to MongoDB. When adding a user, you create the user in a specific database. Together, the user’s name and 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. To authenticate, the client must authenticate the user against the user’s database. For instance, if using the mongo shell as a client, you can specify the database for the user with the –authenticationDatabase option.

To add and manage user information, MongoDB provides the db.createUser() method as well as other user management methods. For an example of adding a user to MongoDB, see Add a User to a Database.

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

Authentication Mechanisms¶

MongoDB supports multiple authentication mechanisms. MongoDB’s default authentication method is a challenge and response mechanism (MONGODB-CR). MongoDB also supports x509 certificate authentication, LDAP proxy authentication, and Kerberos authentication.

This section introduces the mechanisms available in MongoDB.

To specify the authentication mechanism to use, see authenticationMechanisms.

`MONGODB-CR` Authentication¶

MONGODB-CR is a challenge-response mechanism that authenticates users through passwords. MONGODB-CR is the default mechanism.

When you use MONGODB-CR authentication, MONGODB-CR verifies the user against the user’s name, password and database. The user’s database is the database where the user was created, and the user’s database and the user’s name together serves to identify the user.

Using key files, you can also use MONGODB-CR authentication for the internal member authentication of replica set members and sharded cluster members. The contents of the key files serve as the shared password for the members. You must store the key file on each mongod or mongos instance for that replica set or sharded cluster. The content of the key file is arbitrary but must be the same on all mongod and mongos instances that connect to each other.

See Generate a Key File for instructions on generating a key file and turning on key file authentication for members.

x.509 Certificate Authentication¶

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection.

To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords. See Client x.509 Certificate for more information.

For membership authentication, members of sharded clusters and replica sets can use x.509 certificates instead of key files. See Use x.509 Certificate for Membership Authentication for more information.

Kerberos Authentication¶

MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server systems.

To use MongoDB with Kerberos, you must have a properly configured Kerberos deployment, configured Kerberos service principals for MongoDB, and added Kerberos user principal to MongoDB.

See Kerberos Authentication for more information on Kerberos and MongoDB. To configure MongoDB to use Kerberos authentication, see Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows.

LDAP Proxy Authority Authentication¶

MongoDB Enterprise supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. See Authenticate Using SASL and LDAP with OpenLDAP and Authenticate Using SASL and LDAP with ActiveDirectory.

MongoDB Enterprise for Windows does not include LDAP support for authentication. However, MongoDB Enterprise for Linux supports using LDAP authentication with an ActiveDirectory server.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards.

Authentication Behavior¶

Client Authentication¶

Clients can authenticate using the challenge and response, x.509, LDAP Proxy and Kerberos mechanisms.

Each client connection should authenticate as exactly one user. If a client authenticates to a database as one user and later authenticates to the same database as a different user, the second authentication invalidates the first. While clients can authenticate as multiple users if the users are defined on different databases, we recommend authenticating as one user at a time, providing the user with appropriate privileges on the databases required by the user.

See Authenticate to a MongoDB Instance or Cluster for more information.

Authentication Between MongoDB Instances¶

You can authenticate members of replica sets and sharded clusters. To authenticate members of a single MongoDB deployment to each other, MongoDB can use the keyFile and x.509 mechanisms. Using keyFile authentication for members also enables authorization.

Always run replica sets and sharded clusters in a trusted networking environment. Ensure that the network permits only trusted traffic to reach each mongod and mongos instance.

Use your environment’s firewall and network routing to ensure that traffic only from clients and other members can reach your mongod and mongos instances. If needed, use virtual private networks (VPNs) to ensure secure connections over wide area networks (WANs).

Always ensure that:

Your network configuration will allow every member of the replica set or sharded cluster to contact every other member.
If you use MongoDB’s authentication system to limit access to your infrastructure, ensure that you configure a keyFile on all members to permit authentication.

See Generate a Key File for instructions on generating a key file and turning on key file authentication for members. For an example of using key files for sharded cluster authentication, see Enable Authentication in a Sharded Cluster.

Authentication on Sharded Clusters¶

In sharded clusters, applications authenticate to directly to mongos instances, using credentials stored in the admin database of the config servers. The shards in the sharded cluster also have credentials, and clients can authenticate directly to the shards to perform maintenance directly on the shards. In general, applications and clients should connect to the sharded cluster through the mongos.

Changed in version 2.6: Previously, the credentials for authenticating to a database on a cluster resided on the primary shard for that database.

Some maintenance operations, such as cleanupOrphaned, compact, rs.reconfig(), require direct connections to specific shards in a sharded cluster. To perform these operations with authentication enabled, 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.

Localhost Exception¶

The localhost exception allows you to enable authorization before creating the first user in the system. When active, the localhost exception allows all connections from the localhost interface to have full access to that instance. The exception applies only when there are no users created in the MongoDB instance.

If you use the localhost exception when deploying a new MongoDB system, the first user you create must be in the admin database with privileges to create other users, such as a user with the userAdmin or userAdminAnyDatabase role. See Enable Client Access Control and Create a User Administrator for more information.

In the case of a sharded cluster, the localhost exception can apply to the cluster as a whole or separately to each shard. The localhost exception can apply to the cluster as a whole if there are no user information stored on the config servers and clients access via mongos instances.

The localhost exception can apply separately to each shard if there is no user information stored on the shard itself and clients connect to the shard directly.

To prevent unauthorized access to a cluster’s shards, you must either create an administrator on each shard or disable the localhost exception. To disable the localhost exception, use setParameter to set the enableLocalhostAuthBypass parameter to 0 during startup.

← Security Concepts Authorization →