MongoDB is a modern general purpose database that often involves highly sensitive and mission-critical data. Authentication -- the process of verifying the identity of a user -- is therefore one of the most important and central features of MongoDB.
The main purposes of authentication are:
MongoDB Atlas comes with built-in TLS and the latest authentication abilities, like SCRAM, X.509, AWS IAM, and LDAP integrations. It allows an easy UI or API setup.
To secure your deployments, you must apply at least one of the following mechanisms.
Each of these mechanisms has its benefits and use cases.
SCRAM (Default)
SCRAM, which is also known as Salted Challenge Response Authentication Mechanism, adheres to the best practices set out in RFC 5802, which defines standards for authenticating users with a challenge-response mechanism. It is commonly referred to as username/password authentication and can use SHA-1 or SHA-256 algorithms.
x.509 Certificate Authentication
MongoDB supports X.509 certificate authentication for use with a secure TLS connection. The X.509 certificate allows clients to authenticate to servers with certificates rather than with a username and password.
LDAP Proxy Authentication (Only for MongoDB Enterprise and Atlas)
MongoDB Enterprise supports federated SSO authentication of users. This allows administrators to configure a MongoDB cluster to authenticate users by proxying authentication requests to a specified LDAP service.
Kerberos Authentication (Only for MongoDB Enterprise)
MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an IETF (RFC 4120) standard authentication protocol for large client/server systems.
MongoDB Atlas requires any user connecting to the cluster to be authenticated via one of the available mechanisms.
If you wish to add more mechanisms, you need to create database users with the additional mechanism (SCRAM, X.509, AWS IAM, or LDAP).
With a self-managed deployment, you need the following guide to add the needed configuration and users to your deployment.
To enable authentication in MongoDB, we first need to create an administrator account.
Connect to the server using the mongo shell from the server itself.
$ mongo mongodb://localhost:<port>Note: The port is usually set to 27017.
Create an administrator in the admin database with a userAdminAnyDatabase role. This role provides the ability to create and modify roles and users on the current database except local and config.
MongoDB Authorization grants access to data and commands through role-based authorization. In MongoDB Authorization, Privilege is either specified explicitly in the role or inherited from another role, or both. MongoDB allows us to create new user roles for particular databases if we think that the existing built-in roles to control access to a MongoDB system do not describe the set of desired privileges. In addition, you can also create Superuser roles that provide either direct or indirect system-wide superuser access.
In the following example, we will create an Admin user with myNewPassword as a password.
> use admin
> db.createUser(
{
user: "Admin",
pwd: "myNewPassword",
roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
}
)Ctrl+D).Locate the following code in the mongod configuration file (/etc/mongod.conf).
security:
authorization: "disabled"Change authorization disabled to enabled and save the file.
security:
authorization: "enabled"Restart MongoDB using the following code.
sudo service mongodb restartOnce this is complete, all the clients trying to connect to this server must authenticate the user with SCRAM default authentication mechanism.
To authenticate Atlas users, please follow the connection instructions on your cluster connect dialog.
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:
Connect first to the MongoDB or mongos instance.
$ mongo mongodb://<host>:<port>Run the authenticate command or the db.auth() method against the authentication database.
> db.auth("Admin", "myNewPassword","SCRAM-SHA-1",false)Note: db.auth() returns 0 when authentication is not successful, and 1 when the operation is successful.
Or:
Connect and authenticate in one single step. This step is not recommended because it will leave your credentials visible in your terminal history, which can be exploited by any program in your computer. We can use an environment variable to hide our password:
mongo "mongodb://Admin:${DBPASSWORD}@<host>:<port>/admin?authSource=admin"MongoDB Atlas allows creating users via the UI or API as well as adding built-in roles or creating custom roles. There are some limitations to the number of users per project. Those may be extended only by contacting MongoDB Atlas support.
When you self-manage the database, you can use the db.createUser() method to create a user in the authentication database. Administrators can assign any built-in or user-defined roles to the new user. Although authentication is strongly coupled with authorization, they are not the same and each requires a deeper consideration when designing your database security.
Note: A user’s credentials will be stored in one authentication database. The user can also have privileges across multiple different databases. By assigning to the user roles in other databases, a user created in one database can have permission to act on other databases.
In the following code excerpt, we are trying to add a new user justAUser to the demo database. This new user will also get a readWrite role in the demo database. We will also give the user a read role in the finances database.
use demo
db.createUser(
{
user: "justAUser",
pwd: passwordPrompt(), // or cleartext password
roles: [ { role: "readWrite", db: "demo" },
{ role: "read", db: "finances" } ]
}
)When your authentication fails, it's important to understand the root cause of the failure. MongoDB Atlas provides a detailed authentication and connection troubleshooting page.
Let's show some possible failures:
Wrong username/password, resulting in Error: Authentication failed..
{"t":{"$date":"2021-05-03T10:30:18.099+03:00"},"s":"I", "c":"ACCESS", "id":20249, "ctx":"conn11","msg":"Authentication failed","attr":{"mechanism":"SCRAM-SHA-1","principalName":"user","authenticationDatabase":"admin","client":"127.0.0.1:62355","result":"AuthenticationFailed: SCRAM authentication failed, storedKey mismatch"}}Wrong authentication database, resulting in Error: Authentication failed..
{"t":{"$date":"2021-05-03T10:29:24.324+03:00"},"s":"I", "c":"ACCESS", "id":20249, "ctx":"conn10","msg":"Authentication failed","attr":{"mechanism":"SCRAM-SHA-1","principalName":"user","authenticationDatabase":"test","client":"127.0.0.1:62353","result":"UserNotFound: Could not find user \"user\" for db \"test\""}}MongoDB Atlas and MongoDB Server provide a variety of authentication mechanisms that allow users to secure their deployment, from a simple username/password authentication to a full enterprise-grade authentication mechanism, like LDAP and Kerberos.
It's important to familiarize yourself with these mechanisms and make sure you secure your data properly.
atlasAdmin role.db.getUsers() command. However, the cleartext password is never stored in the database. Therefore, you can only change it by running db.changeUserPassword(<user>,<newPassword>) . In Atlas, this can be done via the Database Users UI or API.