Docs Home → Launch & Manage MongoDB → MongoDB Atlas
Set Up User Authentication and Authorization with OIDC/OAuth2.0
On this page
You can authenticate and authorize access to Atlas for both employees and applications with your own identity provider supporting OIDC. You can configure user access with Workforce Identity Federation, and you can configure application access with Workload Identity Federation. See the following table for a comparison of the OIDC access options.
Authentication method | User type | Access type | Supported protocols |
|---|---|---|---|
Workforce Identity Federation | Human users | Atlas UI Access, Database Access | OIDC, SAML |
Workload Identity Federation | Programmatic users | Database Access | OAuth2.0 |
Select the authentication method to learn more:
Required Access
To manage OIDC configuration, you must have
Organization Owner access to Atlas.
Prerequisites
To manage user authentication and authorization using OIDC in Atlas, you must map one or more domains to your Identity Provider.
Procedures
Important
You configure Workforce Identity Federation in two stages. To link your IdP to Atlas:
Configure your IdP and save its metadata.
Set the metadata from your IdP to Atlas.
Authenticate for a User or Group of Users
For both Workload Identity Federation and Workforce Identity Federation, you can grant authorization for either a group of users who will each have the same permissions, or for a single user.
Complete the following steps to create an OIDC entry for multiple users with the same permissions:
Select Group Membership.
Select the Group Membership option in the Configure Identity Provider flow.
Update the Group Claim and the User Claim.
Update the Group Claim and the User Claim default
values of group and sub respectively as needed to align with
your externally configured OIDC provider.
Complete the following steps to create an OIDC entry for a single user:
Select User ID.
Select the User ID option in the Configure Identity Provider flow.
Update the User Claim.
Update the User Claim default value of sub as needed to
align with your externally configured OIDC provider.
Configure An External Identity Provider Application
To configure Workforce Identity Federation with OIDC, you must first register your OIDC or OAuth application with an IdP that supports OIDC standard, such as Microsoft Entra ID, Okta, or Ping Identity.
You configure your OIDC application for the following grant types:
Authorization Code Flow with PKCE and/or
Device Authorization Flow.
MongoDB recommends using Authorization Code Flow with PKCE for better security posture. Use Device Authorization Flow only if your users need to access the database from machines with no browser.
OIDC application registration steps can vary based on your IdP. Ensure that you complete the following items during your registration process:
Register a new application for Atlas.
Make sure to select public client/native application as the client type.
Set the Redirect URL value to http://localhost:27097/redirect.
Add or enable groups claim.
This assures that your access tokens contain the group membership information of the user authenticating. MongoDB uses the values sent in groups claim for authorization.
(Optional) Allow refresh tokens if you want MongoDB clients to refresh the tokens for a better user experience.
(Optional) Configure access token lifetime (exp claim) to align with
your database connection session time.
Once you register your application, save the issuer,
clientId and audience values to use in the next stage of the
Atlas OIDC IdP configuration.
Configure Microsoft Entra ID as an Identity Provider
To register your OIDC or OAuth application with Microsoft Entra ID:
Register an application.
Navigate to App registrations.
In your Azure portal account, search and click Microsoft Entra ID.
In the Manage section of the left navigation, click App registrations.
Click New registration.
Apply the following values.
Field | Value |
|---|---|
Name | Atlas Database - OIDC |
Supported Account Types | Accounts in this organizational directory only (single tenant) |
Redirect URI | - Public client/native (mobile & desktop) - http://localhost:27097/redirect |
Click Register.
To learn more about registering an application, see Azure Documentation.
Add a group claim.
Navigate to Token Configuration.
In the Manage section of the left navigation, click Token Configuration.
Click Add groups claim.
In the Edit groups claim modal, select Security.
What groups you select depend on the type of groups you configured in your Azure environment. You may need to select a different type of group to send the appropriate group information.
In the Customize token properties by type section, ensure that you only select Group ID.
When you select Group Id, Azure sends the security group's Object ID.
Click Add.
To learn more about adding a group claim, see Azure Documentation.
Add a user identifier claim to the access token.
Click Add optional claim.
In the Add optional claim modal, select Access.
Select a claim that carries a user identifier that you can refer to in MongoDB access logs such as an email.
Click Add.
In the Microsoft Graph Permissions note, check the box, and click Add.
To learn more, see Azure Documentation.
Update the manifest.
In the Manage section of the left navigation, click Manifest.
Update the accessTokenAcceptedVersion from null to 2.
The number 2 represents Version 2 of Microsoft's access
tokens. Other applications can use this as a signed
attestation of the Active Directory-managed user's identity.
Version 2 ensures that the token is a JSON Web Token that
MongoDB understands.
Click Save.
To learn more about adding an optional claim, see Azure Documentation.
Remember metadata.
In the left navigation, click Overview.
Copy the Application (client) ID value.
In the top navigation, click Endpoints.
Copy the OpenID Connect metadata document value
without the /.well-known/openid-configuration part.
You can also retrieve this value by following the
OpenID Connect metadata document URL and
copying the value for issuer.
The following table shows what these Microsoft Entra ID UI values map to in our Atlas Configuration Properties:
Microsoft Entra ID UI | Atlas Configuration Property |
|---|---|
Application (client) ID | Client ID Audience |
OpenID Connect metadata document (without /.well-known/openid-configuration) | Issuer URI. |
Delete OIDC Configuration
To delete your OIDC configuration, you must:
Disconnect each organization you connected to your OIDC Identity Provider.
Open the Management Console.
Navigate to the Settings page for your organization.
If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
Navigate to the Federation Management App.
In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.
Click Organizations in the left side navigation bar.
Click the organization that has OIDC enabled.
Click Disconnect on the OIDC card.
In the Disconnect identity provider? modal, click Disconnect.
When you disconnect an IdP, users who authenticate using the IdP will lose access to OIDC in the Atlas projects listed in the Project table.
Click Identity Providers in the left side navigation bar.
In the OIDC card, click Delete.
In the Delete Identity Provider? modal, click Delete.
Revoke JWKS
Note
Don't use this feature to rotate your signing keys. When you rotate your OIDC Identity Provider signing keys, MongoDB fetches the JWKS automatically upon expiration of the existing access tokens.
If your private key is compromised, you can immediately revoke your JSON Web Key Sets (JWKS) cached in MongoDB nodes:
Update your signing keys in your OIDC identity provider.
Open the Management Console.
Navigate to the Settings page for your organization.
If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.
Click the Organization Settings icon next to the Organizations menu.
Navigate to the Federation Management App.
In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.
Click Identity Providers in the left side navigation bar.
Scroll to the OIDC card.
Click the Revoke button.
After you click Revoke, MongoDB fetches the new keys through your JWKS endpoint. You must restart your clients (such as MongoDB Shell or Compass) after revoking JWKS.