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:
(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.
To learn more about registering an application, see Azure Documentation.
Add a group claim.
To learn more about adding a group claim, see Azure Documentation.
Add a user identifier claim to the access token.
Select a claim that carries a user identifier that you can refer to in MongoDB access logs such as an email.
To learn more, see Azure Documentation.
Update the 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.
To learn more about adding an optional claim, see Azure Documentation.
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:
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: |
In the Connect Identity Provider(s) modal, select a row where the Type is OIDC for Data Access.
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.
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.
Delete OIDC Configuration
To delete your OIDC configuration, you must:
Click Identity Providers in the left side navigation bar.
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: