通过

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

Microsoft Entra ID 身份验证

Microsoft Entra ID 是一种基于云的标识解决方案，旨在管理Microsoft服务、资源和应用程序的用户访问和权限。 订阅 Microsoft 联机业务服务（如 azure Microsoft）的组织有权访问 Microsoft Entra ID。

Microsoft Entra ID 使你无需密码或密钥即可对 Azure AI 资源的请求进行身份验证。 而是通过将标识应用程序注册到 Microsoft Entra ID 平台来创建可靠的安全层。 通过此注册，标识应用程序能够向 Azure AI 资源 API 发出安全请求，从而与Microsoft标识平台建立信任关系。

本文介绍如何创建和使用 Microsoft Entra ID 标识应用程序对 Azure AI 资源的请求进行身份验证。 步骤如下：

先决条件

在开始之前，需要一个 Azure 帐户和一个 Azure AI 服务订阅。

重要

区域终结点 不支持Microsoft Entra 身份验证。

  • 已安装 curl 命令行工具。

  • PowerShell 7.* 版本（或类似的命令行应用程序。）：

  • 若要检查 PowerShell 版本，请键入与操作系统相关的以下命令：

    • Windows： Get-Host | Select-Object Version
    • macOS 或 Linux：$PSVersionTable

禁用密钥身份验证

若要使用 Microsoft Entra 身份验证，必须关闭基于密钥的（本地）身份验证。 禁用密钥访问后，Microsoft Entra ID 成为唯一的授权方法。 您的组织可以选择停用本地身份验证，并强制使用 Microsoft Entra 进行 Azure AI 资源的身份验证。 否则，可以按照以下步骤 PowerShell为特定资源禁用密钥身份验证：

  1. 连接到 Azure

     Connect-AzAccount

  2. 验证本地身份验证状态

     Get-AzCognitiveServicesAccount

  3. 检查属性 DisableLocalAuth 是否已设置为 $true （本地身份验证 已 禁用）

    Get-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name"

    如果 DisableLocalAuth 为空或被设为 False，则必须将其设置为 $true。

  4. “禁用本地身份验证”

    Set-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name" -DisableLocalAuth $true

可以再次检查一次，以确保使用 Get-AzCognitiveServicesAccount cmdlet 禁用本地身份验证。 True 值表示禁用本地身份验证。

使用 Microsoft Entra ID 注册标识应用程序

  1. 导航到 Azure 门户

  2. 在页面顶部的搜索框中输入 Microsoft Entra ID 。

    Azure 门户搜索框的屏幕截图。

  3. 从下拉菜单中选择Microsoft Entra ID服务。

    Azure 门户中Microsoft Entra ID 搜索结果的屏幕截图。

  4. 选择 Microsoft Entra ID 将在 Azure 门户中打开组织的概述页。

  5. 在左侧栏菜单 Manage 节点中，选择 App registrations。

    “管理”菜单中选择“应用注册”的屏幕截图。

  6. 从主窗口顶部的菜单中选择 New registration。

    页面主窗口中“新建注册”选择的屏幕截图。

  7. 完成应用程序注册字段：

    • 名称。 为应用程序选择一个名称。 在本例中，让我们使用 azure-ai-auth-app。
    • 支持的帐户类型。 指定谁可以使用该应用程序。
    • 重定向 URI。 此选择是可选的。 我们在此项目中跳过它。
    • 注册。 选择 Register 按钮并完成 App registration。

    有关注册应用程序的详细信息， 请参阅注册应用程序

  8. 注册完成后，将显示“ App's registration概述 ”窗格。 应用程序（客户端）ID，也称为client ID，值唯一标识Microsoft标识平台中的应用程序。

    “应用注册概述”页的屏幕截图。

  9. 在离开“应用注册概述”页之前，请将以下值复制并粘贴到安全方便的位置，例如 Windows 记事本：

    • Application (client) ID
    • Directory (tenant) ID

已完成应用注册。 接下来，我们将 客户端密码添加到 应用程序。

添加客户端机密凭据

客户端应用程序利用凭据来获取对 Web API 的访问权限。 这些凭据使应用程序能够在运行时独立进行身份验证，而无需用户交互（例如密钥输入）。 应用程序的客户端密码（应用程序密码）是应用程序在请求令牌时用来证明其标识的字符串。

  1. 从左侧导航菜单中选择“概述”页。

    Azure 门户中“应用注册概述”页的屏幕截图。

  2. 选择 Add a certificate or secret。

    在 Azure 门户中添加机密链接的屏幕截图。

  3. 下一步选择 New client secret。

    Azure 门户中新客户端机密按钮的屏幕截图。

  4. 在 Add a client secret 窗口中，添加说明、设置到期期限，然后选择 Add 按钮。

    “添加客户端机密设置”窗口的屏幕截图。

  5. 将客户端密码Value复制并粘贴到与Application (client) ID和Directory (tenant) ID相同的安全位置，例如 Windows 记事本。 客户端密码值只能在创建后立即查看。 请确保在离开该页面之前保存该机密。

    Azure 门户中已注册应用程序的客户端机密值位置的屏幕截图。

应用程序具有适当的身份验证凭据后，我们将添加应用程序访问 Azure AI Foundry 资源的权限。

添加 API 权限

接下来，让我们添加一个权限，允许应用程序以用户身份访问 Azure AI 服务（认知服务）API（包括 Azure AI Translator）。

  1. 在左侧导航菜单中，导航到 API permissions 然后从主窗口中进行选择 Add a permission 。

    Azure 门户中 API 权限视图的屏幕截图。

  2. 从出现的新窗口中选择 APIs my organization uses ，然后键入 Microsoft Cognitive Services 搜索栏中。

    “请求 API 权限搜索”窗口的屏幕截图。

  3. 从搜索结果中选择 Microsoft Cognitive Services 。

    • 在新窗口中，选择 Permissions 下的 Delegated permissions。

    • 选中 Access Cognitive Services API as organization users 复选框。

    • 选择 Add permissions。

      Azure 认知服务应用程序权限窗口的屏幕截图。

就是这样！ Microsoft Entra ID 应用程序的设置已完成。 接下来，翻译资源需要通过为翻译资源专门向应用程序添加角色分配来授予应用程序访问权限。 有关详细信息， 请参阅Azure 基于角色的访问控制

将认知服务用户角色分配给 Azure AI Translator 资源

基于角色的访问控制（Azure RBAC）是一种安全主体，可用于控制对 Azure 资源的访问。 可以使用 RBAC 授予对支持 Microsoft Entra 身份验证的任何资源的访问权限，在这种情况下，是您的 Azure AI Translator 实例。 若要向 Microsoft Entra ID 应用程序授予对 Translator 资源的访问权限，请使用 Azure 基于角色的访问控制 (Azure RBAC) 分配 Azure 角色。

  1. 在 Azure 门户中，导航到 Azure AI 翻译全局资源。

  2. 在左侧菜单中，选择 Access control (IAM)。

  3. 从主窗口中进行选择 Add role assignment 。

    “访问控制”窗口的屏幕截图。

  4. 在左侧导航名称菜单中，选择 Cognitive Services User 并选择 Next 按钮。

  5. 在 Add role assignment page上，分配对 User, group, or service principal 的访问权限。

  6. 选择 Select members。

    “添加角色分配成员”窗口的屏幕截图。

  7. 在打开的窗口中，在搜索框中键入已注册应用程序的名称（例如文本翻译应用）。 选择应用程序，然后选择 Select 按钮。

    Azure 门户中“选择成员”窗口的屏幕截图。

  8. 通过选择 Review + assign 按钮完成分配过程。

现在，我们已准备好使用应用程序进行测试，以获取 REST API 调用的安全令牌。

使用 OAuth 客户端凭据流获取访问令牌

访问令牌是一种安全令牌，旨在授权，代表经过身份验证的用户授予对特定资源的访问权限，并使客户端能够安全地调用受保护的 Web API。 在本例中，访问令牌授予 Microsoft Entra ID 注册的应用程序授权，以代表你访问翻译资源。

注释

  • 访问令牌的默认生存期未修复。
  • 颁发后，Microsoft标识平台会为其分配随机持续时间，范围为 60 到 90 分钟，平均为 75 分钟。
  • 当令牌过期时，对 /token 终结点重复此请求以获取新的访问令牌。
  • 刷新令牌不会随客户端凭据流一起颁发。 由于 client_id 和 client_secret（获取刷新令牌所需）已用于获取访问令牌，因此不需要在此上下文中使用刷新令牌。 有关详细信息， 请参阅OAuth 2.0 客户端凭据流

  1. 准备令牌请求。 需要从已注册的应用程序中获取以下值：

    • 应用程序（客户端）ID。 位于已注册应用程序的概述页上。 在注册身份应用程序的早期步骤中复制并存储。（#register-an-identity-application-with-microsoft-entra-id）。
    • 租户 ID。 位于已注册应用程序的概述页上。 在先前的注册身份应用步骤中已被复制和存储。
    • 客户端机密值。 在前面的“添加客户端机密凭据”步骤中复制和存储。

  2. 我们用 cURL 发出令牌请求。 代码如下：

    Linux 或 macOS

    curl -X POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client-id}" \
  -d "scope= https://cognitiveservices.azure.com/.default" \
  -d "client_secret={client-secret}" \
  -d "grant_type=client_credentials" |json_pp

    Windows

    curl -X POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "client_id={client-id}" ^
  -d "scope= https://cognitiveservices.azure.com/.default" ^
  -d "client_secret={client-secret}" ^
  -d "grant_type=client_credentials" |json

  3. 将请求 URL 中的 {tenant-id}, {client-id} 和 {client-secret} 替换为实际值。

    • |json_pp （macOS） 和 |json （Windows） 命令使用 cURL 实现 Json 的美化。

    • 在响应中获得了访问令牌。

  4. 将获取的访问权限保存在安全方便的位置，例如 Windows 记事本。

太好了！ 现在，让我们对 Azure 翻译器 AI API 进行 REST API 调用。

对 REST API 请求使用访问令牌身份验证

若要发出有效的 REST API 请求，需要以下值：

  • 翻译实例的标识。 可以通过两种方式提供该选项（选择一种）：

  • 从 Microsoft Entra ID 应用程序获取的 Microsoft Entra ID 访问令牌。

使用全局终结点

  1. 在 Azure 门户中导航到资源即时页。

    • 全局终结点位于Resource Management → Keys and Endpoint → Web API → Text translation下。

    • 在 ResourceID → Resource Management 下找到 Properties。

    • 资源 ID 格式：/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

      Azure 门户中资源 ID 值位置的屏幕截图。

  2. 将 {your-resource-ID} 替换为 Azure 门户的值，将 {access-token} 替换为上一步获取的值： 获取访问令牌。

    Linux 或 macOS

    curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=en" \
     -H "Authorization: Bearer {access-token}"\
     -H "Ocp-Apim-ResourceId: {your-resource-ID}" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hola'}]"

    Windows

    curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=en" ^
     -H "Authorization: Bearer {access-token}" ^
     -H "Ocp-Apim-ResourceId: {your-resource-id}" ^
     -H "Content-Type: application/json" ^
     -d "[{'Text':'Hola'}]"

使用自定义域终结点

自定义域终结点是一个 URL，格式为资源名称和主机名，可在 Azure 门户中使用。 创建翻译器资源时，字段中 Name 输入的值是终结点的自定义域名参数。 可以在“文档翻译”和“容器文本翻译”字段中找到自定义域终结点 URL。

Linux 或 macOS

curl -X POST "https://{your-custom-domain}.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=en" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d "[{'Text':'Hola'}]"

Windows

curl -X POST "https://{your-custom-domain}.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=en" ^
  -H "Authorization: Bearer {access-token}" ^
  -H "Content-Type: application/json" ^
  -d "[{'Text':'Hola'}]"

将 {your-custom-domain} 替换为 Azure 门户的值，将 {access-token} 替换为上一步获取的令牌， 获取访问令牌。

下面是 JSON 响应的示例：

[{"detectedLanguage":{"language":"es","score":1.0},"translations":[{"text":"Hello","to":"en"}]}]

干得不错！ 现在，你已了解如何使用 Microsoft Entra ID 对 Azure AI 资源的请求进行身份验证。