Docs Menu

Docs Home → MongoDB Cloud Manager

Enable OIDC Authentication for your Cloud Manager Project

On this page

  • Configure An External Identity Provider Application
  • Register a new application for Cloud Manager.
  • Set the Redirect URL value to http://localhost:27097/redirect.
  • Add or enable groups claim.
  • Optional: Allow refresh tokens if you want MongoDB clients to refresh the tokens for a better user experience.
  • Optional: Configure access token lifetime (exp claim) to align with your database connection session time.
  • Configure Microsoft Entra ID as an Identity Provider
  • Prerequisites
  • Procedures
  • Configure OIDC Authentication
  • Configure OIDC Authorization
  • Revoke JWKS

Cloud Manager enables you to configure the Authentication Mechanisms that all clients, including the Cloud Manager Agents, use to connect to your MongoDB deployments. You can enable multiple authentication mechanisms for each of your projects, but you must choose only one mechanism for the Agents.

MongoDB Enterprise allows authentication using OIDC. To authenticate with OIDC, you must first register your OIDC or OAuth application with an IdP that supports OIDC standard, such as as Microsoft Entra ID, Okta, and Ping Identity.

Configure An External Identity Provider Application

OIDC application registration steps can vary based on your IdP. Ensure that you complete the following items during your registration process:

1

Register a new application for Cloud Manager.

Make sure to select public client/native application as the client type.

2

Set the Redirect URL value to http://localhost:27097/redirect.

3

Add or enable groups claim.

This assures that your access tokens contain the group membership information of the user authenticating. MongoDB uses the values sent in groups claim for authorization.

4

Optional: Allow refresh tokens if you want MongoDB clients to refresh the tokens for a better user experience.

5

Optional: Configure access token lifetime (exp claim) to align with your database connection session time.

Once you register your application, save the issuer, clientId and audience values to use in the next stage of the OIDC IdP configuration.

Configure Microsoft Entra ID as an Identity Provider

To register your OIDC or OAuth application with Microsoft Entra ID:

1

Register an application.

  1. Navigate to App registrations.

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

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

  4. Click New registration.

  5. Apply the following values.

    Field
    Value
    Name
    CM Database - OIDC
    Supported Account Types
    Accounts in this organizational directory only (single tenant)
    Redirect URI
    - Public client/native (mobile & desktop)
    - http://localhost:27097/redirect

  6. Click Register.

To learn more about registering an application, see Azure Documentation.

2

Add a group claim.

  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

Add a user identifier claim to the access token.

  1. Click Add optional claim.

  2. In the Add optional claim modal, select Access.

  3. Select a claim that carries a user identifier that you can refer to in MongoDB access logs such as an email.

  4. Click Add.

  5. In the Microsoft Graph Permissions note, check the box, and click Add.

To learn more, see Azure Documentation.

4

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.

5

Remember metadata.

  1. In the left navigation, click Overview.

    Copy the Application (client) ID value.

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

Microsoft Entra ID UI
Cloud Manager Configuration Property
Application (client) ID
Client ID
Audience
OpenID Connect metadata document (without /.well-known/openid-configuration)
Issuer URI.

Prerequisites

To enable OIDC authentication, you must:

  • Use mongosh 1.9.1 or later.

  • Use MongoDB 7.0 or later.

  • Configure at least one other authentication mechanism with MongoDB Agent.

    Note

    The MongoDB Agent cannot connect to your cluster via OIDC. You must enable an additional 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

Note

If you want to reset Authentication and TLS settings for your project, first unmanage any MongoDB deployments that Cloud Manager manages in your project.

Configure OIDC Authentication

1

Navigate to the Security Settings dialog for your deployment.

  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.

  1. Click the Security tab.

  2. Click the Settings tab.

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

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

Note

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.

Client Certificate Mode

Select if client applications or MongoDB Agents must present a TLS certificate when connecting to a 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.

TLS is not required for use with Federated Auth (OIDC) authentication.

3

Choose the authentication mechanism.

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

4

Configure the OIDC Authorization Settings.

Provide the following values:

Setting
Necessity
Value
Audience
Required
Specify who your OIDC provider intends the token for.
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.
Client ID
Required
Unique identifier for your registered application. Enter the clientId value from the app you registered with OIDC IdP.
Requested Scopes
Optional

Tokens that give users permission to request data from the authorization endpoint.

For each additional scope you want to add, click Add more scopes.

User Claim
Optional

The identifier of the claim that includes the user principal identity. Accept the default value unless your IdP uses a different claim.

Default: sub

Groups Claim
Optional

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

5

Click Save Settings.

6

Click Review & Deploy to review your changes.

7

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

Configure OIDC Authorization

MongoDB does not explicitly create database users for OIDC. It maps OIDC users to MongoDB roles based on their groups.

To create a database role for an OIDC group:

1

Navigate to the MongoDB Roles tab for your deployment.

  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 MongoDB Roles tab.

2

Click Add New Role.

3

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 projectId and group name from your IdP separated by a slash /:

    {projectId}/{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.

  2. Click Add Role.

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:

1

Navigate to the Security Settings dialog for your deployment.

  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

Revoke your JWKS token.

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

  2. Click the REVOKE JWKS button.

    Note

    This button is idle if there is no IdP configured.

  3. In the Revoke JWKS tokens? modal, click Revoke.

MongoDB Cloud Manager →

On this page