Docs Menu
Docs Home
/
MongoDB Atlas
/ / /

Set up Workforce Identity Federation with OIDC

On this page

  • Required Access
  • Procedures
  • Configure An External Identity Provider Application
  • Configure Workforce Identity Federation Authentication
  • Add a Database User using Workforce Authentication
  • Connect an Application to MongoDB with Workforce Identity Federation
  • Manage an Existing Workforce Identity Federation Configuration
  • Revoke JWKS
  • Delete a Workforce Identity Provider Configuration

In MongoDB 7.0 and later, Workforce Identity Federation lets you use an external Identity Provider (IdP), such as your corporate IdP, to authenticate and authorize a given workforce, such as employees, partners, and contractors.

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.

  • Grant access for a group of users or a single user.

After you configure your external IdP and add it to your Workforce Identity Federation one time, you can enable Workforce Identity Provider for multiple Atlas organizations. After you enable Workforce Identity Federation in a given organization, you can use it in all projects in that organization for database access.

Workforce Identity Federation is supported by Atlas dedicated clusters (M10 and above) running MongoDB version 7.0.11 and above. You need to use MongoDB Shell or Compass to access Atlas with Workforce Identity Federation.

To learn more about implementing Workforce Identity Federation access, see Connect an Application to MongoDB with Workforce Identity Federation.

To manage Workforce Identity Federation configuration, you must have Organization Owner access to Atlas.

To access Atlas clusters with Workforce Identity Federation, complete the following steps:

  1. Configure a Workforce Identity Provider (one-time setup).

    1. Configure your external identity provider.

    2. Configure Workforce Identity Provider in Atlas and enable it for your |service| organization(s).

  2. Grant external identities (user principals) or groups access to MongoDB clusters.

  3. Authenticate to your Atlas clusters with MongoDB Shell or Compass.

To configure Workforce Identity Federation with OIDC, register your OIDC application with an IdP that supports OIDC standard, such as Microsoft Entra ID, Okta, or Ping Identity.

Note

Workforce Identity Federation supports only JWT for authentication. It doesn't support opaque access tokens.

You can configure your OIDC application for the following grant types:

  • Authorization Code Flow with PKCE

  • Device Authorization Flow

MongoDB recommends that you use Authorization Code Flow with PKCE for increased security. Use Device Authorization Flow only if your users need to access the database from machines with no browser.

The OIDC application registration steps can vary based on your IdP. Ensure that you complete the following items during your registration process:

1

Select public client/native application as the client type.

2
3

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.

4

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

5

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

After you register your application, save the issuer, clientId, and audience values to use in the next stage of the Atlas Workforce IdP configuration.

To register your OIDC application with Microsoft Entra ID:

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

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

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

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

5
  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:

Microsoft Entra ID UI
Atlas Configuration Property
Application (client) ID
Client ID
Audience
OpenID Connect metadata document (without /.well-known/openid-configuration)
Issuer URI.

Note

Prerequisite

This procedure requires you to have Organization Owner access and assumes you already have an OIDC 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.

To configure a Workforce Identity Provider in Atlas:

1
  1. Navigate to Organization settings.

  2. Click on Open Federation Management App.

2

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.

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

4
Setting
Necessity
Value
Configuration Name
Required
Human-readable label that identifies this configuration. This label is visible to your Atlas users.
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 external Identity Provider.
Audience
Required
Entity that your external identity provider intends the token for. Enter the audience value from the app you registered with external Identity Provider. Generally, this value is the same as the Client ID.
Authorization Type
Required
Select Group Membership to grant authorization based on IdP user group membership, or select User ID to grant an individual user authorization.
Requested Scopes
Optional

Tokens that give users permission to request data from the authorization endpoint. If you plan to support refresh tokens, this field must include the value offline_access.

If your identity provider is Microsoft Entra ID, Atlas requires this setting. Add default scope, which is <application client id>/.default.

For each additional scope you want to add, click Add more scopes.

User Claim
Required

Identifier of the claim that includes the user principal identity. Accept the default value unless your IdP uses a different claim.

Default: sub

Groups Claim
Required

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. This field is only required if you select Groups Membership.

Default: groups

5
6
  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.

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

8

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

9

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

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

2

Click Add New Database User or Group.

Note

Until you apply your Workforce IdP to Atlas, this button says Add New Database User.

3

In the Authentication Method section, select Federated Auth.

Note

Until you enable Workforce IdP for your organization, you can't select this box.

4

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.

Note

For Azure Entra ID users, this value maps to the Object Id of your Azure user group rather than user group name.

5

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.

6

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.

7

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.

8

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.

The following lists the ways you can connect an application to MongoDB with Workforce Identity Federation authentication:

Note

Use the following procedure only if you manage your own signing keys.

Don't use this feature to rotate your signing keys. When you rotate your Workforce Identity Provider signing keys, MongoDB fetches the JWKS automatically when the existing access tokens expire.

If your private key is compromised, you can immediately revoke your JSON Web Key Sets (JWKS) cached in MongoDB nodes:

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

2

In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.

3
4
5

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.

To delete your Workforce Identity Provider configuration:

1
  1. Open the Management Console.

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

    2

    In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.

  2. Click Organizations in the left sidebar.

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

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

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

2
3
4

In the Delete Identity Provider? modal, click Delete.

Back

OIDC/OAuth2.0

Next

Workload (Applications)