For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Workforce (Humans)
Docs Home
/ /
OIDC/OAuth2.0
/
Workforce (Humans)
Docs Home
/
Development
/
Connect to a Cluster
/
Authentication
/
OIDC/OAuth2.0
/
Workforce (Humans)

Configure Workforce Identity Federation from PingOne

This guide shows you how to configure Workforce Identity Federation using PingOne as your IdP.

After integrating PingOne and Atlas, your workforce can use their PingOne credentials to access Atlas clusters with OIDC authentication.

Required Access

To manage federated authentication, you must have Organization Owner access to one or more organizations that are delegating federation settings to the instance.

Prerequisites

To use PingOne as an IdP for Atlas, you must have:

  • A PingOne subscription. To obtain a subscription, visit PingOne.

  • A PingOne user with administrative privileges. To grant a user administrative privileges, see Managing administrators. Alternatively, you can use the default administrative user created upon activation of your PingOne account.

Procedures

Throughout the following procedure, it is helpful to have one browser tab open to your Atlas Federation Management Console and one tab open to your PingOne account.

Configure PingOne as an Identity Provider

Use the PingOne admin console to configure PingOne as an OIDC IdP.

1

Create an application in PingOne.

  1. In the PingOne admin console, go to Applications > My Applications > OIDC.

  2. Click Add Application.

  3. Select Native App and click Next.

To learn more, see Adding or updating an OIDC application.

2

Configure your application.

  1. In the Application Name field, enter a name for your application.

  2. In the Short Description field, enter a description for the application.

  3. In the Category list, select a category to assign the application to.

  4. Click Next.

3

Configure grant types and redirect URIs.

  1. Select the allowed grant types for the application.

    Enable the following grant types:

    • Authorization Code or Device Authorization

    • (Optional) Refresh Token

      Enabling refresh tokens provides a better user experience. When refresh tokens are not enabled, users must re-authenticate with the identity provider once their access token expires.

  2. In the Redirect URIs field, enter the following URL: http://localhost:27097/redirect.

  3. Click Next.

4

Configure scopes and attributes.

  1. Add the openid scope to the allowed list.

  2. Add attributes to the Default User Profile Attribute Contract.

    The sub attribute is required for all applications.

    To use group-based authorization, add a groups attribute.

  3. Click Next.

5

Map identity repository attributes.

Map your identity repository attributes to claims made by the application.

  1. For each IdP attribute, enter or select the target attribute from the list.

  2. Click Next.

6

Assign groups and save.

  1. Click the icon for each group that you want to authorize.

  2. Click Done.

7

Obtain the issuer URI and client ID.

After you create the application, copy the following values from the application summary page:

  • Discovery URL or Issuer

  • Client ID

  • IDPID (if displayed)

The issuer URI typically follows this format: https://auth.pingone.com/<environment-id>/as.

Save these values to use in the next stage of the Atlas configuration.

Configure Workforce Identity Federation in Atlas

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 PingOne as an Identity Provider.

To configure a Workforce Identity Provider in Atlas:

1
In Atlas, go to the Federation Management console for your organization.

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

  2. In the sidebar, click Federation under the Identity & Access heading.

  3. Click Open Federation Management App.

The Federation page displays.

2

Configure identity 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 Set Up Identity Provider.

    • Otherwise, on the Identity Providers screen, click Configure Identity Provider(s).

  3. Select Workforce Identity Federation and click Continue.

  4. Select OIDC for Data Access.

3

Enter the following Workforce Identity Provider Protocol Settings.

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 /.well-known/openid-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.

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.

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

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.

Customize 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 Group Membership.

Default: groups

Customize 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

4

Click Save and Finish.

5

(Optional) Associate a domain to your Workforce IdP.

Note

This step is required only if you need to connect multiple Workforce IdPs to the same organization with different domains. Atlas supports a maximum of two Workforce IdPs connected to an organization: one OIDC IdP (for database access) and one SAML IdP (for UI access).

  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.

6

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

7

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.

8

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.

Add a Database User using Workforce Authentication

1
In Atlas, go to the Database & Network 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 & Network Access under the Security heading.

The Database & Network Access page displays after you complete the preceding steps.

2

Open the Add New Database User or Group dialog box.

Click Add New Database User or Group.

Note

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

3

Select Federated Auth.

In the Authentication Method section, select Federated Auth.

Note

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

4

Select Identity Provider and Identifier

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

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

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.

6

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.

7

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.

8

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.

Connect a Client to MongoDB with Workforce Identity Federation

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

Note

If you configured Device Authorization Flow, you must pass the --oidcFlows=device-auth flag when connecting with mongosh. For example:

mongosh "<connection-string>" \
  --authenticationMechanism MONGODB-OIDC \
  --oidcFlows=device-auth

Learn More

Back
Okta
Next
Workload (Applications)
Rate this page

On this page