Set up Workforce Identity Federation with OIDC

Register a new application for Atlas.

Select public client/native application as the client type.

Set the Redirect URL value to http://localhost:27097/redirect.

(Conditional) Add or enable a groups claim if you authenticate with groups.

For groups, this step ensures that your access tokens contain the group membership information of the user authenticating. MongoDB uses the values sent in a groups claim for authorization.

(Optional) Allow refresh tokens if you want MongoDB clients to refresh the tokens for a better user experience.

(Optional) Configure the access token lifetime (exp claim) to align with your database connection session time.

Register an application.

1. Navigate to App registrations.

   1. In your Azure portal account, search and click Microsoft Entra ID.

   2. In the Manage section of the left navigation, click App registrations.

2. Click New registration.

3. Apply the following values.

   Field	Value
   Name	Atlas Database - Workforce
   Supported Account Types	Accounts in this organizational directory only (single tenant)
   Redirect URI	- Public client/native (mobile & desktop) - http://localhost:27097/redirect

4. Click Register.

To learn more about registering an application, see Azure Documentation.

Add a group claim.

1. Navigate to Token Configuration.

   In the Manage section of the left navigation, click Token Configuration.

2. Click Add groups claim.

3. 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.

4. In the Customize token properties by type section, only select Group ID.

5. Click Add.

To learn more about adding a group claim, see Azure Documentation.

Add a user identifier claim to the access token.

1. Click Add optional claim.

2. In the Add optional claim modal, select Access.

3. Select a claim that carries a user identifier that you can refer to in MongoDB access logs such as an email.

   You can use the UPN claim to identify users with their email address.

4. Click Add.

5. In the Microsoft Graph Permissions note, check the box, and click Add.

To learn more, see Azure Documentation.

Update the manifest.

1. In the Manage section of the left navigation, click Manifest.

2. 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.

3. Click Save.

To learn more about adding an optional claim, see Azure Documentation.

Remember metadata.

1. In the left navigation, click Overview.

   Copy the Application (client) ID value.

2. In the top navigation, click Endpoints.

   Copy the OpenID Connect metadata document value without the /.well-known/openid-configuration part.

   You can also get this value by copying the value for issuer in the OpenID Connect metadata document URL.

The following table shows what these Microsoft Entra ID UI values map to in our Atlas Configuration Properties:

Go to the Federation Management Console.

1. Navigate to Organization settings.

2. Click on Open Federation Management App.

Add and verify domain ownership.

You must verify ownership of the domain that you register with your IdP. You can skip this step if you've already registered your domain for SAML SSO with Atlas.

1. Select Domains in the left sidebar.

2. Click the Add Domain button.

3. Enter a display name in the Display Name box.

4. Enter a domain name in the Domain Name box.

5. Select the method you would like to use to verify that you are the owner of your domain by clicking either the HTML File Upload or DNS Record button.

6. If you selected HTML File Upload, download the provided HTML file and upload it to your domain so that it is accessible at https://<your-domain/mongodb-site-verification.html>.

7. If you selected DNS Record, copy the provided TXT Record, and upload it to your domain provider.

8. Click Continue.

9. Finally, in the Domains page, click the Verify button for your newly added domain.

Configure identify providers.

1. Click Identity Providers in the left sidebar.

2. Do one of the following steps:

   • 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).

3. Select Workforce Identity Provider and click Continue.

4. Select OIDC for Data Access.

Enter the following Workforce Identity Provider Protocol Settings.

Click Save and Finish.

Associate at least one domain to your Workforce IdP.

1. In your Workforce Identity Provider card, click Associate Domains.

2. In the Associate Domains with Identity Provider modal, select one or more domains.

3. Click Submit.

Enable your Workforce Identity Provider in an organization.

1. Click Connect Organizations.

2. For the organization you want to connect to Workforce Identity Provider, click Configure Access.

3. Click Connect Identity Provider.

   Note

   If you have another IdP configured, this button says Connect Identity Provider(s).

Select Workforce Identity Federation for Data Access.

In the Connect Identity Provider(s) modal, select a Workforce Identity Provider where the Purpose is Workforce Identity Federation.

Click Connect.

When you connect your Workforce Identity Provider to an organization, Atlas enables your Workforce Identity Provider for all the projects within that organization.

In Atlas, go to the Database Access page for your project.

1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.

2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

3. In the sidebar, click Database Access under the Security heading.

Open the Add New Database User or Group dialog box.

Click Add New Database User or Group.

Select Federated Auth.

In the Authentication Method section, select Federated Auth.

Select Identity Provider and Identifier

a. In the Select Identity Provider section, select a configured OIDC Identity Provider.

1. Specify either the user identifier or group identifier associated with your configured Workforce Identity Provider.

Assign user or group privileges.

To assign privileges to the new user or group, do one or more of the following tasks:

• Select a built-in role from the Built-in Role dropdown menu.

  • You can select one built-in role per database group in the Atlas UI.

  • If you delete the default option, you can click Add Built-in Role to select a new built-in role.

• Select or add custom roles.

  • 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.

  • Click the Custom Roles link to see the custom roles for your project.

• Add privileges.

  • 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.

• Remove an applied role or privilege.

  • Click Delete next to the

    role or privilege 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.

Atlas can apply a built-in role, multiple custom roles, and multiple specific privileges to a database group.

To learn more about authorization, see Role-Based Access Control and Built-in Roles in the MongoDB manual.

Specify the resources in the project that the user or group can access.

By default, groups can access all the clusters and federated database instances in the project. To restrict access to specific clusters and federated database instances:

1. Toggle Restrict Access to Specific Clusters/Federated Database Instances to On.

2. Select the clusters and federated database instances to grant the group access to from the Grant Access To list.

Save as a temporary user or group.

Toggle Temporary User or Temporary Group to On and choose a time after which Atlas can delete the user or group from the Temporary User Duration or 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 users or groups display the time remaining until Atlas deletes the users or group. After Atlas deletes the user or group, any client or application that uses the temporary user's or group's credentials loses access to the cluster.

Add the new database user or group.

Do one of the following steps:

• If you added a user, click the Add User button.

• If you added a group, click the Add Group button.

Update your signing keys in your Workforce identity provider.

In Atlas, go to the Organization Settings page.

1. If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.

2. 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 sidebar.

Scroll to the Workforce Identity Provider 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 mongosh or Compass) after you revoke JWKS.

In Atlas, go to the Organization Settings page.

1. If it is not already displayed, select your desired organization from the Organizations menu in the navigation bar.

2. 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.

Disconnect each organization you connected to your Workforce Identity Provider.

1. Click Organizations in the left sidebar.

2. Click the organization that has Workforce Identity Federation enabled.

3. Click Disconnect under the Manage dropdown on the Workforce Identity Federation card.

4. In the Disconnect identity provider? modal, click Disconnect.

   When you disconnect an IdP, users who authenticate using the IdP lose access to Workforce Identity Federation in the Atlas projects listed in the Project table.

Click Identity Providers in the left sidebar.

In the Workforce Identity Provider card, click Delete.

In the Delete Identity Provider? modal, click Delete.