Atlas Federated Authentication

MongoDB Atlas Federated Authentication

Overview

Atlas Federated Authentication implements Federated Identity Management (FIM) at the Atlas organization layer. Your identity provider (IdP) manages all credentials; Atlas acts as the SAML 2.0 Service Provider (SP). When a user logs in, their browser exchanges SAML assertions with the IdP instead of submitting MongoDB credentials directly.

Scope of federation: One federation application can span multiple Atlas organizations under a single IdP, unified via the Federation Management Console (FMC). Federation covers Atlas UI access only — it does not control database-level user authentication. For OIDC workforce federation, X.509, SCRAM, or LDAP database auth, see [[mongodb-atlas-iam-rbac]].

SAML vs OIDC disambiguation: This skill covers SAML 2.0 federation for Atlas UI login (org-level SSO). If the question is about authenticating application workloads to the Atlas database via an IdP, that is Workload/Workforce Identity Federation (OIDC) — a different feature documented in [[mongodb-atlas-iam-rbac]].

Guardrail: Use only the API endpoint paths, attribute names, and URLs explicitly stated in this skill. Do not extrapolate or invent Atlas Admin API paths — verify any path not listed here against the Atlas Admin API reference before use.

1. How Atlas Federated Authentication Works

Architecture

The SP-initiated SAML flow: User visits cloud.mongodb.com → enters email → Atlas matches domain to IdP → sends AuthnRequest → IdP authenticates → issues signed SAML Response → Atlas validates assertion (signature, audience, timestamps) → extracts NameID/firstName/lastName/memberOf → creates/updates account (JIT) → applies role mappings → user lands in org.

Key concepts

SP-initiated (most common) vs IdP-initiated (tile click in My Apps; requires RelayState = Atlas Login URL). Both flows supported. Federation disables direct Atlas credential login and Atlas-managed 2FA for users on mapped domains — configure MFA at IdP level.

2. Supported Identity Providers

Full tutorials: Okta, Microsoft Entra ID (Azure AD), Google Workspace, PingOne. Any SAML 2.0 IdP works (JumpCloud, OneLogin, Auth0, custom).

Okta + Atlas (key steps)

1. Create SAML 2.0 app in Okta with placeholder SSO URL/Audience URI
2. Download Okta signing cert → convert to PEM (openssl x509)
3. Create IdP in Atlas FMC with placeholder values + PEM cert; Request Binding: HTTP POST, Algorithm: SHA-256
4. Download Atlas metadata XML → update Okta SSO URL and Audience URI with real values
5. Attribute Statements: firstName=user.firstName, lastName=user.lastName; Group Attribute Statement: memberOf (Matches regex .*)
6. Update Atlas FMC IdP with real Okta Issuer URI and SSO URL

Microsoft Entra ID + Atlas (key steps)

1. Add “MongoDB Atlas - SSO” from Entra gallery
2. Set temporary SAML Identifier: https://www.okta.com/saml2/service-provider/MongoDBCloud (replaced in step 5)
3. Download Certificate (Base64)
4. Configure claims: email=user.userprincipalname, firstName=user.givenname, lastName=user.surname
5. Group claim: Security groups, Source=Group Id, customize name to “memberOf”, Namespace blank, uncheck “Emit groups as role claims”
6. Configure IdP in Atlas FMC with Entra Login URL + Identifier → download Atlas metadata → upload to Entra (sets real ACS URL/Audience URI)
7. JIT enabled by default — no additional action needed

Critical: With Entra ID Group Id source, enter group Object ID (GUID) in Atlas role mapping “Group Name” field, not display name.

3. Connected Organizations

One federation can hold multiple Atlas orgs under one IdP. Each org connects to only one IdP. All orgs share the federation’s domain verification pool. Link via FMC → Link Organizations → Configure Access → Connect Identity Provider. To change IdP: disconnect current first. Domain restriction per org: FMC → Organizations → Restrict Access by Domain (see Section 5).

4. Group-to-Atlas Role Mapping

At login: Atlas reads memberOf from assertion → looks up role mappings for each group in connected orgs → applies ALL matched roles (additive) → if user loses group membership, role removed at next login → if no maps + default role configured, assigns default → if no maps + no default, user has no roles but can still log in.

Add mapping: FMC → Organizations → org → Manage Role Mappings → Create → enter Group Name (exact match, case-sensitive, max 200 chars; use GUID for Entra ID Group Id) → assign org roles → optionally assign project roles.

Default role: FMC → Organizations → org → Default User Role. Typical: Organization Member. Constraint: cannot remove last Organization Owner mapping. When group mappings active, cannot manually edit per-user roles in Access Manager. Role sync is login-time only; SCIM (Section 8) enables real-time sync.

5. Domain Verification

Proves domain ownership before Atlas routes @domain users through IdP.

Method A (DNS TXT Record — recommended): FMC → Add Domain → DNS Record → copy mongodb-site-verification=<32-char-string> → add to DNS → Verify. Propagation: minutes to hours.

Method B (HTML File): Download mongodb-site-verification.html → host at https://host.domain/mongodb-site-verification.html → Verify → DELETE file after verification.

After verification: FMC → Identity Providers → Edit → Associated Domains → select domain → Confirm. Without association, IdP shows as Inactive.

Multiple IdPs per domain: Atlas routes to first configured IdP from web UI; use per-IdP Login URL to reach secondary. Delete domain: disassociate from all IdPs first.

Restrict access by domain (org-level): FMC → Organizations → ellipsis → Restrict Access by Domain → On. New invitations restricted; existing users outside approved domains retain access.

6. Bypass and Breakglass Users

Bypass SAML Mode URL: per-IdP URL allowing Atlas credential login regardless of SSO. Enabled by default. To find: FMC → Identity Providers → click IdP entry → copy Bypass SAML Mode URL (do NOT toggle the switch just to find the URL — toggling changes the state). Disable in production once federation is validated; keep breakglass accounts instead.

Breakglass accounts: Atlas Organization Owner accounts with email domain NOT mapped to any IdP (e.g., @admin.example.com), strong password in secrets manager, Atlas 2FA enabled. Use only during SSO outage.

Federation lockout recovery: Contact MongoDB Support with org ID + proof of ownership. Process is slow — justify maintaining bypass-capable accounts.

Restrict Membership to Federation: FMC → Advanced Settings → Restrict Membership On. Prevents federated users from joining/creating orgs outside the federation. Org Owners can still create orgs (auto-connected).

7. Just-In-Time (JIT) User Provisioning

Atlas auto-creates user account on first successful SAML login. Enabled by default, no configuration needed. Works with all SAML IdPs.

Required assertion attributes (case-sensitive): firstName (String), lastName (String), NameID/Subject (email format). For role mapping (not account creation): memberOf (multi-value string).

Entra ID attribute mapping: email→user.userprincipalname (or user.mail), firstName→user.givenname, lastName→user.surname, memberOf→Group Object IDs or display names.

JIT vs SCIM: JIT creates on first login, no deprovisioning, login-time sync only, zero setup. SCIM provisions proactively, deprovisions on IdP removal, continuous group sync, requires IdP configuration. Enterprise with compliance needs: use both.

8. SCIM Provisioning

SCIM 2.0 enables automated user lifecycle: create/update/deactivate events pushed from IdP to Atlas without login.

Capabilities: user creation, deprovisioning (active=false → Atlas deactivates), group sync, attribute writeback (some IdPs).

Okta SCIM setup:

1. MongoDB Atlas Okta app → Provisioning → Configure API Integration
2. SCIM base URL: https://cloud.mongodb.com/api/atlas/v2/federationSettings/{federationSettingsId}/connectedOrgConfigs/{orgId}/users (verify against Atlas Admin API reference before use)
3. Bearer token: generate via Atlas Admin API service account or programmatic API key with Org Owner permissions
4. Enable Create/Update/Deactivate; configure Push Groups

Entra ID SCIM setup:

1. Enterprise apps → MongoDB Atlas - SSO → Provisioning → Automatic
2. Enter same SCIM URL pattern (verify against Atlas Admin API reference) + bearer token as secret token
3. Test connection → configure attribute mappings → assign scope

Deprovisioning: Okta sends PATCH /Users/{id} active=false; Entra ID sends SCIM deactivation on user removal or app assignment revocation.

JIT + SCIM coexist: SCIM handles lifecycle; JIT syncs attributes at login. SCIM group sync preferred over SAML memberOf assertions for compliance-sensitive orgs with dynamic membership.

9. Federation Manager

FMC: Atlas UI for all federation config, separate from standard org/project UI. Access: org sidebar → Identity & Access → Federation → Open Federation Management App. URL pattern: https://cloud.mongodb.com/v2#/federation//

Sections: Home/Quick Start (4-step guided setup), Identity Providers (IdP configs, metadata download, domain association, bypass URL, login URL), Organizations (link/unlink, default roles, domain restrictions, role mappings), Domains (verify/delete), Advanced Settings (restrict membership).

IdP config fields: Configuration Name, IdP Issuer URI (SAML EntityID), IdP SSO URL, IdP Signature Certificate (PEM), Request Binding (HTTP POST recommended), Response Signature Algorithm (SHA-256 recommended).

Atlas SAML metadata XML (Download metadata in FMC): contains ACS URL, Audience URI (SP EntityID), Atlas SP self-signed cert. Upload to IdP to auto-populate SP configuration. Note: the Atlas SP cert in metadata is for IdP to verify Atlas-signed AuthnRequests, not the IdP signing cert.

Login URL per IdP: unique URL in FMC for SP-initiated login directly to correct IdP. Use when multiple IdPs share a domain.

RelayState URLs (MongoDB-provided static values — copy exactly, not customer-specific):

• Support Portal: https://auth.mongodb.com/app/salesforce/exk1rw00vux0h1iFz297/sso/saml
• University: https://auth.mongodb.com/home/mongodb_thoughtindustriesstaging_1/0oadne22vtcdV5riC297/alndnea8d6SkOGXbS297
• Community Forums: https://auth.mongodb.com/home/mongodbexternal_communityforums_3/0oa3bqf5mlIQvkbmF297/aln3bqgadajdHoymn297

Audit: Atlas UI → Org → Activity Feed; Atlas Admin API GET /api/atlas/v2/orgs/{orgId}/events; IdP audit logs (Okta System Log, Entra ID Sign-in logs).

AtlasFederatedAuth Kubernetes Operator CRD: supports GitOps-driven federation config.

10. Troubleshooting

Debugging order: (1) IdP-side logs (show raw SAML Response), (2) browser DevTools Network tab → POST to ACS URL → base64-decode SAMLResponse, (3) validate Issuer, Audience (must match Atlas SP Entity ID), NotBefore/NotOnOrAfter, NameID format+value, AttributeStatement names (memberOf, firstName, lastName), (4) Atlas Activity Feed.

Audience restriction mismatch: Audience value doesn’t match Atlas SP EntityID. Fix: download Atlas metadata XML → copy entityID → set as Audience URI in IdP exactly (no trailing slash, exact case). Entra ID: confirm real value replaced the temporary placeholder after metadata upload.

NameID format rejected: Set Name ID Format to Unspecified in IdP. Atlas requires urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified or emailAddress. NameID value must be email matching Atlas username.

Clock skew: Intermittent failures across regions. Ensure NTP on IdP servers. SAML library clockSkewMs tolerance: 180s typical, 300s max (security control).

Group mapping not applying: Capture SAML Response → check AttributeStatement for memberOf exact name. Entra ID: group claim name must be “memberOf”, Namespace blank, “Emit groups as role claims” unchecked. Okta: Group Attribute Statement name exactly “memberOf”. Atlas role mapping Group Name must exactly match assertion value (display name or GUID).

Domain verification failing: DNS propagation up to 48h; verify TXT record with dig TXT; HTML file must return HTTP 200 at https://host.domain/mongodb-site-verification.html (HTTPS required); TXT record on exact domain not subdomain.

Bypass user locked out: Breakglass account domain was claimed. Fix: remap to unclaimed domain, disable bypass SAML mode (if accessible), or Atlas Support escalation.

Domain restriction too broad: Claimed wrong domain (e.g., gmail.com). Fix: delete domain mapping, add correct narrow domain, re-verify.

Certificate expiry: All logins fail. Fix: generate new cert from IdP → upload to Atlas FMC → test → remove old cert. Proactive: Atlas alert “IdP certificate about to expire” — configure ops notification; cert expiry visible in FMC IdP entry; rotate procedure: new cert in IdP → add to Atlas → verify login → remove old cert.

Wrong IdP redirect: Domain mapped to multiple IdPs, Atlas routes to first. Fix: use per-IdP Login URL from FMC.

Quick-Reference Checklist: New Federation Setup

[ ] Org Owner role confirmed; custom routable domain available; IdP admin access confirmed [ ] SAML app created in IdP; signing cert downloaded + converted to PEM [ ] Atlas FMC IdP entry created with placeholder values [ ] Atlas metadata XML downloaded; uploaded to IdP (sets real ACS URL + Audience URI) [ ] IdP real Issuer URI + SSO URL entered in Atlas FMC [ ] Attributes configured: firstName, lastName, memberOf [ ] Domain verified (DNS TXT or HTML file); associated with IdP in FMC [ ] Bypass SAML Mode URL saved securely [ ] Tested in private browser with real credentials [ ] Role mappings created; default org role set (optional) [ ] Breakglass account confirmed working [ ] Domain restriction enabled (optional); SCIM configured (if deprovisioning required)

References

• https://www.mongodb.com/docs/atlas/security/federated-authentication/
• https://www.mongodb.com/docs/atlas/security/manage-federated-auth/
• https://www.mongodb.com/docs/atlas/security/federation-advanced-options/
• https://www.mongodb.com/docs/atlas/security/manage-org-mapping/
• https://www.mongodb.com/docs/atlas/security/manage-role-mapping/
• https://www.mongodb.com/docs/atlas/security/federated-auth-okta/
• https://www.mongodb.com/docs/atlas/security/federated-auth-azure-ad/
• https://learn.microsoft.com/en-us/entra/identity/saas-apps/mongodb-cloud-tutorial
• https://www.okta.com/integrations/mongodb-atlas/
• https://www.scalekit.com/blog/saml-debugging-handbook-2026-how-to-diagnose-log-and-resolve-sso-failures

Related: [[mongodb-atlas-expert]], [[mongodb-security-architecture]], [[okta-expert]], [[mongodb-atlas-azure]], [[mongodb-atlas-iam-rbac]]