In MongoDB 7.0 and later, you can use Workforce Identity Federation with an external Identity Provider (IdP), such as your corporate IdP. Workforce Identity Federation authenticates and authorizes your workforce, including 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 multi-factor authentication within your IdP.
You can only create one Workforce Identity Federation per project, but you can edit or recreate the configuration at any time.
Required Access
To configure Workforce Identity Federation, you must have Project Owner access to Ops Manager.
Prerequisites
You must meet these prerequisites:
mongosh1.9.1 or later.MongoDB 7.0 or later.
At least one other authentication mechanism with MongoDB Agent configured.
Note
The MongoDB Agent can't connect to your deployment through OIDC. You must enable another auth mechanism for the MongoDB Agent. If Ops Manager doesn't manage Monitoring or Backup, you must manually configure them to use the alternative authentication mechanism.
Procedures
To access Ops Manager deployments with Workforce Identity Federation, follow these steps:
Configure a Workforce Identity Provider (one-time setup).
Configure an External Identity Provider App
IMPORTANT: To reset Authentication and TLS settings for your project, first unmanage any MongoDB deployments that Ops Manager manages in your project.
To configure Workforce Identity Federation with OIDC, register your OIDC app with an IdP that supports the OIDC standard. Examples include Microsoft Entra ID, Okta, and Ping Identity.
You can configure your OIDC app for these 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 app registration steps can vary by IdP. During your app registration, set these items:
The generic registration steps for your OIDC app are as follows:
(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.
After you register your application, save the issuer, clientId, and audience values to use in the next stage of the configuration.
To register your OIDC app with Microsoft Entra ID:
Register an application.
Navigate to App registrations.
In your Azure portal account, search and click Microsoft Entra ID.
In the Manage section of the left navigation, click App registrations.
Click New registration.
Apply the following values.
FieldValueName
Ops Manager Database - Workforce
Supported Account Types
Accounts in this organizational directory only (single tenant)
Redirect URI
- Public client/native (mobile & desktop)
-http://localhost:27097/redirectClick 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, only select Group 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.
You can use the UPN claim to identify users with their email address.
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
nullto2.The number
2represents 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-configurationpart.You can also get this value by copying the value for
issuerin the OpenID Connect metadata document URL.
The following table shows what these Microsoft Entra ID UI values map to in our MongoDB Atlas Configuration Properties:
Microsoft Entra ID UI | MongoDB Atlas Configuration Property |
|---|---|
Application (client) ID | Client ID |
OpenID Connect metadata document (without /.well-known/openid-configuration) | Issuer URI. |
To register your OIDC application with Microsoft Active Directory Federation Services (AD FS), you must have an AD FS server that is joined to an Active Directory domain and has a publicly trusted SSL certificate.
Use the following procedure to register your OIDC application with AD FS:
Update the Federation Service Identifier.
In Server Manager, go to Tools → AD FS Management.
Click Edit Federation Service Properties.
In the Federation Service identifier field, change the value from
https://<domain>/adfs/services/trusttohttps://<domain>/adfs.<domain>should be replaced with the name of the Active Directory domain that your AD FS server belongs to.Click OK.
The Federation Service Identifier you update in this step is the issuer URI that you use when configuring your OIDC provider in MongoDB. If these values don't match, authentication fails because of a token issuer mismatch.
Add the groups and sub claims to the access token.
MongoDB reads the groups and sub claims from the access token. By default, AD FS includes sub only in the ID token and sends an idsub claim in the access token instead. To add both claims to the access token, create an issuance transform rule on your web API:
In AD FS Management, open the properties for your application group.
In the Applications section, select your web API and click Edit.
On the Issuance Transform Rules tab, click Add Rule.
In the Claim rule template field, select Send LDAP Attributes as Claims and click Next.
In the Claim rule name field, enter a name for the rule.
In the Attribute store field, select Active Directory.
Map the following LDAP attributes to outgoing claim types:
LDAP AttributeOutgoing Claim TypeToken-Groups - Unqualified Names
groupsUser-Principal-Name
subClick OK.
To register your OIDC application with Okta:
Create an application in Okta.
In your Okta Admin dashboard, use the left navigation pane to go to Applications → Applications.
On the Applications screen, click Create App Integration.
In the Sign-in method section, select OIDC - OpenID Connect.
In the Application type section, select Native Application.
Click Next.
To learn more, see Create OIDC app integrations.
Configure your New Native App Integration.
After you create an app integration, you are automatically redirected to the New Native App Integration screen.
In the App integration name field, enter a name for your application.
In the Grant type field, select the grant types.
Enable the following grant types:
Authorization Code, Device Authorization, or both
(Optional) Refresh Token
Enabling refresh tokens provides a better user experience. If you don't enable refresh tokens, users must re-authenticate with the identity provider once their access token expires.
In the Sign-in redirect URIs section, enter a URL.
Enter the following URL:
http://localhost:27097/redirect.In the Assignments section, configure the Controlled access and Enable immediate access fields with the appropriate settings for your security policies.
Click Save.
To learn more, see Create OIDC app integrations.
Configure PKCE and obtain client ID.
On your application dashboard, go to the General tab and configure the following:
In the Client ID field, click the icon to copy the client ID for later use.
In the Proof Key for Code Exchange (PKCE) field, ensure Require PKCE as additional verification is enabled (checked by default).
Add an authorization server.
In the left navigation pane, go to Security → API. Click Add Authorization Server.
In the Name field, enter a name for your server.
Fill in the Audience field.
The Audience is the entity that OIDC intends the token for. While this can be any valid URI, generally, this is the client ID of your application you copied in the previous step.
(Optional) In the Description field, enter a description of your server.
Click Save.
To learn more, see Create an Authorization Server.
Find and save the issuer URI.
After you create your authorization server, you are automatically redirected to your authorization server's screen.
Under the Settings tab, save the issuer URI by copying the first part of the Metadata URI up to the .well-known section. The URI structure should be similar to: https://<your-okta-domain>/oauth2/ausabgmhveoOQSMsE697.
(Conditionally Required) Add a Groups claim.
This step is only required if you want to authorize users using Okta groups. If you are planning on using User ID for authorization instead, you can skip this step.
On your authorization server screen, go to the Claims tab and click Add Claim.
Configure the Groups claim with the following configuration information:
FieldValueName
Enter a name for your claim.
Include in token type
Click the drop-down and select Access Token.
Value type
Click the drop-down and select Groups.
Filter
Click the drop-down and select Matches regex. Next to the drop-down, enter a regular expression that matches only groups used for MongoDB Atlas authorization. For example, if your MongoDB Atlas authorization groups use a common naming prefix, enter
^<mongodb-atlas-group-prefix>.*where<mongodb-atlas-group-prefix>is your chosen prefix.Disable claim
Do not check.
Include in
Select Any scope.
Click Create.
Important
Avoid using .* as the filter value. The .* expression matches every group assigned to the user, including groups unrelated to MongoDB Atlas authorization. A broad filter increases the access token size and can cause authentication failures when the token exceeds the preAuthMaximumMessageSizeBytes limit (16 KiB by default).
To reduce token size, create a dedicated naming convention for MongoDB Atlas authorization groups and filter on that convention.
If your deployment intentionally requires a large groups claim, you can increase the preAuthMaximumMessageSizeBytes parameter on your cluster. However, increasing this limit has resource and security implications and should not be used as a workaround for an unnecessarily broad claim.
To learn more, see Create Claims.
Create an access policy.
On your authorization server screen, go to the Access Policies tab and click Add Policy.
In the Name field, enter a policy name.
In the Description field, enter a description for the policy.
In the Assign to field, select All clients.
Click Create Policy.
To learn more, see Create an Access Policy.
Create a rule for the access policy.
Under the Access Policies tab, click Add Rule.
In the Rule Name field, enter a name for the access policy.
For IF Grant Type is, select a grant type.
When configuring grant types, select the appropriate option based on the client behavior:
If the client is acting on behalf of itself, select Client Credentials.
If the client is acting on behalf of a user, select the following:
Authorization Code
Device Authorization
Add rule configurations based on your organization's security policy.
Example Okta rule configuration:
FieldValueAND user is
Select Any user assigned to the app.
AND Scopes requested
Select Any scopes.
THEN Use this inline hook
None (disabled)
AND Access token lifetime is
1 Hours
AND Refresh token lifetime is
Click the second drop-down and select Unlimited.
but will expire if not used every
Enter 7 days.
Click Create Rule.
To learn more, see Create Rules for each Access Policy.
Create a group.
In the left navigation pane, go to Directory → Groups and click Add Group.
In the Name field, name your directory
OIDC.(Optional) In the Description field, enter a description for your rule.
Click Save.
To learn more, see Create a group.
Follow the Okta documentation to manually assign people to the group.
Add a user to your organization.
In the left navigation pane, go to Directory → People and click Add Person.
Provide user details by entering the following values in the corresponding fields:
FieldValueUser type
Select User.
First name
Provide a name as needed.
Last name
Provide a name as needed.
Username
Enter an email as a username.
Primary email
Enter an email. The email must be same as the one used for the Username field.
Secondary email
Optional.
Groups
Enter OIDC.
Activation
Select Activate Now and check I will set password.
Password
Enter a password.
User must change password on first login
Select Optional
Click Save.
To learn more, see Add Users Manually.
Configure Workforce Identity Federation Authentication
To configure Workforce Identity Federation with OIDC, follow this procedure.
Note
Workforce Identity Federation supports only JSON Web Token (JWT) authentication. It doesn't support opaque access tokens.
Navigate to the Security Settings dialog for your deployment.
Select the organization that contains your project from the Organizations menu in the navigation bar.
Select your project from the Projects menu in the navigation bar.
Click Deployment in the sidebar.
Click the Security tab.
Click the Settings tab.
Perform one of the following actions:
If this is your first time configuring TLS, authentication, or authorization settings for this project, click Get Started.
If you have already configured TLS authentication, or authorization settings for this project, click Edit.
Optional: Specify the TLS Settings.
Field | Action |
|---|---|
MongoDB Deployment Transport Layer Security (TLS) | Toggle this slider to ON. |
TLS CA File Path | The TLS Certificate Authority file is a The encrypted private key for the Type the file path to the TLS Certificate Authority file on every host running a MongoDB process:
This enables the Click Validate to test that each host in your deployment has a TLS Certificate Authority at the paths you specified. |
Cluster TLS CA File Path | The If you do not specify the
|
Client Certificate Mode | Select if client applications or MongoDB Agents must present a TLS certificate when connecting to TLS-enabled MongoDB deployments. Each MongoDB deployment checks for certificates from these client hosts when they try to connect. If you choose to require the client TLS certificates, make sure they are valid. Accepted values are:
|
Enter the following settings.
Setting | Necessity | Value |
|---|---|---|
Configuration Name | Required | Unique label that identifies this configuration. This label is visible to your Ops Manager users and is used when creating users and roles for authorization. It is case-sensitive and can only contain the following characters:
After saving the configuration, you can't edit the configuration name. |
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 |
Client ID | Required | Unique identifier for your registered application. Enter the |
Audience | Required | Entity that your external identity provider intends the token for. Enter the |
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. |
Authorization Type | Required | Select |
Customize 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: |
Customize Group Claim | Required | Required if you select Default: |
Configure OIDC Authorization
MongoDB doesn't explicitly create database users for OIDC. It maps OIDC users to MongoDB roles based on the configuration.
Follow the procedure for the authorization type that you selected when configuring OIDC authentication:
Group Membership
If you selected the Group Membership authorization type, follow these steps to create a custom role that grants authorization based on IdP user group membership:
Navigate to the MongoDB Roles tab for your deployment.
Select the organization that contains your project from the Organizations menu in the navigation bar.
Select your project from the Projects menu in the navigation bar.
Click Deployment in the sidebar.
Click the Security tab.
Click the MongoDB Roles tab.
Create the OIDC role.
Enter the following fields:
FieldNecessityDescriptionIdentifier
Required
In the Database box, enter
admin.In the Name box, enter your OIDC IdP configuration name and the group name from your external identity provider, separated by a slash (
/):{configuration_name}/{group_name}Inherits From
Optional
A list of role name and database pairs. The format for these pairs are
roleName@dbName.Authentication Restrictions
Optional
A list of IP addresses or CIDR notations that you want to restrict from your IdP.
Privilege Actions by Resource
Optional
Actions permitted on the resource.
To learn more, see Privilege Actions.
Click Add Role.
User ID
If you selected the User ID authorization type, create a new user to grant an individual user authorization:
Navigate to the MongoDB Users tab for your deployment.
Select the organization that contains your project from the Organizations menu in the navigation bar.
Select your project from the Projects menu in the navigation bar.
Click Deployment in the sidebar.
Click the Security tab.
Click the MongoDB Users tab.
Add the OIDC user.
Note
Before you add users, ensure that you've created any roles that you want to assign to the users.
Complete the user account fields:
FieldDescriptionIdentifier
In the first field, enter the
$externaldatabase.In the second field, enter a username using your OIDC IdP configuration name and the user principal claim from your configuration separated by a slash (
/):{configuration_name}/{user_principal_claim}
Roles
Enter any available user-defined roles and built-in roles into this box. The combo box provides a list of existing roles when you click in it.
Authentication Restrictions
Click Add Entry.
Add one or more IP addresses and/or CIDR blocks in either the Client Source or Server Address boxes. Separate multiple addresses or blocks with commas.
Client Source restricts which addresses this user can authenticate and use the given roles.
Server Address restricts the addresses this user can authenticate and has the given roles.
Click Save.
To add another entry, click Add Entry.
Click Add User.
Connect to MongoDB with Workforce Identity Federation
Use mongosh or Compass to connect an app to MongoDB with Workforce Identity Federation authentication.
Manage an Existing Workforce Identity Federation Configuration
To manage your Workforce Identity Federation configuration, you can perform these actions.
Revoke JSON Web Key Sets (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 the JSON Web Key Sets cached in MongoDB nodes:
Navigate to the Security Settings dialog for your deployment.
If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.
Click the Security tab.
Click the Settings tab.
Edit a Configuration
To edit your Workforce Identity Federation configuration:
Navigate to the Security Settings dialog for your deployment.
Select the organization that contains your project from the Organizations menu in the navigation bar.
Select your project from the Projects menu in the navigation bar.
Cick Deployment in the sidebar.
Click the Security tab.
Click the Settings tab.
Delete a Configuration
To delete your Workforce Identity Federation configuration:
Navigate to the Security Settings dialog for your deployment.
Select the organization that contains your project from the Organizations menu in the navigation bar.
Select your project from the Projects menu in the navigation bar.
Click Deployment in the sidebar.
Click the Security tab.
Click the Settings tab.