Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
- 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.
- If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the
First, get the unique identifier for your currently signed-in identity.
Get the details for the currently logged-in account using
az ad signed-in-user
.az ad signed-in-user show
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>" }
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.
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.
Now, get the
authConfig
property from your existing cluster usingaz resource show
.az resource show \ --resource-group "<resource-group-name>" \ --name "<cluster-name>" \ --resource-type "Microsoft.DocumentDB/mongoClusters" \ --query "properties.authConfig" \ --latest-include-preview
Observe the output. If Microsoft Entra authentication isn't configured, the output includes only the
NativeAuth
value in theallowedModes
array.{ "allowedModes": [ "NativeAuth" ] }
Then, update the existing cluster with an HTTP
PATCH
operation by adding theMicrosoftEntraID
value toallowedModes
.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"]}}}'
Validate that the configuration was successful by using
az resource show
again and observing the entire cluster's configuration which includesproperties.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" ] }, ... }, ... }
Use
az resource create
to create a new resource of typeMicrosoft.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 wasaaaaaaaa-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 withServicePrincipal
.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.
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
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.