Authentication and authorization

Authentication answers "who is this client?"; authorization answers "is this client allowed to do this?". The implementation lives at src/mongo/db/auth/ plus cryptographic primitives in src/mongo/crypto/.

Purpose

The auth subsystem handles:

• SCRAM (default) — password-based challenge/response.
• x.509 — TLS-certificate-based authentication.
• Kerberos / GSSAPI — enterprise environments.
• LDAP — pluggable LDAP authorization (enterprise).
• AWS IAM / OIDC — cloud-friendly external providers.
• Internal cluster auth — shard ↔ shard and shard ↔ config-server mTLS or keyfile-based auth.
• Role-based access control (RBAC) — fine-grained per-action, per-resource permissions.
• Audit — tap point for SOC2/SOX compliance.

Authentication

mongod/mongos advertise their supported mechanisms in hello.saslSupportedMechs. Drivers pick one and run a SASL handshake (saslStart/saslContinue):

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: hello
    Server-->>Client: saslSupportedMechs: [SCRAM-SHA-256, ...]
    Client->>Server: saslStart(mechanism, payload_1)
    Server->>Client: saslContinue(payload_2)
    Client->>Server: saslContinue(payload_3)
    Server-->>Client: ok

The mechanism implementations live under src/mongo/db/auth/ (e.g. sasl_scram*.cpp) and src/mongo/client/ for the client-side. The crypto primitives — SHA, HMAC, AES — are in src/mongo/crypto/.

RBAC

After authentication, the server attaches an AuthorizationSession to the Client. Every command goes through Command::checkAuthForOperation, which consults the session's roles. A role is a named bundle of privileges (action × resource pattern). The schema:

• admin.system.users — users.
• admin.system.roles — custom roles.
• Built-in roles: read, readWrite, dbAdmin, clusterAdmin, root, …

The auth catalog is loaded from these collections at startup and reloaded when users/roles change. Implementation: src/mongo/db/auth/authorization_manager.cpp, authorization_session.cpp.

Keys and TLS

Keys live in:

• /etc/mongo.keyfile — shared-secret keyfile used for cluster auth.
• TLS certificates — configured via --tlsCertificateKeyFile. Server-to-server traffic also uses TLS (or keyfile as a fallback in older deployments).

Crypto operations go through src/mongo/crypto/ which wraps OpenSSL (or Apple/Microsoft equivalents on those platforms). The wrapper is intentionally narrow — most callers depend only on SHA{1,256,512}::hmac() and AES_256_* helpers.

Queryable Encryption (FLE2)

Beyond password and certificate authentication, the server supports client-side field-level encryption and Queryable Encryption (FLE2) — schemes where the data itself is encrypted with keys the server cannot read but where the server can still answer equality, range, or prefix queries on encrypted ciphertext. The implementation is in src/mongo/crypto/, src/mongo/db/query/fle/, and many IDL files for the encryption schema definition. The user-facing crypto-shared library mongocryptd shares this code.

Internal cluster auth

mongod/mongos instances authenticate to each other using either:

• A shared keyfile (older deployments).
• Member x.509 certificates with internal cluster identity (modern).

The cluster auth mode is set at startup and exposed via setClusterAuthMode.

Audit

The audit subsystem (src/mongo/db/audit*) writes structured records for security-relevant events:

• Authentication success/failure.
• Authorization failures.
• Role and privilege changes.
• Cluster topology changes.

The destination is configurable (file, syslog) via --auditDestination. The interface is intentionally pluggable so the enterprise edition can swap in additional sinks.

Key source files

File	Purpose
src/mongo/db/auth/authorization_manager.cpp	Loads and caches user/role definitions.
src/mongo/db/auth/authorization_session.cpp	Per-Client auth state.
src/mongo/db/auth/sasl_scram*.cpp	SCRAM mechanism.
src/mongo/db/auth/sasl_x509*.cpp	x.509 mechanism.
src/mongo/db/audit_interface.h	Pluggable audit interface.
src/mongo/db/audit.cpp	Default file/syslog audit implementation.
src/mongo/crypto/	Crypto primitives (SHA/HMAC/AES, OpenSSL wrappers).
src/mongo/db/query/fle/	Queryable Encryption query rewrites.

Integration points

• The transport layer runs the SASL handshake during connection setup.
• The command framework consults the AuthorizationSession for every command.
• Sharding — cluster auth runs between every shard pair.
• Replication — replica-set internal traffic is authenticated.

Entry points for modification

New auth mechanisms add a SASL handler under src/mongo/db/auth/. New built-in roles are added in src/mongo/db/auth/builtin_roles.cpp. Custom audit sinks plug into audit_interface.h. RBAC behavior is exhaustively tested in src/mongo/db/auth/*_test.cpp and in the auth* resmoke suites.