Authentication

Authentication answers "who is connecting?" — MongoDB supports several mechanisms, from simple username/password to certificate-based auth, and self-hosted deployments need auth enabled explicitly (Atlas enables it for you by default).

SCRAM — the Default Mechanism

SCRAM (Salted Challenge Response Authentication Mechanism) is username/password authentication, and is the default for both self-hosted MongoDB and Atlas.

Creating a user with roles at creation time

use admin
db.createUser({
  user: "appUser",
  pwd: passwordPrompt(),   // prompts securely instead of hardcoding
  roles: [
    { role: "readWrite", db: "shop" },
    { role: "read", db: "analytics" }
  ]
})

x.509 Certificate Authentication

Instead of a password, the client presents a TLS certificate signed by a CA the server trusts. Common in environments with strict internal PKI requirements, or where you want to avoid password management entirely.

db.getSiblingDB("$external").createUser({
  user: "CN=appservice,OU=Engineering,O=Acme,L=City,ST=State,C=US",
  roles: [{ role: "readWrite", db: "shop" }]
})

Bash

mongosh --tls \
  --tlsCertificateKeyFile client.pem \
  --tlsCAFile ca.pem \
  --authenticationMechanism MONGODB-X509 \
  --authenticationDatabase '$external'

Authentication via Connection String

Bash

mongodb://appUser:password@host:27017/shop?authSource=admin
mongodb+srv://appUser:password@cluster0.mongodb.net/shop?authSource=admin

The authSource Gotcha

authSource specifies which database the credentials are validated against — it is not necessarily the database you connect to. Users are frequently created against admin (or $external for x.509) but used to access a completely different application database.

Warning

Forgetting authSource=admin in the connection string is one of the most common "auth failed" support tickets — if your user was created via use admin; db.createUser(...), the connection string must include authSource=admin, even though you're connecting to a different working database.

Enabling Auth on Self-Hosted mongod

A freshly installed, self-hosted mongod has authentication disabled by default. Enable it in mongod.conf:

Bash

# mongod.conf
security:
  authorization: enabled

Bash

# Restart mongod for the change to take effect
sudo systemctl restart mongod

# Now every connection (including local mongosh) must authenticate
mongosh -u appUser -p --authenticationDatabase admin

The Localhost Exception

Right after enabling authorization but before any user exists, MongoDB grants a one-time "localhost exception": a connection from localhost may create the very first user (typically with the userAdminAnyDatabase role) without authenticating. Once any user exists, the exception closes automatically.

// Run this once, immediately after enabling authorization, connected
// from localhost — this is the only unauthenticated write allowed
use admin
db.createUser({
  user: "admin",
  pwd: passwordPrompt(),
  roles: [{ role: "userAdminAnyDatabase", db: "admin" }, { role: "readWriteAnyDatabase", db: "admin" }]
})

Tip

Create your first admin user immediately after enabling authorization: enabled — until you do, anyone who can reach the server from localhost can create arbitrary users.

Authentication Mechanisms Summary

Mechanism	Use case
SCRAM-SHA-256	Default username/password auth — use for most application connections
x.509	Certificate-based auth for internal services with existing PKI
LDAP (Enterprise)	Integrate with an existing corporate directory
Kerberos (Enterprise)	Integrate with an existing Kerberos/Active Directory environment
AWS IAM (Atlas)	Authenticate using AWS IAM roles instead of a stored password
OIDC	Authenticate using an external identity provider (Okta, Azure AD, etc.)

Summary

SCRAM (username/password) is the default and most common mechanism — Atlas enables auth automatically.
x.509 lets clients authenticate with a certificate instead of a password.
authSource tells MongoDB where to validate credentials — it is easy to forget and a frequent source of connection failures.
On self-hosted deployments, set security.authorization: enabled in mongod.conf and create your first user immediately via the localhost exception.