Docs Menu
Docs Home
/
MongoDB Atlas
/ / /

Set up Workload Identity Federation with OAuth 2.0

On this page

  • How it Works
  • Built-in Authentication
  • Callback Authentication
  • Procedures
  • Prepare Your External Identity Provider
  • Configure Workload Identity Federation Authentication
  • Add a Database User Using Workload Identity Federation Authentication
  • Connect an Application to MongoDB with Workload Identity Federation
  • Manage an Existing Workload Identity Federation Configuration
  • Revoke JWKS
  • Delete Workload Identity Federation Configuration

Workload Identity Federation lets your applications access MongoDB Atlas clusters using external programmatic identities such as Azure Service Principals, Azure Managed Identities and Google Service Accounts.

You can enable any number of workload identity providers for one or more organizations. When you enable a Workload Identity Provider in an Atlas organization, you can use it in all the projects in that organization for database access.

Atlas supports Workload Identity Federation on only dedicated clusters (M10 and above) running MongoDB version 7.0.11 and above, and only by selected drivers.

To learn more about implementing Workload Identity Federation access with your chosen driver, see the MongoDB Drivers documentation.

Workload Identity Federation allows your applications access to MongoDB clusters with OAuth2.0 access tokens. The access tokens can be issued by any external Identity Provider including Azure Entra ID and Google Cloud Platform. Atlas stores the user identifiers and privileges, but not the secrets. This authentication mechanism for your applications is only supported by MongoDB drivers. Other MongoDB tools like mongosh and MongoDB Compass don't support this authentication mechanism.

MongoDB Drivers support two types of authentication flow for Workload Identity Federation: Built-in Authentication and Callback 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 Atlas clusters 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 Atlas cluster automatically when your application connects.

For more implementation details, see your chosen Driver's documentation.

Built-in Authentication Supported IAM and Infrastructure

Cloud Provider
Infrastructure Type
IAM Type
GCP
Compute Engine
GCP Service Accounts
App Engine Standard Environment
App Engine Flexible Environment
Cloud Functions
Google Run
Google Kubernetes Engine
Cloud Build
Azure
Azure VM
Azure Managed Identities (User and System assigned)

You can use callback authentication with any service supporting OAuth2.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 Atlas with Workload Identity Federation.

Please review your chosen driver's documentation for additional implementation details.

To configure MongoDB's Workload Identity Federation:

  1. Configure Workload Identity Provider (one-time setup).

    1. Configure your external identity provider.

    2. Configure Workload Identity Provider in Atlas and enable it for your Atlas organization(s).

  2. Grant external identities (service principals) or groups access to MongoDB clusters.

  3. Connect your application to Atlas with a MongoDB Driver.

Note

Prerequisite

This procedure requires you to have Organization Owner access and assumes you have already configured your external IdP. To learn how to configure an IdP, see Configure An External Identity Provider Application.

You can configure Workload Identity Federation with Workload Identity Federation for database access in Atlas from the Federation Management Console.

Before you begin, you must have the following to add a database user:

  • Project Owner access

  • Workload Identity Federation configured in Atlas and enabled for your Organization.

1
2

In the Authentication Method section, select Federated Auth.

Note

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

3
  1. In the Select Identity Provider section, select a configured Workload Identity Provider.

  2. Specify either the user identifier or group identifier associated with your configured Workload 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.

  • For GCP users, this value maps to the Unique Id of your GCP Service Account.

4
5
  • If you added a user, click the Add User button.

  • If you added a group, click the Add Group button.

The following MongoDB Drivers support Workload Identity Federation authentication:

Note

This procedure is only for users who manage their own signing keys.

Don't use this feature to rotate your signing keys. When you rotate your Workload Identity Federation 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:

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

  2. Click the Organization Settings icon next to the Organizations menu.

2

In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.

3
4
5

After you click Revoke, MongoDB fetches the new keys through your JWKS endpoint. You must restart your clients (such as mongosh or Compass) after you revoke JWKS.

To delete your Workload Identity Federation configuration:

1
  1. Open the Management Console.

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

    2. Click the Organization Settings icon next to the Organizations menu.

    2

    In the Setup Federated Login or Manage Federation Settings section, click Visit Federation Management App.

  2. Click Organizations in the left sidebar.

  3. Click the organization that has Workload Identity Federation enabled.

  4. Click Disconnect under the Manage dropdown on the Workload Identity Federation card.

  5. In the Disconnect identity provider? modal, click Disconnect.

    When you disconnect an IdP, users who authenticate using the IdP lose access to Workload Identity Federation in the Atlas projects listed in the Project table.

2

Click Identity Providers in the left side navigation bar.

3
4

In the Delete Identity Provider? modal, click Delete.

← Workforce (Humans)
X.509 →