Set up Workforce Identity Federation with OIDC
On this page
In MongoDB 7.0 and later, you can manage your workforce access to MongoDB by federating to your own IdP supporting OpenID Connect (OIDC).
With Workforce Identity Federation, you can:
Manage your workforce access to MongoDB deployments through your existing IdP.
Enforce security policies such as password complexity, credential rotation, and MFA within your IdP.
Currently, you can only use Workforce Identity Federation with OIDC for database access.
You can enable one OIDC IdP for multiple organizations. When you enable OIDC IdP in an organization, you can use it in all projects in that organization for database access.
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.
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 Azure Active Directory, 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 Azure AD as an Identity Provider
To register your OIDC or OAuth application with Azure AD:
Register an application.
Navigate to App registrations.
In your Azure portal account, search and click Azure Active Directory.
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 Azure AD UI values map to in our Atlas Configuration Properties:
Azure AD UI | Atlas Configuration Property |
|---|---|
Application (client) ID | Client ID Audience |
OpenID Connect metadata document (without /.well-known/openid-configuration) | Issuer URI. |
Configure OIDC Authentication
Note
Prerequisite
This procedure requires you to have Organization Owner
access and assumes you already have an OIDC or OAuth2 application
created in your IdP. To learn
how to configure an IdP, see Configure An External Identity Provider Application.
You can configure Workforce Identity Federation with OIDC for database access in Atlas from the Federation Management Console.
Use the Federation Management Console to:
Configure Identity Providers to authenticate users belonging to specified organizations.
Connect Atlas Organizations to your IdP.
To configure an OIDC IdP in Atlas:
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 Configure Identity Providers.
If you do not have any Identity Providers configured yet, click Setup Identity Provider. Otherwise, on the Identity Providers screen, click Configure Identity Provider(s).
Enter the following OIDC Protocol Settings.
Setting | Necessity | Value |
|---|---|---|
Configuration Name | Required | Human-readable label that identifies this configuration. |
Configuration Description | Optional | Human-readable label that describes this configuration. |
Issuer URI | Required | Issuer value provided by your registered IdP application.
Using this URI, MongoDB finds an OpenID Provider Configuration
Document, which should be available in the
/.wellknown/open-id-configuration endpoint. |
Client ID | Required | Unique identifier for your registered application. Enter
the clientId value from the app you registered
with OIDC IdP. |
Audience | Required | Entity that your OIDC provider intends the token for. Enter
the audience value from the app you registered
with OIDC IdP. |
Requested Scopes | Optional | Tokens that give users permission to request data from the authorization endpoint. For each additional scope you want to add, click Add more scopes. |
User Claim | Required | The identifier of the claim that includes the user principal identity. Accept the default value unless your IdP uses a different claim. Default: |
Groups Claim | Required | The identifier of the claim that includes the principal's IdP user group membership information. Accept the default value unless your IdP uses a different claim, or you need a custom claim. Default: |
Click Finish.
Associate at least one domain to your OIDC IdP.
In your OIDC card, click Associate Domains.
In the Associate Domains with Identity Provider modal, select one or more domains.
Click Submit.
Enable your OIDC IdP in an organization.
Click Connect Organizations.
For the organization you want to connect to OIDC, click Configure Access.
Click Connect Identity Provider.
Note
If you have another IdP configured, this button says Connect Identity Provider(s).
In the Connect Identity Provider(s) modal, select a row where the Type is OIDC for Data Access.
Click Connect.
When you connect your OIDC IdP to an organization, Atlas enables OIDC for all the projects within that organization.
Configure OIDC Authorization
Atlas clusters grant access to users authenticating with your OIDC IdP by using the token issued by your IdP. MongoDB expects that the following claims exist in the access token:
Claim | Description |
|---|---|
iss | Identifies the token issuer, such as a registered OIDC or OAuth
application. |
sub | Identifier of the principal in your IdP. This value appears in
database access logs as the user identifier. |
aud | Identifies the intended consumer of the token. This value should
match the audience value set during the OIDC IdP
configuration in Atlas. |
iat | Time at which your IdP issued the token. |
exp | Time at which the token expires. |
groups | Custom claim that includes user group membership information.
OIDC used this information for authorization. |
After you enable OIDC IdP for your Organization in Atlas, set up authorization for IdP groups:
Open the Add New Database User or Group dialog.
In the Security section of the left navigation, click Database Access.
Click Add New Database User or Group.
Note
If you didn't apply your OIDC IdP to Atlas, this button says Add New Database User.
Select Federated Auth.
In the Authentication Method section, select the box marked Federated Auth.
Note
If you didn't apply your OIDC IdP to Atlas, you cannot select this box.
Enter your IdP group name.
In the User Group Identifier section, enter the user group name you configured in your IdP.
Assign group privileges.
Select the database group privileges. You can assign privileges to the new group in one or more of the following ways:
Select a built-in role from the Built-in Role dropdown menu. You can select one built-in role per database group within the Atlas UI. If you delete the default option, you can click Add Built-in Role to select a new built-in role.
If you have any custom roles defined, you can expand the Custom Roles section and select one or more roles from the Custom Roles dropdown menu. Click Add Custom Role to add more custom roles. You can also click the Custom Roles link to see the custom roles for your project.
Expand the Specific Privileges section and select one or more privileges from the Specific Privileges dropdown menu. Click Add Specific Privilege to add more privileges. This assigns the group specific privileges on individual databases and collections.
Atlas can apply a built-in role, multiple custom roles, and multiple specific privileges to a database group.
To remove an applied role or privilege, click Delete next to the role or privilege you wish to delete.
Note
Atlas doesn't display the Delete icon next to your Built-in Role, Custom Role, or Specific Privilege selection if you selected only one option. You can delete the selected role or privilege once you apply another role or privilege.
For more information on authorization, see Role-Based Access Control and Built-in Roles in the MongoDB manual.
Optional: Specify the resources in the project that the group can access.
By default, groups can access all the clusters and federated database instances in the project. You can restrict access to specific clusters and federated database instances by doing the following:
Toggle Restrict Access to Specific Clusters/Federated Database Instances to ON.
Select the clusters and federated database instances to grant the group access to from the Grant Access To list.
Optional: Save as temporary group.
Toggle Temporary Group to On and choose a time after which Atlas can delete the group from the Temporary Group Duration dropdown. You can select one of the following time periods for the group to exist:
6 hours
1 day
1 week
In the Database Users tab, temporary groups display the time remaining until Atlas will delete the group. Once Atlas deletes the group, any client or application that uses the temporary group's credentials loses access to the cluster.
Click Add Group.
Delete OIDC Configuration
To delete your OIDC configuration, you must:
Disconnect each organization you connected to your OIDC IdP.
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 IdP 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.