MongoDB Atlas IAM and RBAC
Parent: MongoDB Atlas · Published reference · snapshot 2026-09-08 · skill mongodb-atlas-expert/references/mongodb-atlas-iam-rbac.md
↓ Facts as markdownall context files
Atlas uses a three-tier identity model: Organization → Project → Database.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Three-Tier Identity Model
- Atlas uses a three-tier identity model: Organization → Project → Database. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#three-tier-identity-model]
SCRAM-SHA-256 (default)
- Username + password. Most compatible. FIPS 140-2 compliant when using SHA-256. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#scram-sha-256-default]
X.509 Certificates
- Client certificate authentication. Two types: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#x509-certificates]
- Atlas-managed: Atlas generates and manages the CA; valid for up to 5 years (configurable) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#x509-certificates]
- Customer-managed (LDAP): Customer operates their own CA; Atlas validates against customer's CA [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#x509-certificates]
AWS IAM (MONGODB-AWS)
- Passwordless auth using AWS credentials (IAM user, role, EC2 instance profile, IRSA, Lambda execution role). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#aws-iam-mongodb-aws]
- Connection string: authMechanism=MONGODB-AWS [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#aws-iam-mongodb-aws]
- Create Atlas database user with username = arn:aws:iam::<account-id>:role/<role-name> or arn:aws:iam::<account-id>:user/<username> [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#aws-iam-mongodb-aws]
OIDC / Workload Identity Federation (GA 2024)
- Workforce (human users) and Workload (apps/services) identity federation. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#oidc-workload-identity-federation-ga-2024]
- Workforce OIDC: Human users SSO into Atlas database access via Entra ID, Okta, Google Workspace, or any OIDC provider. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#oidc-workload-identity-federation-ga-2024]
- Workload OIDC: Applications authenticate without passwords using OIDC tokens from GCP, Azure, AWS, or any OIDC provider. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#oidc-workload-identity-federation-ga-2024]
LDAP (Deprecated in MongoDB 8.0)
- LDAP authentication and authorization supported in MongoDB 4.x–7.x. Deprecated in 8.0. Migrate to OIDC or X.509. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#ldap-deprecated-in-mongodb-80]
Atlas Service Accounts (GA April 2025)
- Replaces legacy Programmatic API Keys for machine-to-machine Atlas API access. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Client ID + Client Secret → OAuth 2.0 client credentials flow → 1-hour bearer tokens [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Scoped at Org or Project level [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Supports Workload Identity Federation (WIF) - replace Client Secret with OIDC tokens from GKE/AKS/EKS/Cloud Run [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Migration from API Keys to Service Accounts: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Create Service Account in Atlas (Org/Project → Access Manager → Service Accounts) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Generate Client ID + Client Secret (show once) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Update IaC/CI env vars: MONGODB_ATLAS_CLIENT_ID + MONGODB_ATLAS_CLIENT_SECRET [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
- Remove old API key after confirming new SA works [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-service-accounts-ga-april-2025]
Programmatic API Keys (Legacy)
- Public key + private key pair using HTTP Digest. Cannot be rotated atomically. Counted as "users" in the project. Will eventually be deprecated. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#programmatic-api-keys-legacy]
- API key IP allowlist: API keys can be restricted to specific IP addresses - important for CI/CD security. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#programmatic-api-keys-legacy]
Workforce Identity Federation (SAML/OIDC)
- Allows organization members to log into the Atlas UI and API using their corporate SSO (Okta, Entra ID, Google Workspace, PingFederate). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#workforce-identity-federation-samloidc]
- SAML: Atlas UI access only. Configure via Organization → Security → Federation Management. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#workforce-identity-federation-samloidc]
- OIDC (Workforce): Atlas database access. Configure in Organization → Security → Workforce Identity Provider. Maps IdP group claims to Atlas project roles. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#workforce-identity-federation-samloidc]
- Group-to-role mapping: Map IdP group Object IDs to Atlas org/project roles. Groups claim must be present in the token. Large group membership (>150 groups on Entra ID) may omit groups claim - filter to relevant groups. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#workforce-identity-federation-samloidc]
Custom Database Roles
- Extend built-in MongoDB roles with collection-level or action-level granularity. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#custom-database-roles]
- Custom roles created at the project level - available across all clusters in the project. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#custom-database-roles]
Atlas Resource Policies (Cedar Guardrails)
- Atlas Resource Policies use Cedar policy language to enforce organization-wide guardrails (GA 2025). Examples: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-resource-policies-cedar-guardrails]
- Restrict cluster creation to specific cloud providers/regions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-resource-policies-cedar-guardrails]
- Require encryption at rest for all clusters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-resource-policies-cedar-guardrails]
- Enforce minimum backup retention [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-resource-policies-cedar-guardrails]
- Applied at the organization level; evaluated before any Atlas API mutation. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#atlas-resource-policies-cedar-guardrails]
Database Auditing
- When available: M10+ clusters only. Not available on M0/Flex. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#database-auditing]
- Configure audit log filter to capture: authenticate, authCheck (authorization decisions), createCollection, dropCollection, createDatabase, dropDatabase. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#database-auditing]
- SIEM integration: Push Atlas audit logs to Datadog, Sumo Logic, S3, or via Atlas Admin API log pull. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#database-auditing]
- Activity Feed: Organization and project-level audit trail of Atlas control-plane actions (cluster creates, user changes, backup events) - accessible even on M0/Flex. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#database-auditing]
Common Debugging Scenarios
- "Authentication failed" for new database user: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Verify user exists in the correct project (users are project-scoped) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Verify the auth database is admin for SCRAM users [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Verify password does not contain special characters needing URL encoding [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Verify IP allowlist includes the client IP [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- "Authorization failed" after auth succeeds: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Check which roles are assigned to the user [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Verify role is scoped to the correct database/collection [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Custom roles: check actions and resources are correct [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- AWS IAM: verify the role ARN matches exactly (account ID + role name) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- OIDC token rejected: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Decode JWT: check iss claim matches Atlas Workload IDP issuer config [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Check aud claim matches Atlas IDP audience field [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
- Check token exp hasn't passed (clock skew > 5 min causes failures) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#common-debugging-scenarios]
References
- Atlas Database Users [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
- Atlas Service Accounts [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
- Workforce Identity Federation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
- Workload Identity Federation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
- Atlas Resource Policies [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
- Database Auditing [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-atlas-iam-rbac/#references]
Where this helps
- Designing passwordless, machine-to-machine authentication for an application running on AWS, GCP, or Azure compute, using AWS IAM or OIDC Workload Identity Federation instead of static database credentials. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Migrating CI/CD and IaC automation off legacy Programmatic API Keys onto Atlas Service Accounts with OAuth 2.0 client credentials. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Rolling out corporate SSO, such as Okta or Entra ID, for human access to both the Atlas UI and the underlying databases via Workforce Identity Federation. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Debugging an "Authorization failed" error after authentication succeeds, which usually traces to role scope, custom-role actions, or, for OIDC, a claims/audience mismatch. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Project ideas
- Migrate a CI/CD pipeline from legacy Programmatic API Keys to an Atlas Service Account using OAuth 2.0 client credentials, and add Workload Identity Federation so no client secret is stored at all. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Design a custom database role that grants collection-level, action-level access narrower than any built-in role, for a service that should only read one collection. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Build an org-wide Atlas Resource Policy (Cedar guardrail) that restricts cluster creation to approved cloud providers/regions and requires encryption at rest. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Set up Workforce OIDC federation so engineers authenticate to database access with their corporate SSO identity instead of a shared SCRAM credential. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Continuing to build new integrations on LDAP authentication, which is deprecated as of MongoDB 8.0 in favor of OIDC or X.509. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Relying on legacy Programmatic API Keys for new automation instead of Service Accounts, when API keys can't be rotated atomically and count as project "users." [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Mapping an OIDC group claim without accounting for large group membership — Entra ID can omit the groups claim entirely above roughly 150 groups, silently breaking group-to-role mapping. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Treating Atlas users and database users as the same identity — they access different planes, control plane vs. data plane, and have to be reasoned about separately. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Database Auditing is only available on M10+ clusters, not on M0 or Flex, so audit-log-based compliance controls can't be applied uniformly across every tier. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- X.509 customer-managed certificates require the customer to operate their own CA, which adds real operational burden compared to Atlas-managed certificates that are valid up to 5 years. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- OIDC token failures are commonly caused by clock skew greater than about 5 minutes between the token issuer and Atlas, which can look like a configuration bug rather than a clock problem. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Custom database roles are created at the project level, so a role designed for one project has to be recreated, not simply shared, in another project. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Atlas Three-Tier Identity Model
- Atlas Organization Roles
- Atlas Project Roles (15 Purpose-Built) (frontier, viability 3.58 / 5)
- Atlas Database Users (frontier, viability 3.58 / 5)
- Atlas Custom Database Roles (frontier, viability 4.08 / 5)
- Atlas Programmatic API Keys (Legacy)
- Atlas AWS IAM Database Auth (frontier, viability 3.95 / 5)
- Atlas X.509 Certificate Auth (frontier, viability 3.75 / 5)
- Atlas LDAPS (Deprecated 8.0)
- Atlas SCRAM-SHA-256 (frontier, viability 3.67 / 5)
- Atlas Database Auditing (frontier, viability 3.65 / 5)
- Atlas Activity Feed
- Atlas Log Push SIEM
- Atlas IdP Group to Role Mapping (frontier, viability 3.88 / 5)
- Atlas Organization Teams
- Atlas Auth Tier Feature Matrix M0 Flex M10 (frontier, viability 4.00 / 5)
- Atlas IAM Compliance Mapping
- Atlas Identity Federation and Resource Policy Boundaries
- Atlas Resource Policies Cedar
Frontier under this node: Atlas AWS IAM Database Auth (3.95), Atlas Auth Tier Feature Matrix M0 Flex M10 (4.00), Atlas Custom Database Roles (4.08), Atlas Database Auditing (3.65), Atlas Database Users (3.58), Atlas IdP Group to Role Mapping (3.88), Atlas Project Roles (15 Purpose-Built) (3.58), Atlas SCRAM-SHA-256 (3.67), Atlas X.509 Certificate Auth (3.75)