你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 Azure Cosmos DB for MongoDB vCore 群集配置Microsoft Entra ID 身份验证

2025-06-09
适用于: ✅ MongoDB (vCore)

本文介绍如何为 Azure Cosmos DB for MongoDB vCore 配置 Microsoft Entra ID 身份验证。本指南中的步骤配置现有 Azure Cosmos DB for MongoDB vCore 群集，以使用 Microsoft Entra ID 身份验证和人类标识（当前登录的帐户）。 Microsoft Entra ID 身份验证允许使用组织的现有标识安全无缝地访问数据库。本指南介绍设置身份验证、注册用户或服务主体以及验证配置的步骤。

先决条件

现有的 Azure Cosmos DB for MongoDB (vCore) 群集。

Azure Cloud Shell 中最新版本的 Azure CLI。
- 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

获取登录标识元数据

首先，获取当前已登录身份的唯一标识符。

使用 az ad signed-in-user 获取当前登录帐户的详细信息。
```
az ad signed-in-user show
```

该命令将输出包含各种字段的 JSON 响应。

{
  "@odata.context": "<https://graph.microsoft.com/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>"
}

记录 id 属性的值。此属性是主体的唯一标识符，有时称为 主体 ID。在接下来的步骤中将使用此值。

配置现有群集以进行身份验证

创建 Azure Cosmos DB for MongoDB vCore 群集时，群集默认配置为本机身份验证。使用 Azure CLI 配置现有群集以支持Microsoft Entra ID 身份验证。然后，将群集配置为将当前用户映射到您的已登录标识。

现在，使用 authConfig 从现有群集中获取 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

观察输出。如果未配置 Microsoft Entra ID 身份验证，输出中仅包含数组 allowedModes 中的 NativeAuth 值。
```
{
  "allowedModes": [
    "NativeAuth"
  ]
}
```

然后，使用 HTTP PATCH 操作来更新现有群集，通过将 MicrosoftEntraID 的值添加到 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

小窍门

如果使用 Azure Cloud Shell，可以直接将文件上载/下载到 shell。有关详细信息，请参阅 Azure Cloud Shell 中的托管文件。

此外，如果希望直接使用 az restAzure REST API，请使用以下替代命令：

az rest \
    --method "PUT" \
    --url "https://management.azure.com/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"]}}}'

再次使用 az resource show 验证配置是否成功，并观察整个群集的配置，其中包括 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"
      ]
    },
    ...
  },
  ...
}

使用 az resource create 创建一个新的 Microsoft.DocumentDB/mongoClusters/users 类型的资源。通过将父群集的名称与您的身份的主体 ID连接起来来生成资源的名称。

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

小窍门

例如，如果父资源已命名 example-cluster ，并且主体 ID 为 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb，则资源的名称为：

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

此外，如果要注册服务主体（如托管标识），则会将 identityProvider.properties.principalType 属性的值替换为 ServicePrincipal。

最后，如果希望直接使用 az restAzure REST API，请使用以下替代命令：

az rest \
    --method "PUT" \
    --url "https://management.azure.com/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"}]}}'

注释

Microsoft Entra ID 用户添加到群集后，将成为同一群集上已定义的本机 DocumentDB 用户之外的附加用户。使用至少一个内置本机 DocumentDB 用户创建 Azure Cosmos DB for MongoDB vCore 群集。完成群集预配后，可以添加更多本机 DocumentDB 用户。

连接至群集

可以使用首选语言的驱动程序中的连接 URI 或自定义设置对象连接到群集。在任一选项中，必须将方案设置为 mongodb+srv 连接到群集。主机位于*.global.mongocluster.cosmos.azure.com或*.mongocluster.cosmos.azure.com域，具体取决于使用的是当前群集还是全局读写终结点。 +srv 方案和 *.global.* 主机可确保客户端在多群集配置中动态连接到适当的可写群集，即使发生区域交换操作，也是如此。在单群集配置中，可以不分青红皂白地使用任一主机。

还必须启用 tls 设置。其余建议的设置是最佳实践配置。

选项	价值
方案	`mongodb+srv`
主机	`<cluster-name>.global.mongocluster.cosmos.azure.com` 或 `<cluster-name>.mongocluster.cosmos.azure.com`
`tls`	`true`
`authMechanism`	`MONGODB-OIDC`
`retrywrites`	`false`
`maxIdleTimeMS`	`120000`

Azure 门户
Node.js
Python
C#

在 Azure 门户的群集属性页上的 “设置”下，打开 连接字符串。 “连接字符串”页包含群集上启用的身份验证方法的连接字符串。 Microsoft Entra ID 连接字符串位于 “Microsoft Entra ID ”部分中。

全球

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

群集

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.windows.net/.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.windows.net/.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.windows.net/.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);
    }
}

Microsoft Azure Cosmos DB for MongoDB vCore 中的 Entra ID 身份验证概述
检查 Azure Cosmos DB for MongoDB vCore 中 Microsoft Entra ID 的局限性
使用控制台应用程序进行连接

通过

为 Azure Cosmos DB for MongoDB vCore 群集配置Microsoft Entra ID 身份验证

先决条件

获取登录标识元数据

配置现有群集以进行身份验证

连接至群集

相关内容

反馈

其他资源