In this tutorial, we will cover the steps to set up SCRAM (Salted Challenge Response Authentication Mechanism) for client authentication on a standalone MongoDB instance. SCRAM is a secure authentication mechanism that provides authentication between clients and the MongoDB server.

The tutorial assumes that you have already installed MongoDB on your system.

Step 1: Start MongoDB without Access Control

To start, you need to run the standalone mongod instance without access control. You can do this by opening a terminal and running the following command as the mongod user:

mongod --port 27017 --dbpath /var/lib/mongodb

In this command, --port specifies the port number, and --dbpath specifies the path to the database directory. The tutorial assumes that the /var/lib/mongodb directory exists and is the default dbPath. You may specify a different data directory or port as needed.

When the mongod instance starts, it creates some system files in the /var/lib/mongodb directory. To ensure the system files have the correct ownership, follow this tutorial as the mongod user. If you start mongod as the root user, you will have to update file ownership later.

Step 2: Connect to the MongoDB Instance

Next, you need to connect to the database deployment using mongosh. Open a new terminal and run the following command:

mongosh --port 27017

If you are connecting to a different deployment, specify additional command-line options, such as --host, as needed to connect.

Step 3: Create the User Administrator

You can create the user administrator either before or after enabling access control. If you enable access control before creating any user, MongoDB provides a localhost exception that allows you to create a user administrator in the admin database. Once created, you must authenticate as the user administrator to create additional users.

Using mongosh, switch to the admin database and add the myUserAdmin user with the userAdminAnyDatabase and readWriteAnyDatabase roles:

use admin
db.createUser(
  {
    user: "myUserAdmin",
    pwd: passwordPrompt(), // or cleartext password
    roles: [
      { role: "userAdminAnyDatabase", db: "admin" },
      { role: "readWriteAnyDatabase", db: "admin" }
    ]
  }
)

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string. We recommend using the passwordPrompt() method to avoid the password being visible on your screen and potentially leaking the password to your shell history.

The userAdminAnyDatabase role allows this user to:

• create users
• grant or revoke roles from users
• create or modify custom roles

You can assign your user additional built-in roles or user-defined roles as needed.

The database where you create the user, in this example admin, is the user's authentication database. Although the user needs to authenticate to this database, the user can have roles in other databases. The user's authentication database doesn't limit the user's privileges.

Step 4: Re-start the MongoDB Instance with Access Control

Shut down the mongod instance using mongosh, and issue the following command:

db.adminCommand( { shutdown: 1 } )

Exit mongosh.

Start the mongod with access control enabled. If you start the mongod from the command line, add the --auth command-line option:

mongod --auth --port 27017 --dbpath /var/lib/mongodb

If you start the mongod using a configuration file, add the security.authorization configuration file setting:

security:
    authorization: enabled

Clients that connect to this instance must now authenticate themselves and can only perform actions as determined by their assigned roles.

You can create users either before or after enabling access control. If you enable access control before creating any user, MongoDB provides a localhost exception that allows you to create a user administrator in the admin database. Once created, you must authenticate as the user administrator to create additional users.

Step 5: Connect and Authenticate as the User Administrator

Using mongosh, you can authenticate during or after connection. Start mongosh with the -u <username>, -p, and the --authenticationDatabase <database> command-line options:

mongosh --port 27017  --authenticationDatabase "admin" -u "myUserAdmin" -p

Enter your password when prompted.

Next Steps

You have now set up SCRAM authentication for your MongoDB deployment. To use SCRAM authentication for replica sets or sharded clusters, see Deploy Replica Set With Keyfile Authentication.

Tags: