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

本文介绍如何为 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 Cli 中最新版本的 Azure CLI。

  • 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

获取登录标识元数据

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

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

   az ad signed-in-user show
   

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

   {
     "@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. 记录 id 属性的值。 此属性是主体的唯一标识符，有时称为 主体 ID。 在接下来的步骤中将使用此值。

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

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

1. 现在，使用 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
   

2. 观察输出。 如果未配置 Microsoft Entra ID 身份验证，输出中仅包含数组 NativeAuth 中的 allowedModes 值。

   {
     "allowedModes": [
       "NativeAuth"
     ]
   }
   

3. 然后，使用 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
   

   小窍门

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

   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. 再次验证 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"
         ]
       },
       ...
     },
     ...
   }
   

5. 使用 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":"root"}]}' \
       --latest-include-preview
   

   小窍门

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

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

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

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

   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":"root"}]}}'
   

连接至群集

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

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

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);
    }
}

相关内容

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