Docs Menu
Docs Home
/
MongoDB Ops Manager
/ / /

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.

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.

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)

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.

To configure Workload Identity Federation, you must have Project Owner access to Ops Manager.

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.

To configure Workload Identity Federation, complete the following steps:

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

    1. Configure your external identity provider.

    2. Configure workload Identity Provider in Ops Manager.

  2. Grant external identities (user principals) or groups access.

  3. Authenticate to your Ops Manager deployment.

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.

1
  1. Navigate to App registrations.

    1. In your Azure portal account, search and click Microsoft Entra ID.

    2. In the Manage section of the left navigation, click App registrations.

  2. Click New registration.

  3. Apply the following values.

    Field
    Value
    Name
    Ops Manager Database - Workload
    Supported Account Types
    Accounts in this organizational directory only (single tenant)
    Redirect URI
    Web
2

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.

  1. Navigate to Token Configuration.

    In the Manage section of the left navigation, click Token Configuration.

  2. Click Add groups claim.

  3. 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.

  4. 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.

  5. Click Add.

    To learn more about adding a group claim, see Azure Documentation.

3
  1. Navigate to Expose an API in the left sidebar and enable Application ID URI.

  2. Enable an Application ID URI.

    1. 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.

4
  1. In the Manage section of the left navigation, click Manifest.

  2. Update the accessTokenAcceptedVersion from null to 2.

    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.

  3. Click Save.

To learn more about adding an optional claim, see Azure Documentation.

5
  1. In the left navigation, click Overview.

  2. 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.

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:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the Settings tab.

  6. 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.

2
Field
Action
MongoDB Deployment Transport Layer Security (TLS)
Toggle this slider to ON.
TLS CA File Path

The TLS Certificate Authority file is a .pem-format certificate file that contains the root certificate chain from the Certificate Authority. The MongoDB Agent uses this same Certificate Authority file to connect to every item in your deployment.

The encrypted private key for the .pem certificate file must be in PKCS #1 format. The MongoDB Agent doesn't support the PKCS #8 format.

Type the file path to the TLS Certificate Authority file on every host running a MongoDB process:

  • Type the file path on all Linux hosts in the first box.

  • Type the file path on all Windows hosts in the second box.

This enables the net.tls.CAFile setting for the MongoDB processes in the project.

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 .pem file that contains the root certificate chain from the Certificate Authority used to validate the certificate presented by a client establishing a connection. Specify the file name of the .pem file using relative or absolute paths. net.tls.clusterCAFile requires that net.tls.CAFile is set.

If you do not specify the net.tls.clusterCAFile, the cluster uses the .pem file specified in the net.tls.CAFile option.

net.tls.clusterCAFile lets you use separate Certificate Authorities to verify the client-to-server and server-to-client portions of the TLS handshake.

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:

Optional
Every client may present a valid TLS certificate when connecting to MongoDB deployments. MongoDB Agents might use TLS certificates if you don't set the mongod tlsMode to None.
Required
Every MongoDB deployment in this project starts with TLS-encrypted network connections. All Agents must use TLS to connect to any MongoDB deployment.
3

In the MongoDB Deployment Authentication Mechanism section, select Federated Auth (OIDC).

4
  1. In the OIDC Connection and Authorization (Required for OIDC) section, click + OIDC IdP Configuration.

  2. In the OIDC Protocol Settings dialog box, select Workload Identity Federation.

5
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:

  • alphanumeric characters (combination of a to z and 0 to 9)

  • hyphens (-)

  • underscores (_)

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 /.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 Group Membership to grant authorization based on IdP user group membership, or select User ID to grant an individual user authorization.

It is more common to use User ID for application access.

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: sub

Customize Group Claim
Required

Required if you select Group Membership as the authorization type. The identifier of the claim that includes the principal's IdP user group membership information. Accept the default value unless your IdP uses a different claim, or you need a custom claim.

Default: groups

6

Ops Manager saves the configuration and lists it in the OIDC Connection and Authorization (Required for OIDC) section.

7
8
9

Otherwise, click Cancel and you can make additional changes.

To configure a Workload Identity Federation Identity Provider with GCP in Ops Manager:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the Settings tab.

  6. 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.

2
Field
Action
MongoDB Deployment Transport Layer Security (TLS)
Toggle this slider to ON.
TLS CA File Path

The TLS Certificate Authority file is a .pem-format certificate file that contains the root certificate chain from the Certificate Authority. The MongoDB Agent uses this same Certificate Authority file to connect to every item in your deployment.

The encrypted private key for the .pem certificate file must be in PKCS #1 format. The MongoDB Agent doesn't support the PKCS #8 format.

Type the file path to the TLS Certificate Authority file on every host running a MongoDB process:

  • Type the file path on all Linux hosts in the first box.

  • Type the file path on all Windows hosts in the second box.

This enables the net.tls.CAFile setting for the MongoDB processes in the project.

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 .pem file that contains the root certificate chain from the Certificate Authority used to validate the certificate presented by a client establishing a connection. Specify the file name of the .pem file using relative or absolute paths. net.tls.clusterCAFile requires that net.tls.CAFile is set.

If you do not specify the net.tls.clusterCAFile, the cluster uses the .pem file specified in the net.tls.CAFile option.

net.tls.clusterCAFile lets you use separate Certificate Authorities to verify the client-to-server and server-to-client portions of the TLS handshake.

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:

Optional
Every client may present a valid TLS certificate when connecting to MongoDB deployments. MongoDB Agents might use TLS certificates if you don't set the mongod tlsMode to None.
Required
Every MongoDB deployment in this project starts with TLS-encrypted network connections. All Agents must use TLS to connect to any MongoDB deployment.
3

In the MongoDB Deployment Authentication Mechanism section, select Federated Auth (OIDC).

4
  1. In the OIDC Connection and Authorization (Required for OIDC) section, click + OIDC IdP Configuration.

  2. In the OIDC Protocol Settings dialog box, select Workload Identity Federation.

5
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:

  • alphanumeric characters (combination of a to z and 0 to 9)

  • hyphens (-)

  • underscores (_)

After 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 Group Membership to grant authorization based on IdP user group membership, or select User ID to grant an individual user authorization.

It is more common to use User ID for application access.

Customize User Claim
Required

Don't modify the default value, sub.

Default: sub

6

Ops Manager saves the configuration and lists it in the OIDC Connection and Authorization (Required for OIDC) section.

7
8
9

Otherwise, click Cancel and you can make additional changes.

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:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the MongoDB Users tab.

2
3

Note

Before you add users, ensure that you've created any roles that you want to assign to the users.

  1. Complete the user account fields:

    Field
    Description
    Identifier
    • In 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}
    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
    1. Click Add Entry.

    2. 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.

    3. Click Save.

    4. To add another entry, click Add Entry.

  2. Click Add User.

4
5

Otherwise, click Cancel and you can make additional changes.

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:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the MongoDB Roles tab.

2
3
  1. Enter the following fields:

    Field
    Necessity
    Description
    Identifier
    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.

  2. Click Add Role.

Use the following MongoDB Drivers to connect an application to MongoDB with Workload Identity Federation authentication:

To manage your Workload Identity Federation configuration, you can perform the following actions.

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:

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

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If it is not already displayed, click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the Settings tab.

2
  1. Scroll to the OIDC Connection and Authorization (Required for OIDC) section.

  2. Click the REVOKE JWKS button.

  3. In the Revoke JWKS tokens? dialog box, click Revoke.

To edit your Workload Identity Federation configuration:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Cick Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the Settings tab.

2
  1. Scroll to the OIDC Connection and Authorization (Required for OIDC) section.

  2. For the configuration that you want to edit, click the EDIT button.

  3. Make changes to the configuration.

3
4
5
6

Otherwise, click Cancel and you can make additional changes.

To delete your Workload Identity Federation configuration:

1
  1. Select the organization that contains your project from the Organizations menu in the navigation bar.

  2. Select your project from the Projects menu in the navigation bar.

  3. Click Deployment in the sidebar.

  4. Click the Security tab.

  5. Click the Settings tab.

2
  1. Scroll to the OIDC Connection and Authorization (Required for OIDC) section.

  2. For the configuration that you want to delete, click the REMOVE button.

  3. In the Removing OIDC IdP configuration? dialog box, click Remove.

Back

Workforce (Humans)