OPTIONS

Authentication

Authentication is the process of verifying the identity of a client. When enabled, MongoDB requires all clients to provide credentials to access MongoDB databases. By default, MongoDB does not require authentication.

MongoDB supports a number of authentication mechanisms, or methods clients can use to validate their identity. These mechanisms allow MongoDB to integrate into existing authentication systems that your environments may use. MongoDB’s default authentication method is a challenge and response mechanism. MongoDB also supports x509 certificate authentication, LDAP proxy authentication, and Kerberos authentication.

With authentication, MongoDB requires authentication for all clients, including connections between all MongoDB components in a deployment. See Authentication Between MongoDB Instances for more information.

Authentication is distinct from authorization, which determines the client’s access to resources and operations.

Authentication Mechanisms and Credential Storage

MongoDB supports multiple authentication mechanisms to fit into existing deployments and use existing authentication infrastructure. To declare a specific authentication mechanism use the authenticationMechanisms parameter. For details, see Enable Client Authentication.

MongoDB represents authentication credentials differently depending on authentication mechanism. This section addresses all available methods and describes how each method stores user credentials.

MONGODB-CR Authentication

MONGODB-CR is a challenge-response mechanism that authenticates users through passwords. MONGODB-CR applies by default when you enable authentication in MongoDB without setting a mechanism in the authenticationMechanisms parameter. You can also explicitly apply MONGODB-CR by setting it as the value of authenticationMechanisms.

When you enable MONGODB-CR authentication using the authorization setting, MongoDB uses the credentials stored in the admin database’s system.users collection.

When you enable MONGODB-CR authentication using the keyFile setting, you must store the key file on each mongod or mongos instance. MongoDB uses the key file as stored on each instance. See Generate a Key File for instructions on generating a key file.

x.509 Certificate Authentication

New in version 2.6.

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

Instead of usernames and passwords, clients can use certificates to authenticate to servers.

Instead of key files, MongoDB instances can use certificates to authenticate to sharded clusters and replica sets.

When used to verify membership in a sharded cluster or replica set, an x.509 certificate must have certain properties, as described in Use x.509 for Replica Set/Sharded Cluster Member Authentication.

For more information, see Authenticate with x.509 Certificate.

Kerberos Authentication

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

To use MongoDB with Kerberos, you must have a properly configured Kerberos deployment and the ability to generate valid keytab files.

When you use MongoDB with Kerberos, you must store a keytab file on each mongod and mongos instance. Transmit keytab files only over secure channels.

You must create corresponding user credentials in the system.users collection on the admin database.

For more information, see Deploy MongoDB with Kerberos Support on Linux.

LDAP Proxy Authority Authentication

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

MongoDB Enterprise for Windows does not include LDAP support for authentication.

MongoDB does not support LDAP authentication in mixed sharded cluster deployments that contain both version 2.4 and version 2.6 shards. To upgrade to 2.6, see Upgrade MongoDB to 2.6 for upgrade instructions.

Authentication Options

Clients can authenticate using the Challenge Response, x.509, LDAP Proxy and Kerberos methods.

MongoDB can use the keyFile and x.509 methods to authenticate members of a single MongoDB deployment to each other.

Authentication Behavior

Localhost Exception

The localhost exception allows you to enable authentication 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 user documents in the admin database of a MongoDB instance.

If you use the localhost exception when deploying a new MongoDB system, the first user created must be an administrator who has privileges to create other users, such as a user with the userAdmin or userAdminAnyDatabase role. See Enable Client Authentication and Create a User Administrator for more information.

In the case of a sharded cluster, the localhost exception applies to the cluster as a whole when no user exists in the cluster’s admin database, which exists on the config servers and clients access via mongos instances. The localhost exception applies separately on each shard according to whether a user exists in the shard’s admin database.

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.

Client Authentication

Each client connection should authenticate as exactly one user. If a client authenticates to a database as one user and later authenticates on the same database as a different user, the second authentication invalidates the first. Clients may be authenticated to multiple databases at the same time.

MongoDB stores all user information, including credentials and authorization information, for a MongoDB instance in the system.users collection in the admin database.

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

Authentication Between MongoDB Instances

Replica sets and sharded clusters require authentication between MongoDB instances. The default mechanism for authentication between MongoDB instances is the keyFile setting. The key file serves as a shared password. The content of the key file is arbitrary but must be the same on all mongod and mongos instances that connect to each other.

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.

Authentication on Sharded Clusters

In a sharded cluster, you can authenticate to the cluster as a whole, to a specific database on the cluster, or to a given shard. This section describes how to authenticate to each and where the credentials for authenticating to each are stored.

To authenticate to a sharded cluster, connect and authenticate to the mongos instance. The credentials all users of a sharded cluster reside on the admin databases of the config servers.

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

To perform maintenance operations that require direct connections to specific shards in a sharded cluster, (e.g. cleanupOrphaned, compact, rs.reconfig()) you must create shard local administrative users for each shard. The credentials for these users reside in the admin database of the shard.

For additional information, see Enable Authentication in a Sharded Cluster.