Set up Workload Identity Federation with OAuth 2.0

Register an application.

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	Cloud Manager Database - Workload
   Supported Account Types	Accounts in this organizational directory only (single tenant)
   Redirect URI	Web

(Optional) Add groups claim.

It is a best practice to use service principal identifiers as MongoDB user identifiers while defining access rights in Cloud 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.

Enable an Application ID URI.

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 Cloud Manager and all MongoDB drivers require this value for Workload Identity Federation configuration.

Update the manifest.

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.

Remember metadata.

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 Cloud Manager Configuration Properties that these Microsoft Entra ID UI values map to.

Navigate to the Security Settings dialog for your deployment.

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.

Optional: Specify the TLS Settings.

Choose the authentication mechanism.

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

Create a new OIDC IdP configuration.

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.

Enter the following settings.

Click Save Configuration.

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

Click Save Settings.

Click Review & Deploy to review your changes.

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

Navigate to the Security Settings dialog for your deployment.

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.

Optional: Specify the TLS Settings.

Choose the authentication mechanism.

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

Create a new OIDC IdP configuration.

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.

Enter the following settings.

Click Save Configuration.

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

Click Save Settings.

Click Review & Deploy to review your changes.

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

Navigate to the MongoDB Users tab for your deployment.

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.

Click Add New User.

Add the OIDC user.

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

2. Click Add User.

Click Review & Deploy to review your changes.

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

Navigate to the MongoDB Roles tab for your deployment.

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.

Click Add New Role.

Create the OIDC role.

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.