With Workload Identity Federation, your applications can access MongoDB Cloud 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 (GCP). Cloud Manager stores the user identifiers and privileges, but not the secrets. A limited set of MongoDB drivers offers this authentication mechanism for your applications.
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 app on a compatible infrastructure with a compatible principal type. Your app can access Cloud Manager deployments without supplying a password or manually requesting a JWT from your cloud provider's metadata service. Instead, your driver uses the existing principal identifier to request a JSON Web Token (JWT) access token. The driver passes the token to the Cloud Manager deployment when your app connects.
For more implementation details, see your 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 where you request the required JWT from your authorization server or cloud provider. You then pass the token to Cloud Manager with Workload Identity Federation when your app connects.
For more implementation details, review the documentation for your driver.
Required Access
To configure Workload Identity Federation, you must have Project Owner access to Cloud Manager.
Prerequisites
You must meet these prerequisites:
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 Cloud Manager doesn't manage Monitoring or Backup, you must manually configure them to use the alternative authentication mechanism.
Procedures
To configure Workload Identity Federation, follow these steps:
Configure a Workload Identity Provider (one-time setup).
Configure An External Identity Provider Application
Note
To reset Authentication and TLS settings for your project, first unmanage any MongoDB deployments that Cloud Manager manages in your project.
Configure Workload Identity Federation Authentication
Note
Workload Identity Federation supports only JWT for authentication. It doesn't support opaque access tokens.
Configure OIDC Authorization
MongoDB does not explicitly create database users for OIDC. It maps OIDC users to MongoDB roles based on the configuration.
Complete the procedure for the authorization type that you selected when configuring OIDC authentication.
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.
Group Membership
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:
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.
Connect an App to MongoDB with Workload Identity Federation
Use these MongoDB drivers to connect an app to MongoDB with Workload Identity Federation authentication:
Manage an Existing Workload Identity Federation Configuration
To manage your Workload 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:
In MongoDB Cloud Manager, go to the Security page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click Security under the Database heading.
The Security page displays.
Edit a Configuration
To edit your Workload Identity Federation configuration:
In MongoDB Cloud Manager, go to the Security page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click Security under the Database heading.
The Security page displays.
Delete a Configuration
To delete your Workload Identity Federation configuration:
In MongoDB Cloud Manager, go to the Security page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click Security under the Database heading.
The Security page displays.