This article tries to summarize all important concepts of MongoDB authentication in the official documentation. It was written based on MongoDB version 4.0.
Target Audience: software engineers experienced with MongoDB
MongoDB has two kinds of authentication:
MongoDB supports various authentication mechanisms:
In addition, MongoDB Enterprise also provides supports for additional Enterprise Authentication Mechanisms.
Internal Auth is used to authenticate nodes within replica set or sharded clusters for all internal communication.
Enabling internal authentication also enables client authorization (Role-Based Access Control).
There are major two methods for internal auth:
MongoDB can use keyfiles to authenticate communication between MongoDB nodes.
The contents of the keyfiles serve as the shared password for the members.
- MongoDB strips whitespace characters (e.g.
x20) for cross-platform convenience.
- On UNIX systems, the keyfile must not have group or world permissions.
Keyfiles use SCRAM challenge and response authentication mechanism.
Enable Keyfiles Authentication
Further reads for operational guide:
- Deploy New Replica Set With Keyfile Access Control
- Enforce Keyfile Access Control in a Replica Set
- Enforce Keyfile Access Control in a Replica Set without Downtime
SCRAM stands for Salted Challenge Response Authentication Mechanism.
This article explains Challenge Response Authentication.
This article explains Salted Salted Challenge Response Authentication Mechanism.
MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection.
Overall, x.509 Authentication can be used in two ways:
- Member certificate authentication: internal authentication, used to verify membership
- Client certificate authentication: authenticate various MongoDB clients
Member Certificate Requirements
The member (node) certificate, used for internal authentication to verify membership, must follow certain requirements.
To specify x.509 for member certificate (internal) authentication, in addition to other TLS/SSL configurations appropriate for your deployment, for each member of the replica set or sharded cluster, include either:
net.ssl.clusterFileif using a config file, or
--sslClusterFilecommand line options.
Client Certificate Configuration
Further read: Member Certificate and PEMKeyFile
Specify Authentication Mechanism
There are three ways to specify authentication mechanism:
mongod --setParameter authenticationMechanisms=PLAIN,SCRAM-SHA-256 --auth
- Clients can specify the authentication mechanism in the
- For the
mongoshell and the MongoDB tools, you can also specify the authentication mechanism from the command line.
To authenticate a client (mongo shell, mongo client driver etc), you must add a corresponding user to MongoDB.
When adding a user, you can assign roles to the user in order to grant privileges.
DB Administration Roles
Cluster Administration Roles
Backup and Restoration Roles
All-DB roles are available on the
admin database and provide privileges which apply to all databases except
Collection-Level Access Control
Administrators can implement collection-level access control through user-defined roles.
When adding a user, you create the user in a specific database. This database is the authentication database for the user.
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.
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.
Authenticate a User
To authenticate as a user, you must provide a username, password, and the authentication database associated with that user.
Centralized User Data
Do not access this collection directly but instead use the user management commands.
Sharded Cluster User
The localhost exception allows you to enable access control and then create the first user in the system.
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.