Set up Workload Identity Federation with OAuth 2.0
On this page
- How it Works
- Built-in Authentication
- Callback Authentication
- Required Access
- Prerequisites
- Procedures
- Configure An External Identity Provider Application
- Configure Workload Identity Federation Authentication
- Configure OIDC Authorization
- Connect an Application to MongoDB with Workload Identity Federation
- Manage an Existing Workload Identity Federation Configuration
- Revoke JWKS
- Edit a Configuration
- Delete a Configuration
Workload Identity Federation lets your applications access MongoDB Ops Manager deployments using external programmatic identities such as Azure Service Principals, Azure Managed Identities and Google Service Accounts.
How it Works
Workload Identity Federation allows your applications access to MongoDB deployments with OAuth 2.0 access tokens. The access tokens can be issued by any external Identity Provider including Azure Entra ID and Google Cloud Platform. Ops Manager stores the user identifiers and privileges, but not the secrets. This authentication mechanism for your applications is only supported by certain MongoDB drivers.
MongoDB Drivers support two types of authentication flow for Workload Identity Federation: Built-in Authentication and Callback Authentication.
Built-in Authentication
You can use built-in authentication if you deploy your application on a supported infrastructure with a supported principal type. Your application can access Ops Manager deployments without supplying a password or manually requesting a JWT from your cloud provider's metadata service. Instead, your chosen MongoDB driver uses your existing principal identifier to request a JWT access token under the hood, which is then passed to the Ops Manager deployment automatically when your application connects.
For more implementation details, see your chosen driver's documentation.
Built-in Authentication Supported Infrastructure and Principal Types
Cloud Provider | Infrastructure Type | Principal Type |
---|---|---|
GCP | Compute Engine | GCP Service Accounts |
App Engine Standard Environment | ||
App Engine Flexible Environment | ||
Cloud Functions | ||
Cloud Run | ||
Google Kubernetes Engine | ||
Cloud Build | ||
Azure | Azure VM | Azure Managed Identities (User and System assigned) |
Callback Authentication
You can use callback authentication with any service supporting OAuth 2.0 access tokens. Workload Identity Federation calls a callback method, in which you can request the required JWT from your authorization server or cloud provider that you must pass when your application connects to Ops Manager with Workload Identity Federation.
Please review your chosen driver's documentation for additional implementation details.
Required Access
To configure Workload Identity Federation, you must have
Project Owner
access to Ops Manager.
Prerequisites
You must have the following:
MongoDB 7.0 or later.
At least one other authentication mechanism with MongoDB Agent configured.
Note
The MongoDB Agent cannot connect to your deployment via OIDC. You must enable an additional 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 configure Workload Identity Federation, complete the following steps:
Configure a Workload Identity Provider (one-time setup).
Grant external identities (user principals) or groups access.
Configure An External Identity Provider Application
Note
If you want to reset Authentication and TLS settings for your project, first unmanage any MongoDB deployments that Ops Manager manages in your project.
In order to access Ops Manager deployments with Azure Managed Identities or Azure Service Principals, you need to register an Azure Entra ID application. If you have an existing application registration for Workload (human user) access, we recommended that you register a separate application for Workload access.
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.
FieldValueNameOps Manager Database - WorkloadSupported Account TypesAccounts in this organizational directory only (single tenant)Redirect URIWeb
(Optional) Add groups claim.
It is a best practice to use service principal identifiers as MongoDB user identifiers while defining access rights in Ops Manager. If you plan to use this common approach, skip this step. However, if you prefer to use group identifiers such as Microsoft Entra ID Security Group identifier instead, you can set groups claim in your application registration with below steps.
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, ensure that you only select Group ID.
When you select Group Id, Azure sends the security group's Object ID.
Click Add.
To learn more about adding a group claim, see Azure Documentation.
Enable an Application ID URI.
Navigate to Expose an API in the left sidebar and enable Application ID URI.
Enable an Application ID URI.
Keep the default Application ID URI assigned by Azure, which is
<application_client_id>
. Copy and store this value, as Ops Manager and all MongoDB drivers require this value for Workload Identity Federation configuration.
Update the manifest.
In the Manage section of the left navigation, click Manifest.
Update the accessTokenAcceptedVersion from
null
to2
.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.Click Save.
To learn more about adding an optional claim, see Azure Documentation.
Remember metadata.
In the left navigation, click Overview.
In the top navigation, click Endpoints.
Copy the OpenID Connect metadata document value without the
/.well-known/openid-configuration
part.You can also retrieve this value by following the OpenID Connect metadata document URL and copying the value for
issuer
.
The following table shows what Ops Manager Configuration Properties that these Microsoft Entra ID UI values map to.
Microsoft Entra ID UI | Ops Manager Configuration Property |
---|---|
OpenID Connect metadata document (without /.well-known/openid-configuration) | Issuer URI. |
Application ID URI (<Application ID>) | Audience |
You don't need to make any configuration changes in your GCP account.
Configure Workload Identity Federation Authentication
Note
Workload Identity Federation supports only JWT for authentication. It doesn't support opaque access tokens.
To configure a Workload Identity Federation Identity Provider with Azure Entra ID in Ops Manager:
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:
NoteAfter 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
/.wellknown/open-id-configuration endpoint. |
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. |
Authorization Type | Required | Select It is more common to use |
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: |
To configure a Workload Identity Federation Identity Provider with GCP in Ops Manager:
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:
NoteAfter saving the configuration, you can't edit the configuration name. |
Issuer URI | Required | Enter the URI https://accounts.google.com . |
Audience | Required | Specify any custom value. Audience is used while calling MongoDB drivers. |
Authorization Type | Required | Select It is more common to use |
Customize User Claim | Required | Don't modify the default value, Default: |
Configure OIDC Authorization
MongoDB does not explicitly create database users for OIDC. It maps OIDC users to MongoDB roles based on the configuration.
Select a tab depending on the authorization type that you selected when configuring OIDC authentication.
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:
FieldDescriptionIdentifierIn the first field, enter the
$external
database.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}
RolesEnter 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 RestrictionsClick 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.
If you selected the Group Membership
authorization type,
complete the following 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:
FieldNecessityDescriptionIdentifierRequiredIn 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 FromOptionalA list of role name and database pairs. The format for these pairs areroleName@dbName
.Authentication RestrictionsOptionalA list of IP addresses or CIDR notations that you want to restrict from your IdP.Privilege Actions by ResourceOptionalActions permitted on the resource.
To learn more, see Privilege Actions.
Click Add Role.
Connect an Application to MongoDB with Workload Identity Federation
Use the following MongoDB Drivers to connect an application to MongoDB with Workload Identity Federation authentication:
Manage an Existing Workload Identity Federation Configuration
To manage your Workload Identity Federation configuration, you can perform the following actions.
Revoke 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 your JSON Web Key Sets (JWKS) 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 Workload 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 Workload 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.