MongoDB Authentication

Introduction

Authentication is the process of verifying the identity of a client attempting to connect to a MongoDB database. In a production environment, all MongoDB deployments should enforce authentication to ensure that only authorized users can access your data.

MongoDB provides several authentication mechanisms that allow you to verify client identities and restrict database access based on user credentials. Properly configured authentication is a foundational element of a secure MongoDB deployment, working alongside authorization, encryption, and other security controls.

In this guide, you'll learn how to:

Set up and manage MongoDB users and authentication
Configure different authentication mechanisms
Implement best practices for securing your MongoDB deployment
Troubleshoot common authentication issues

Why Authentication Matters

Without authentication:

Anyone with network access to your MongoDB server can connect to your database
Unauthorized users can read, modify, or delete your data
Your database could be vulnerable to malicious attacks

Consider this scenario:

# Without authentication - anyone can connect
$ mongosh --host mongodb://your-server:27017
MongoDB shell version v6.0.6
connecting to: mongodb://your-server:27017/
> show dbs
admin     0.000GB
config    0.000GB
myDb      1.234GB  # All your data is accessible!

Authentication Methods in MongoDB

MongoDB supports several authentication mechanisms to accommodate different security requirements and integration scenarios:

SCRAM (Salted Challenge Response Authentication Mechanism) - The default and recommended mechanism
X.509 Certificate Authentication
LDAP Authentication (MongoDB Enterprise only)
Kerberos Authentication (MongoDB Enterprise only)

SCRAM Authentication

SCRAM is MongoDB's default authentication mechanism. It provides secure password-based authentication using challenge-response and salted passwords to protect credentials.

MongoDB supports two SCRAM mechanisms:

SCRAM-SHA-1
SCRAM-SHA-256 (more secure, recommended)

Enabling Authentication

Method 1: Starting MongoDB with Authentication

You can enable authentication when starting the MongoDB server:

bash
# Start mongod with authentication enabled
mongod --auth --dbpath /data/db

Or in your configuration file (mongod.conf):

yaml
security:
  authorization: enabled

Then start MongoDB using the config file:

bash
mongod --config /path/to/mongod.conf

Method 2: Creating the First User in the Admin Database

If you're starting with a fresh MongoDB installation without authentication:

Start MongoDB without authentication
Connect to MongoDB using the mongo shell
Create an admin user
Restart MongoDB with authentication enabled

Here's how it works:

javascript
// Connect to MongoDB without authentication
$ mongosh

// Switch to admin database
> use admin

// Create administrator user
> db.createUser({
  user: "adminUser",
  pwd: "securePassword123",  // Use a strong password!
  roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
})

Output:

Successfully added user: {
  "user": "adminUser",
  "roles": [ { "role": "userAdminAnyDatabase", "db": "admin" } ]
}

Now restart MongoDB with authentication enabled.

User Management

Creating Users

To create a user for a specific database:

javascript
// Switch to the database where you want to create the user
> use myDatabase

// Create a user with specific permissions for this database
> db.createUser({
  user: "appUser",
  pwd: "userPassword456",
  roles: [
    { role: "readWrite", db: "myDatabase" },
    { role: "read", db: "analytics" }
  ]
})

Output:

Successfully added user: {
  "user": "appUser",
  "roles": [
    { "role": "readWrite", "db": "myDatabase" },
    { "role": "read", "db": "analytics" }
  ]
}

Built-in Roles

MongoDB provides several built-in roles for common use cases:

Database User Roles: read, readWrite
Database Administration Roles: dbAdmin, dbOwner, userAdmin
Cluster Administration Roles: clusterAdmin, clusterManager, clusterMonitor, hostManager
Backup/Restore Roles: backup, restore
Super User Roles: root

For example, to create a read-only user:

javascript
> use reporting
> db.createUser({
  user: "reportReader",
  pwd: "reader123",
  roles: [{ role: "read", db: "reporting" }]
})

Managing Existing Users

You can update user roles, change passwords, or remove users as needed:

javascript
// Update user roles
> db.updateUser("appUser", {
  roles: [
    { role: "readWrite", db: "myDatabase" },
    { role: "readWrite", db: "analytics" }
  ]
})

// Change a user's password
> db.changeUserPassword("appUser", "newSecurePassword789")

// Remove a user
> db.dropUser("oldUser")

Connecting with Authentication

Once authentication is enabled, you must provide credentials when connecting to MongoDB:

Using the MongoDB Shell

bash
# Connect with username and password
mongosh --host localhost:27017 -u adminUser -p --authenticationDatabase admin

You'll be prompted to enter your password securely.

Using Connection Strings

For applications, use a MongoDB connection string:

javascript
// Node.js example with MongoDB driver
const { MongoClient } = require('mongodb');

// Connection URI with authentication
const uri = "mongodb://appUser:userPassword456@localhost:27017/myDatabase";

// Create a new MongoClient
const client = new MongoClient(uri);

async function run() {
  try {
    // Connect to the MongoDB server
    await client.connect();
    console.log("Connected successfully to MongoDB");
    
    // Get a reference to the database
    const database = client.db('myDatabase');
    const collection = database.collection('documents');
    
    // Perform operations
    const findResult = await collection.find({}).toArray();
    console.log('Found documents:', findResult);
  } finally {
    // Close the connection
    await client.close();
  }
}

run().catch(console.error);

Advanced Authentication Configurations

X.509 Certificate Authentication

For enhanced security, MongoDB supports X.509 certificate-based authentication. This method uses TLS/SSL certificates instead of usernames and passwords.

Basic steps:

Generate certificates for your MongoDB server and clients
Configure MongoDB to use TLS/SSL
Create users that authenticate using certificates

yaml
# mongod.conf
net:
  ssl:
    mode: requireSSL
    PEMKeyFile: /path/to/mongodb.pem
    CAFile: /path/to/ca.pem

security:
  authorization: enabled

To create a user for X.509 authentication:

javascript
db.getSiblingDB("$external").runCommand(
  {
    createUser: "CN=myClient,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry",
    roles: [
      { role: "readWrite", db: "myDatabase" }
    ]
  }
)

To connect using X.509:

bash
mongosh --ssl --sslPEMKeyFile /path/to/client.pem --sslCAFile /path/to/ca.pem --host localhost

Authentication Architecture

The following diagram illustrates how authentication works in MongoDB:

Best Practices for MongoDB Authentication

Always enable authentication in production environments.

Use strong passwords for all database users:

javascript
// Good: Long, complex password with mixed characters
db.createUser({ user: "appUser", pwd: "J8!pQ*2xZ9@sL5&vB", roles: [...] })

// Bad: Short, simple password
db.createUser({ user: "appUser", pwd: "password123", roles: [...] })

Follow the principle of least privilege - give users only the permissions they need:

javascript
// Bad: Giving excessive permissions
db.createUser({ user: "webUser", pwd: "password", roles: ["root"] })

// Good: Limited, specific permissions
db.createUser({ 
  user: "webUser", 
  pwd: "password", 
  roles: [{ role: "readWrite", db: "webApp" }] 
})

Use role-based access control to organize permissions.
Rotate credentials regularly to reduce the risk of compromised accounts.
Enable audit logging to track authentication attempts and user activities.
Use SCRAM-SHA-256 instead of SCRAM-SHA-1 for stronger security.
Implement IP whitelisting to restrict connections to trusted sources.

Troubleshooting Authentication Issues

Common Error Messages

Authentication failed:
```
Error: Authentication failed.
```
Possible solutions:
- Verify username and password
- Check that you're using the correct authentication database
- Ensure the user exists in the specified database
Not authorized:
```
Error: not authorized on admin to execute command { find: "users", ... }
```
Possible solutions:
- Verify the user has the necessary roles for the operation
- Grant additional permissions if needed

Checking Authentication Status

To check if authentication is enabled:

javascript
> db.adminCommand( { getParameter: 1, authenticationMechanisms: 1 } )

Output:

{
  "authenticationMechanisms": [
    "SCRAM-SHA-1",
    "SCRAM-SHA-256"
  ],
  "ok": 1
}

To see the current authenticated user:

javascript
> db.runCommand({ connectionStatus: 1 })

Practical Example: Setting Up Authentication for a Web Application

Let's walk through a complete example of setting up authentication for a web application:

Enable authentication in MongoDB
Create specific users for your application
Configure your application to use authentication

Step 1: Enable Authentication

bash
# Edit your MongoDB configuration file
sudo nano /etc/mongod.conf

# Add or modify the security section
# security:
#   authorization: enabled

# Restart MongoDB
sudo systemctl restart mongod

Step 2: Create Database Users

javascript
// Connect to MongoDB (before restarting with auth enabled)
mongosh

// Create an admin user first
use admin
db.createUser({
  user: "dbAdmin",
  pwd: "admin_strong_password",
  roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
})

// Create an application-specific user
use myWebApp
db.createUser({
  user: "webAppUser",
  pwd: "app_strong_password",
  roles: [ 
    { role: "readWrite", db: "myWebApp" },
    { role: "read", db: "analytics" }
  ]
})

Step 3: Configure Your Application

Here's how you might configure a Node.js application with Express and Mongoose:

javascript
// app.js
const mongoose = require('mongoose');
const express = require('express');
const app = express();

// MongoDB connection with authentication
const mongoUri = 'mongodb://webAppUser:app_strong_password@localhost:27017/myWebApp';

mongoose.connect(mongoUri, {
  useNewUrlParser: true,
  useUnifiedTopology: true
})
.then(() => {
  console.log('Successfully connected to MongoDB');
})
.catch(err => {
  console.error('MongoDB connection error:', err);
});

// Define your schema and models
const userSchema = new mongoose.Schema({
  username: String,
  email: String,
  createdAt: { type: Date, default: Date.now }
});

const User = mongoose.model('User', userSchema);

// Express routes
app.get('/users', async (req, res) => {
  try {
    const users = await User.find({});
    res.json(users);
  } catch (err) {
    res.status(500).send(err.message);
  }
});

// Start server
app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Summary

MongoDB authentication is a critical component of database security that verifies the identity of clients connecting to your database. We've covered:

Why authentication is essential for protecting your MongoDB data
How to enable authentication and create users with appropriate permissions
Different authentication mechanisms available in MongoDB
Best practices for secure authentication configuration
Troubleshooting common authentication issues
A practical example of setting up authentication for a web application

By implementing proper authentication, you create the foundation for a secure MongoDB deployment that protects your data from unauthorized access.

Additional Resources

Practice Exercises

Set up a local MongoDB instance with authentication enabled and create users with different permission levels.
Configure a simple application to connect to your authenticated MongoDB instance.
Implement X.509 certificate authentication for a development environment.
Create a script that audits user permissions in your MongoDB database and reports any overprivileged accounts.
Test authentication failures and implement proper error handling in an application.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

Why Authentication Matters​

Authentication Methods in MongoDB​

SCRAM Authentication​

Enabling Authentication​

Method 1: Starting MongoDB with Authentication​

Method 2: Creating the First User in the Admin Database​

User Management​

Creating Users​

Built-in Roles​

Managing Existing Users​

Connecting with Authentication​

Using the MongoDB Shell​

Using Connection Strings​

Advanced Authentication Configurations​

X.509 Certificate Authentication​

Authentication Architecture​

Best Practices for MongoDB Authentication​

Troubleshooting Authentication Issues​

Common Error Messages​

Checking Authentication Status​

Practical Example: Setting Up Authentication for a Web Application​

Step 1: Enable Authentication​

Step 2: Create Database Users​

Step 3: Configure Your Application​

Summary​

Additional Resources​

Practice Exercises​

Introduction

Why Authentication Matters

Authentication Methods in MongoDB

SCRAM Authentication

Enabling Authentication

Method 1: Starting MongoDB with Authentication

Method 2: Creating the First User in the Admin Database

User Management

Creating Users

Built-in Roles

Managing Existing Users

Connecting with Authentication

Using the MongoDB Shell

Using Connection Strings

Advanced Authentication Configurations

X.509 Certificate Authentication

Authentication Architecture

Best Practices for MongoDB Authentication

Troubleshooting Authentication Issues

Common Error Messages

Checking Authentication Status

Practical Example: Setting Up Authentication for a Web Application

Step 1: Enable Authentication

Step 2: Create Database Users

Step 3: Configure Your Application

Summary

Additional Resources

Practice Exercises