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) or a Microsoft Entra ID security principal such as managed identity. 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.
When you create an Azure Cosmos DB for MongoDB vCore cluster, cluster is configured to use native authentication by default. To enable authentication using Entra ID, turn on the Entra ID authentication method and add Entra ID users to the cluster.
Prerequisites
- An existing Azure Cosmos DB for MongoDB (vCore) cluster.
Get unique identifier for Entra ID user management
First, get the unique identifier used to manage Entra ID principals on the cluster.
Get the details for the currently logged-in account using az ad signed-in-user.
az ad signed-in-user show
Get the details for another account using az ad user show.
az ad user show --id kai@adventure-works.com
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.
Get friendly name using unique identifier
When you need to get a friendly name using unique identifier, follow these steps.
Get the details for another account using az ad user show.
az ad user show --id aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
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>"
}
Note the value of the mail and displayName properties.
Manage cluster authentication methods
Use the following steps to enable Microsoft Entra ID authentication method on your existing cluster. Then, add an Entra ID user mapped to your signed-in identity to the cluster. You can have native DocumentDB authentication only or native DocumentDB and Microsoft Entra ID authentication methods enabled on the cluster.
On the cluster sidebar, under Settings, select Authentication.
In Authentication methods section, select Native DocumentDB and Microsoft Entra ID to enable Microsoft Entra ID authentication.
Select Save to confirm the authentication method changes.
To enable Microsoft Entra ID on the cluster, update the existing cluster with an HTTP PATCH operation by adding the MicrosoftEntraID value to allowedModes in the authConfig property.
az resource patch \
--resource-group "<resource-group-name>" \
--name "<cluster-name>" \
--resource-type "Microsoft.DocumentDB/mongoClusters" \
--properties "{\"authConfig\":{\"allowedModes\":[\"MicrosoftEntraID\",\"NativeAuth\"]}}" \
--latest-include-preview
To disable Microsoft Entra ID authentication method on the cluster, update the existing cluster with an HTTP PATCH operation by overwriting the current values in allowedModes in the authConfig property with NativeAuth.
az resource patch \
--resource-group "<resource-group-name>" \
--name "<cluster-name>" \
--resource-type "Microsoft.DocumentDB/mongoClusters" \
--properties "{\"authConfig\":{\"allowedModes\":[\"NativeAuth\"]}}" \
--latest-include-preview
You can use the Azure REST API directly or wrapped into az rest from Azure CLI environment.
Use this command to add Microsoft Entra ID authentication method to the cluster:
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-07-01-preview" \
--body "{\"location\":\"<cluster-region>\",\"properties\":{\"authConfig\":{\"allowedModes\":[\"MicrosoftEntraID\",\"NativeAuth\"]}}}"
Use this command to remove Microsoft Entra ID authentication method from the cluster and leave only native DocumentDB authentication method enabled:
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-07-01-preview" \
--body "{\"location\":\"<cluster-region>\",\"properties\":{\"authConfig\":{\"allowedModes\":\"NativeAuth\"}}}"
View authentication methods enabled on the cluster
Follow these steps to see authentication methods currently enabled on the cluster.
On the cluster sidebar, under Settings, select Authentication.
In the Authentication methods section, check authentication methods currently enabled on the cluster.
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
Observe the output. If Microsoft Entra ID authentication isn't configured, the output includes only the NativeAuth value in the allowedModes array.
{
"authConfig": {
"allowedModes": [
"NativeAuth"
] }
}
If Microsoft Entra ID authentication is enabled on the cluster, the output includes both the NativeAuth and MicrosoftEntraID values in the allowedModes array.
{
"authConfig": {
"allowedModes": [
"NativeAuth",
"MicrosotEntraID"
] }
}
Use this command to check authentication methods currently enabled on the cluster:
az rest \
--method "GET" \
--url "https://management.chinacloudapi.cn/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview"
Observe the output. If Microsoft Entra ID authentication isn't configured, the output includes only the NativeAuth value in the allowedModes array.
{
"authConfig": {
"allowedModes": [
"NativeAuth"
] }
}
If Microsoft Entra ID authentication is enabled on the cluster, the output includes both the NativeAuth and MicrosoftEntraID values in the allowedModes array.
{
"authConfig": {
"allowedModes": [
"NativeAuth",
"MicrosotEntraID"
] }
}
Manage Entra ID users on the cluster
Follow these steps to add or remove administrative Entra ID users to cluster.
Select a cluster with Microsoft Entra ID authentication method enabled.
On the cluster sidebar, under Settings, select Authentication.
To add administrative Entra ID users:
In the Microsoft Entra ID authentication section, select +Add Microsoft Entra ID to open the side panel that allows to add Entra ID users and security principals to the cluster.
In the Select Microsoft Entra ID roles side panel, select one or more Entra ID users and confirm your choice by selecting Select.
Note
When administrative Microsoft Entra ID users are added to the cluster, their identifiers in aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb format not human readable names such as kai@adventure-works.com are added to the cluster.
Select Save to confirm the authentication method changes.
To remove administrative Entra ID users from the cluster:
Get Entra ID identifiers for the users to be removed from the cluster.
In the Microsoft Entra ID authentication section, select Remove next to the user's identifier to remove that user from the cluster.
Important
User is removed from the cluster right after Remove is selected.
Get the unique ID of the user or service principal that needs to be added to or removed from the cluster.
To add administrative Entra ID users, use az resource create. This command creates 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\":\"root\"}]}" \
--latest-include-preview
Tip
For example, if your parent resource is named example-cluster and your principal ID was aaaaaaaa-bbbb-cccc-1111-222222222222, 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.
To remove administrative Entra ID users, use az resource delete. This command deletes 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 delete \
--resource-group "<resource-group-name>" \
--name "<cluster-name>/users/<principal-id>" \
--resource-type "Microsoft.DocumentDB/mongoClusters/users" \
--latest-include-preview
Get the unique ID of the user or service principal that needs to be added to or removed from the cluster.
To add administrative Entra ID users to the cluster, use PUT Azure REST API call with this az rest 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-07-01-preview" \
--body "{\"location\":\"<cluster-region>\",\"properties\":{\"identityProvider\":{\"type\":\"MicrosoftEntraID\",\"properties\":{\"principalType\":\"User\"}},\"roles\":[{\"db\":\"admin\",\"role\":\"root\"}]}}"
Tip
For example, if your parent resource is named example-cluster and your principal ID was aaaaaaaa-bbbb-cccc-1111-222222222222, 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.
To remove administrative Entra ID users from the cluster, use DELETE Azure REST API call with this az rest command:
az rest \
--method "DELETE" \
--url "https://management.chinacloudapi.cn/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users/<principal-id>?api-version=2025-07-01-preview"
View Entra ID users on the cluster
When you view administrative users on a cluster, there's always one native built-in administrative user created during cluster provisioning and all administrative Entra ID users added to the cluster listed.
Follow these steps to see all administrative Entra ID users added to cluster.
Select a cluster with Microsoft Entra ID authentication method enabled.
On the cluster sidebar, under Settings, select Authentication.
In the Microsoft Entra ID authentication section, find the list of object IDs (unique identifiers) for the administrative Entra ID users added to the cluster.
To get friendly names using a unique identifier, follow these steps.
Use commands on the REST APIs tab to list administrative users on the cluster.
Use this command to list all administrative users on the cluster:
az rest \
--method "GET" \
--url "https://management.chinacloudapi.cn/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users?api-version=2025-07-01-preview"
Observe the output. The output includes an array of administrative user accounts on the cluster. This array has one built-in native administrative users and all administrative Entra ID user and service principals added to the cluster.
{
"id": "/subscriptions/<subscription-id>>/resourceGroups/<resource-group-name>>/providers/Microsoft.DocumentDB/mongoClusters/<cluser-name>>/users/<user's-unique-id>",
"name": "user's-unique-id",
"properties": {
"identityProvider": {
"properties": {
"entraTenant": "entra-tenant-id",
"principalType": "User"
},
"type": "MicrosoftEntraID"
},
...
"user": "user's-unique-id"
},
...
"type": "Microsoft.DocumentDB/mongoClusters/users"
}
If Microsoft Entra ID authentication is enabled on the cluster, the output includes both the NativeAuth and MicrosoftEntraID values in the allowedModes array.
{
"authConfig": {
"allowedModes": [
"NativeAuth",
"MicrosotEntraID"
] }
}
Note
An Azure Cosmos DB for MongoDB vCore cluster is created with one built-in native DocumentDB user. You can add more native DocumentDB users after cluster provisioning is completed. Microsoft Entra ID users added to the cluster are going to be in addition to native DocumentDB users defined on the same cluster.
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 cluster. 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 connection string 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 |
On the cluster properties page in the Azure portal, under Settings, open Connection strings. The Connection strings page contains connection strings for the authentication methods enabled on the cluster. Microsoft Entra ID connection strings are in the Microsoft Entra ID section.
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
const AzureIdentityTokenCallback = async (params: OIDCCallbackParams, credential: TokenCredential): Promise<OIDCResponse> => {
const tokenResponse: AccessToken | null = await credential.getToken(['https://ossrdbms-aad.database.chinacloudapi.cn/.default']);
return {
accessToken: tokenResponse?.token || '',
expiresInSeconds: (tokenResponse?.expiresOnTimestamp || 0) - Math.floor(Date.now() / 1000)
};
};
const clusterName: string = '<azure-cosmos-db-mongodb-vcore-cluster-name>';
const credential: TokenCredential = new DefaultAzureCredential();
const client = new MongoClient(
`mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, {
connectTimeoutMS: 120000,
tls: true,
retryWrites: true,
authMechanism: 'MONGODB-OIDC',
authMechanismProperties: {
OIDC_CALLBACK: (params: OIDCCallbackParams) => AzureIdentityTokenCallback(params, credential),
ALLOWED_HOSTS: ['*.azure.com']
}
}
);
class AzureIdentityTokenCallback(OIDCCallback):
def __init__(self, credential):
self.credential = credential
def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
token = self.credential.get_token(
"https://ossrdbms-aad.database.chinacloudapi.cn/.default").token
return OIDCCallbackResult(access_token=token)
clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>"
credential = DefaultAzureCredential()
authProperties = {"OIDC_CALLBACK": AzureIdentityTokenCallback(credential)}
client = MongoClient(
f"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/",
connectTimeoutMS=120000,
tls=True,
retryWrites=True,
authMechanism="MONGODB-OIDC",
authMechanismProperties=authProperties
)
string tenantId = "<microsoft-entra-tenant-id>";
string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";
DefaultAzureCredential credential = new();
AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
MongoClientSettings settings = MongoClientSettings.FromUrl(url);
settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
settings.Freeze();
MongoClient client = new(settings);
internal sealed class AzureIdentityTokenHandler(
TokenCredential credential,
string tenantId
) : IOidcCallback
{
private readonly string[] scopes = ["https://ossrdbms-aad.database.chinacloudapi.cn/.default"];
public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
{
AccessToken token = credential.GetToken(
new TokenRequestContext(scopes, tenantId: tenantId),
cancellationToken
);
return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
}
public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
{
AccessToken token = await credential.GetTokenAsync(
new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
cancellationToken
);
return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
}
}
Related content
