Configure Microsoft Entra ID authentication for an Azure Cosmos DB for MongoDB vCore cluster

Important

Microsoft Entra ID authentication in Azure Cosmos DB for MongoDB vCore is currently in preview. This preview version is provided without a service level agreement, and it isn't recommended for production workloads. Some features are unsupported or have limited capabilities.

In this article, you learn how to configure Microsoft Entra ID authentication for an Azure Cosmos DB for MongoDB vCore. The steps in this guide configure an existing Azure Cosmos DB for MongoDB vCore cluster to use Microsoft Entra ID authentication with your human identity (currently signed-in account). Microsoft Entra ID authentication enables secure and seamless access to your database by using your organization's existing identities. This guide goes through the steps to set up authentication, register users or service principals, and validate the configuration.

Prerequisites

  • An existing Azure Cosmos DB for MongoDB (vCore) cluster.
  • The latest version of the Azure CLI in Azure Cli.

    • If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the az login command.

Get signed-in identity metadata

First, get the unique identifier for your currently signed-in identity.

  1. Get the details for the currently logged-in account using az ad signed-in-user.

    az ad signed-in-user show
    
  2. The command outputs a JSON response containing various fields.

    {
      "@odata.context": "<https://microsoftgraph.chinacloudapi.cn/v1.0/$metadata#users/$entity>",
      "businessPhones": [],
      "displayName": "Kai Carter",
      "givenName": "Kai",
      "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "jobTitle": "Senior Sales Representative",
      "mail": "<kai@adventure-works.com>",
      "mobilePhone": null,
      "officeLocation": "Redmond",
      "preferredLanguage": null,
      "surname": "Carter",
      "userPrincipalName": "<kai@adventure-works.com>"
    }
    
  3. Record the value of the id property. This property is the unique identifier for your principal and is sometimes referred to as the principal ID. You use this value in the next series of steps.

Configure existing cluster for authentication

When you create an Azure Cosmos DB for MongoDB vCore cluster, the cluster is configured for native authentication by default. Use the Azure CLI to configure your existing cluster to support Microsoft Entra authentication. Then, configure the cluster to map a user to your signed-in identity.

  1. Now, get the authConfig property from your existing cluster using az resource show.

    az resource show \
        --resource-group "<resource-group-name>" \
        --name "<cluster-name>" \
        --resource-type "Microsoft.DocumentDB/mongoClusters" \
        --query "properties.authConfig" \
        --latest-include-preview
    
  2. Observe the output. If Microsoft Entra authentication isn't configured, the output includes only the NativeAuth value in the allowedModes array.

    {
      "allowedModes": [
        "NativeAuth"
      ]
    }
    
  3. Then, update the existing cluster with an HTTP PATCH operation by adding the MicrosoftEntraID value to allowedModes.

    az resource patch \
        --resource-group "<resource-group-name>" \
        --name "<cluster-name>" \
        --resource-type "Microsoft.DocumentDB/mongoClusters" \
        --properties '{"authConfig":{"allowedModes":["MicrosoftEntraID","NativeAuth"]}}' \
        --latest-include-preview
    

    Tip

    If you prefer to use the Azure REST API directly with az rest, use this alternative command:

    az rest \
        --method "PUT" \
        --url "https://management.chinacloudapi.cn/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-04-01-preview" \
        --body '{"location":"<cluster-region>","properties":{"authConfig":{"allowedModes":["MicrosoftEntraID","NativeAuth"]}}}'
    
  4. Validate that the configuration was successful by using az resource show again and observing the entire cluster's configuration which includes properties.authConfig.

    az resource show \
        --resource-group "<resource-group-name>" \
        --name "<cluster-name>" \
        --resource-type "Microsoft.DocumentDB/mongoClusters" \
        --latest-include-preview
    
    {
      ...
      "properties": {
        ...
        "authConfig": {
          "allowedModes": [
            "MicrosoftEntraID",
            "NativeAuth"
          ]
        },
        ...
      },
      ...
    }
    
  5. Use az resource create to create a new resource of type Microsoft.DocumentDB/mongoClusters/users. Compose the name of the resource by concatenating the name of the parent cluster and the principal ID of your identity.

    az resource create \
        --resource-group "<resource-group-name>" \
        --name "<cluster-name>/users/<principal-id>" \
        --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
        --location "<cluster-region>" \
        --properties '{"identityProvider":{"type":"MicrosoftEntraID","properties":{"principalType":"User"}},"roles":[{"db":"admin","role":"dbOwner"}]}' \
        --latest-include-preview
    

    Tip

    For example, if your parent resource is named example-cluster and your principal ID was aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb, the name of the resource would be:

    "example-cluster/users/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    

    Also, if you're registering a service principal, like a managed identity, you would replace the identityProvider.properties.principalType property's value with ServicePrincipal.

    Finally, if you prefer to use the Azure REST API directly with az rest, use this alternative command:

    az rest \
        --method "PUT" \
        --url "https://management.chinacloudapi.cn/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users/<principal-id>?api-version=2025-04-01-preview" \
        --body '{"location":"<cluster-region>","properties":{"identityProvider":{"type":"MicrosoftEntraID","properties":{"principalType":"User"}},"roles":[{"db":"admin","role":"dbOwner"}]}}'
    

Note

Microsoft Entra ID users added to the cluster are going to be in addition to native DocumentDB users defined on the same cluster. An Azure Cosmos DB for MongoDB vCore cluster is created with at least one built-in native DocumentDB user. You can add more native DocumentDB users after cluster provisioning is completed.

Connect to the cluster

You can connect to the cluster using either a connection URI or a custom settings object from the driver for your preferred language. In either option, the scheme must be set to mongodb+srv to connect to the replica set. The host is at either the *.global.mongocluster.cosmos.azure.com or *.mongocluster.cosmos.azure.com domain depending on whether you're using the current cluster or global read-write endpoint. The +srv scheme and the *.global.* host ensures that your client is dynamically connected to the appropriate writable cluster in a multi-cluster configuration even if a region swap operation occurs. In a single-cluster configuration, you can use either host indiscriminately.

The tls setting must also be enabled. The remaining recommended settings are best practice configuration settings.

Option Value
scheme mongodb+srv
host <cluster-name>.global.mongocluster.cosmos.azure.com or <cluster-name>.mongocluster.cosmos.azure.com
tls true
authMechanism MONGODB-OIDC
retrywrites false
maxIdleTimeMS 120000
  • Global

    mongodb+srv://<cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=MONGODB-OIDC&retrywrites=false&maxIdleTimeMS=120000
    
  • Cluster

    mongodb+srv://<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=MONGODB-OIDC&retrywrites=false&maxIdleTimeMS=120000
    

Limitations

The Microsoft Entra ID authentication feature has these current limitations:

  • This feature isn't supported on replica clusters.

  • This feature isn't supported on restored clusters.

  • This feature isn't supported with Mongo shell (mongosh) or MongoDB Compass.