Key Concepts in MongoDB Authentication

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

Overview

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

Internal Auth is used to authenticate nodes within replica set or sharded clusters for all internal communication.

NOTE

Enabling internal authentication also enables client authorization (Role-Based Access Control).

There are major two methods for internal auth:

Keyfiles Authentication

MongoDB can use keyfiles to authenticate communication between MongoDB nodes.

The contents of the keyfiles serve as the shared password for the members.

Warning

The content of the keyfile must be the same on all mongod and mongos instances that connect to each other. You must store the keyfile on each member of the replica set or sharded clusters.

Notes

  • MongoDB strips whitespace characters (e.g. x0dx09, and 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

To specify the keyfile, set the security.keyFile setting in the config file or use --keyFile command line option.

Further reads for operational guide:

SCRAM

SCRAM stands for Salted Challenge Response Authentication Mechanism.

This article explains Challenge Response Authentication.

This article explains Salted Salted Challenge Response Authentication Mechanism.

x.509 Authentication

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.

Configuration

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:

Client Certificate Configuration

The mongod and mongos need to specify a PEMKeyFile to prove its identity to clients, either through net.ssl.PEMKeyFile setting in the config file or --sslPEMKeyFile command line option.

Further read: Member Certificate and PEMKeyFile

Specify Authentication Mechanism

There are three ways to specify authentication mechanism:

  1. Set the authenticationMechanisms parameter for mongodand mongos.
  • E.g. mongod --setParameter authenticationMechanisms=PLAIN,SCRAM-SHA-256 --auth
  1. Clients can specify the authentication mechanism in the db.auth() method.
  2. For the mongo shell and the MongoDB tools, you can also specify the authentication mechanism from the command line.

User Auth

To authenticate a client (mongo shell, mongo client driver etc), you must add a corresponding user to MongoDB.

Access Control

When adding a user, you can assign roles to the user in order to grant privileges.

MongoDB provides built-in roles and user-defined roles.

Built-in roles

User Roles

  • read
  • readWrite

DB Administration Roles

Cluster Administration Roles

Backup and Restoration Roles

All-Database Roles

All-DB roles are available on the admin database and provide privileges which apply to all databases except local and config:

Superuser Roles

Internal Role

Collection-Level Access Control

Administrators can implement collection-level access control through user-defined roles

Authentication Database

When adding a user, you create the user in a specific database. This database is the authentication database for the user.

Note

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. 

Note

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

MongoDB stores all user information, including name, password, and the user's authentication database, in the system.users collection in the admin database.

Do not access this collection directly but instead use the user management commands.

Sharded Cluster User

mongos should be used to create users for a sharded cluster. Then, clients authenticate these users through the mongos instances.

Localhost Exception

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. 

Further reads: https://docs.mongodb.com/manual/core/security-users/#localhost-exception