To configure Workforce Identity Federation with OIDC, register your OIDC application with an external IdP, such as Okta or Microsoft Entra ID. This ensures secure authentication and facilitates user management.
About this Task
Workforce Identity Federation uses OIDC. You can use any external IdP that supports the OIDC standard.
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.
Note
Workforce Identity Federation supports only JWT for authentication. It doesn't support opaque access tokens.
The following procedures provide detailed configuration instructions for Microsoft Entra ID and Okta, and generic configuration instructions for other external IdPs.
Before you Begin
To use Okta as an IdP, you must have an Okta account.
To use Microsoft Entra ID as an IdP, you must have a Microsoft Azure account.
To use Microsoft AD FS as an IdP, you must have an AD FS server that is joined to an Active Directory domain and has a publicly trusted SSL certificate.
Steps
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
MongoDB - Workforce
Supported Account Types
Accounts in this organizational directory only (single tenant)
Redirect URI
- Public client/native (mobile & desktop)
- To access clusters using MongoDB Compass and MongoDB Shell, set the Redirect URI tohttp://localhost:27097/redirect.Click 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 requestedAccessTokenVersion 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 the MongoDB oidcIdentityProviders parameter:
Microsoft Entra ID UI | MongoDB oidcIdentityProviders Parameter Field |
|---|---|
Application (client) ID |
|
OpenID Connect metadata document (without /.well-known/openid-configuration) |
|
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.
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.
(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.