使用 Microsoft Entra ID 配置无密钥身份验证

Azure AI Foundry 模型使用 Microsoft Entra ID 支持无密钥授权。 无密钥授权可增强安全性、简化用户体验、降低作复杂性，并为新式开发提供可靠的合规性支持。 对于采用安全且可缩放的标识管理解决方案的组织来说，它是一个不错的选择。

本文介绍如何在 Azure AI Foundry 模型中为推理配置 Microsoft Entra ID。

了解 Azure 中资源上下文中的角色

Microsoft Entra ID 采用基于角色的访问控制 (RBAC) 概念进行授权。 角色是管理对云资源的访问权限的核心。 角色本质上是一组权限，用于定义可在特定 Azure 资源上执行的操作。 通过为用户、组、服务主体或托管标识（统称为安全主体）分配角色，可以控制它们在 Azure 环境中对特定资源的访问权限。

若要分配角色，必须指定三个要素：安全主体、角色定义和范围。 此组合称为角色分配。 Azure AI Foundry 模型是 Azure AI 服务资源的一项功能，因此，分配给该特定资源的角色控制推理的访问。

可以识别两种不同类型的资源访问权限：

• 管理访问：与资源管理相关的操作。 它们通常更改资源的状态及其配置。 在 Azure 中，这些操作属于控制平面操作，可以通过 Azure 门户、Azure CLI 或使用基础结构即代码的方式执行。 示例包括创建新的模型部署、更改内容筛选配置、更改提供的模型版本或更改部署的 SKU。

• 开发人员访问：与资源消耗相关的操作。 例如，调用聊天补全 API。 但是，用户无法更改资源的状态及其配置。

在 Azure 中，始终使用 Microsoft Entra ID 执行管理操作。 认知服务参与者等角色允许你执行这些操作。 另一方面，开发人员操作可以使用访问密钥或/和 Microsoft Entra ID 来执行。 认知服务用户等角色允许你执行这些操作。

按照以下步骤配置开发人员对 Azure AI Foundry 模型的推理访问权限。

先决条件

若要完成本文，需要做好以下准备：

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 具有Microsoft.Authorization/roleAssignments/write和Microsoft.Authorization/roleAssignments/delete权限的帐户，例如基于管理员角色的访问控制。

• 若要分配角色，必须指定三个元素：

  • 安全主体：例如用户帐户。
  • 角色定义：认知服务用户角色。
  • 范围：Azure AI 服务资源。

• 如果要创建自定义角色定义而不是使用 认知服务用户 角色，请确保该角色具有以下权限：

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

为推理配置 Microsoft Entra ID

以下步骤将指导您如何设置 Microsoft Entra ID 用于推断：

1. 转到 Azure 门户 ，找到正在使用的 Azure AI Foundry （以前已知的 Azure AI 服务） 资源。 如果将 Azure AI Foundry 用于项目或中心，可以通过以下方式进入：

   1. 转到 Azure AI Foundry 门户。

   2. 在登陆页面上，选择“打开管理中心”。

   3. 转到“ 已连接资源 ”部分，选择要配置的 Azure AI Foundry（以前已知的 Azure AI 服务）资源的连接。 如果未列出，请选择“查看所有”以查看完整列表。

      

   4. 在“连接详细信息”部分的“资源”下，选择 Azure 资源的名称。 将打开一个新页面。

   5. 现在，可在 Azure 门户中管理资源本身的所有方面。

      

2. 在左窗格中，选择访问控制 (IAM)，然后选择添加>添加角色分配。

   

   提示

   使用“查看我的访问”选项来验证哪些角色已分配给你。

3. 在“作业函数角色”上，键入“认知服务用户”。 角色列表已被筛选掉。

   

4. 选择角色，然后选择“下一步”。

5. 在“成员”上，选择要向其授予访问权限的用户或组。 我们建议尽可能使用安全组，因为它们更易于管理和维护。

   

6. 选择“下一步”并完成向导。

7. 所选用户现在可以使用 Microsoft Entra ID 进行推理。

   提示

   请记住，Azure 角色分配可能需要最多五分钟的时间进行传播。 使用安全组时，添加或删除安全组中的用户会立即传播。

请注意，对于已经有密钥的用户来说，仍然可以通过密钥进行访问。 若要撤销密钥，请在 Azure 门户中的左侧导航中选择“资源管理”>“密钥和终结点”>“重新生成密钥1”和“重新生成密钥2”。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天完成模型：

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 时的凭据选项

DefaultAzureCredential 是一个有主见的有序认证机制序列，用于向 Microsoft Entra ID 进行身份验证。 每个身份验证机制都是一个派生自 TokenCredential 类的类，称为“凭据”。 在运行时，DefaultAzureCredential 尝试使用第一个凭据进行身份验证。 如果该凭据无法获取访问令牌，则会尝试序列中的下一个凭据，以此类推，直到成功获取访问令牌。 这样，应用就可在不同的环境中使用不同的凭据，而无需编写特定于环境的代码。

上述代码在本地开发工作站上运行时，它会在应用程序服务主体的环境变量或本地安装的开发人员工具（如 Visual Studio）中查找一组开发人员凭据。 在本地开发期间，两种方法都可用于对访问 Azure 资源的应用进行身份验证。

部署到 Azure 时，此代码也可以对访问 Azure 资源的应用进行身份验证。 DefaultAzureCredential 可以检索环境设置和托管标识配置，以自动向其他服务进行身份验证。

最佳做法

• 在生产环境中使用确定性凭据：强烈建议在生产环境中从 DefaultAzureCredential 迁移到以下确定性解决方案之一：

  • 特定的 TokenCredential 实现，例如 ManagedIdentityCredential。 有关选项，请参阅派生列表。
  • 针对运行应用的 Azure 环境优化的精简版 ChainedTokenCredential 实现。 ChainedTokenCredential 本质上创建了一个可接受的凭据选项的特定允许列表，例如用于生产的 ManagedIdentity 和用于开发的 VisualStudioCredential。

• 如果可能，为代码正在运行的 Azure 资源配置系统分配或用户分配的托管标识。 配置对这些特定标识的 Microsoft Entra ID 访问权限。

故障排除

在进行故障排除之前，请验证是否分配了正确的权限：

1. 转到 Azure 门户 ，找到正在使用的 Azure AI Foundry （以前已知的 Azure AI 服务） 资源。

2. 在左窗格中，选择 “访问控制”（IAM）， 然后选择“ 检查访问权限”。

3. 键入用于连接到服务的用户或身份的名称。

4. 验证 角色认知服务用户 是否已列出（或包含 先决条件中所述所需权限的角色）。

   重要

   所有者或参与者等角色不通过Microsoft Entra ID 提供访问权限。

5. 如果未列出，请在继续之前按照本指南中的步骤进行操作。

下表包含多个方案，可帮助对 Microsoft Entra ID 进行故障排除：

在项目中使用 Microsoft Entra ID

即使您的资源已配置 Microsoft Entra ID，您的项目仍可能使用密钥来调用资源的预测功能。 使用 Azure AI Foundry 操场时，会使用与项目所建立的连接相关联的凭据。

若要更改此行为，必须更新项目中的连接以使用 Microsoft Entra ID。 执行以下步骤：

1. 转到 Azure AI Foundry 门户。

2. 通过连接导航到使用 Azure AI Foundry（以前已知的 Azure AI 服务）资源的项目或中心。

3. 选择“管理中心”。

4. 转到“ 已连接资源 ”部分，选择要配置的 Azure AI Foundry（以前已知的 Azure AI 服务）资源的连接。 如果未列出，请选择“查看所有”以查看完整列表。

5. 在“连接详细信息”部分，选择“访问详细信息”旁边的编辑图标。

6. 在“身份验证”下，将值更改为 Microsoft Entra ID。

7. 选择“更新”。

8. 连接现已配置为使用 Microsoft Entra ID。

在资源中禁用基于密钥的身份验证

在实现了 Microsoft Entra ID 并且解决了所有使用该服务的应用程序中的兼容性或回退问题时，建议禁用基于密钥的身份验证。 仅当使用 Bicep/ARM 进行部署时，才能禁用基于密钥的身份验证。

Azure AI Foundry 模型使用 Microsoft Entra ID 支持无密钥授权。 无密钥授权可增强安全性、简化用户体验、降低作复杂性，并为新式开发提供可靠的合规性支持。 对于采用安全且可缩放的标识管理解决方案的组织来说，它是一个不错的选择。

本文介绍如何在 Azure AI Foundry 模型中为推理配置 Microsoft Entra ID。

了解 Azure 中资源上下文中的角色

Microsoft Entra ID 采用基于角色的访问控制 (RBAC) 概念进行授权。 角色是管理对云资源的访问权限的核心。 角色本质上是一组权限，用于定义可在特定 Azure 资源上执行的操作。 通过为用户、组、服务主体或托管标识（统称为安全主体）分配角色，可以控制它们在 Azure 环境中对特定资源的访问权限。

若要分配角色，必须指定三个要素：安全主体、角色定义和范围。 此组合称为角色分配。 Azure AI Foundry 模型是 Azure AI 服务资源的一项功能，因此，分配给该特定资源的角色控制推理的访问。

可以识别两种不同类型的资源访问权限：

• 管理访问：与资源管理相关的操作。 它们通常更改资源的状态及其配置。 在 Azure 中，这些操作属于控制平面操作，可以通过 Azure 门户、Azure CLI 或使用基础结构即代码的方式执行。 示例包括创建新的模型部署、更改内容筛选配置、更改提供的模型版本或更改部署的 SKU。

• 开发人员访问：与资源消耗相关的操作。 例如，调用聊天补全 API。 但是，用户无法更改资源的状态及其配置。

在 Azure 中，始终使用 Microsoft Entra ID 执行管理操作。 认知服务参与者等角色允许你执行这些操作。 另一方面，开发人员操作可以使用访问密钥或/和 Microsoft Entra ID 来执行。 认知服务用户等角色允许你执行这些操作。

按照以下步骤配置开发人员对 Azure AI Foundry 模型的推理访问权限。

先决条件

若要完成本文，需要做好以下准备：

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 具有Microsoft.Authorization/roleAssignments/write和Microsoft.Authorization/roleAssignments/delete权限的帐户，例如基于管理员角色的访问控制。

• 若要分配角色，必须指定三个元素：

  • 安全主体：例如用户帐户。
  • 角色定义：认知服务用户角色。
  • 范围：Azure AI 服务资源。

• 如果要创建自定义角色定义而不是使用 认知服务用户 角色，请确保该角色具有以下权限：

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• 安装 Azure CLI。

• 标识以下信息：

  • Azure 订阅 ID。

  • 您的 Azure AI Foundry（前称为 Azure AI Services）资源名称。

  • 部署了 Azure AI Foundry（以前称为 Azure AI 服务）资源的资源组。

为推理配置 Microsoft Entra ID

以下步骤将指导您如何设置 Microsoft Entra ID 用于推断：

1. 登录到 Azure 订阅：

   az login
   

2. 如果订阅超过一个，请选择资源所在的订阅：

   az account set --subscription "<subscription-id>"
   

3. 请设置以下环境变量，包括计划使用的 Azure AI Foundry（原称 Azure AI 服务）资源名称及其资源组。

   ACCOUNT_NAME="<ai-services-resource-name>"
   RESOURCE_GROUP="<resource-group>"
   

4. 获取资源的全名：

   RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")
   

5. 获取要向其分配权限的安全主体的对象 ID。 以下示例演示如何获取与以下对象关联的对象 ID：

   您自己的登录帐户：

   OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)
   

   安全组：

   OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)
   

   服务主体：

   OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)
   

6. 向服务主体分配“认知服务用户”角色（范围限定为资源）。 通过分配角色，将向服务主体授予对此资源的访问权限。

   az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
   

7. 所选用户现在可以使用 Microsoft Entra ID 进行推理。

   提示

   请记住，Azure 角色分配可能需要最多五分钟的时间进行传播。 添加或删除安全组中的用户会立即传播。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天完成模型：

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 时的凭据选项

DefaultAzureCredential 是一个有主见的有序认证机制序列，用于向 Microsoft Entra ID 进行身份验证。 每个身份验证机制都是一个派生自 TokenCredential 类的类，称为“凭据”。 在运行时，DefaultAzureCredential 尝试使用第一个凭据进行身份验证。 如果该凭据无法获取访问令牌，则会尝试序列中的下一个凭据，以此类推，直到成功获取访问令牌。 这样，应用就可在不同的环境中使用不同的凭据，而无需编写特定于环境的代码。

上述代码在本地开发工作站上运行时，它会在应用程序服务主体的环境变量或本地安装的开发人员工具（如 Visual Studio）中查找一组开发人员凭据。 在本地开发期间，两种方法都可用于对访问 Azure 资源的应用进行身份验证。

部署到 Azure 时，此代码也可以对访问 Azure 资源的应用进行身份验证。 DefaultAzureCredential 可以检索环境设置和托管标识配置，以自动向其他服务进行身份验证。

最佳做法

• 在生产环境中使用确定性凭据：强烈建议在生产环境中从 DefaultAzureCredential 迁移到以下确定性解决方案之一：

  • 特定的 TokenCredential 实现，例如 ManagedIdentityCredential。 有关选项，请参阅派生列表。
  • 针对运行应用的 Azure 环境优化的精简版 ChainedTokenCredential 实现。 ChainedTokenCredential 本质上创建了一个可接受的凭据选项的特定允许列表，例如用于生产的 ManagedIdentity 和用于开发的 VisualStudioCredential。

• 如果可能，为代码正在运行的 Azure 资源配置系统分配或用户分配的托管标识。 配置对这些特定标识的 Microsoft Entra ID 访问权限。

故障排除

在进行故障排除之前，请验证是否分配了正确的权限：

1. 转到 Azure 门户 ，找到正在使用的 Azure AI Foundry （以前已知的 Azure AI 服务） 资源。

2. 在左窗格中，选择 “访问控制”（IAM）， 然后选择“ 检查访问权限”。

3. 键入用于连接到服务的用户或身份的名称。

4. 验证 角色认知服务用户 是否已列出（或包含 先决条件中所述所需权限的角色）。

   重要

   所有者或参与者等角色不通过Microsoft Entra ID 提供访问权限。

5. 如果未列出，请在继续之前按照本指南中的步骤进行操作。

下表包含多个方案，可帮助对 Microsoft Entra ID 进行故障排除：

Azure AI Foundry 模型使用 Microsoft Entra ID 支持无密钥授权。 无密钥授权可增强安全性、简化用户体验、降低作复杂性，并为新式开发提供可靠的合规性支持。 对于采用安全且可缩放的标识管理解决方案的组织来说，它是一个不错的选择。

本文介绍如何在 Azure AI Foundry 模型中为推理配置 Microsoft Entra ID。

了解 Azure 中资源上下文中的角色

Microsoft Entra ID 采用基于角色的访问控制 (RBAC) 概念进行授权。 角色是管理对云资源的访问权限的核心。 角色本质上是一组权限，用于定义可在特定 Azure 资源上执行的操作。 通过为用户、组、服务主体或托管标识（统称为安全主体）分配角色，可以控制它们在 Azure 环境中对特定资源的访问权限。

若要分配角色，必须指定三个要素：安全主体、角色定义和范围。 此组合称为角色分配。 Azure AI Foundry 模型是 Azure AI 服务资源的一项功能，因此，分配给该特定资源的角色控制推理的访问。

可以识别两种不同类型的资源访问权限：

• 管理访问：与资源管理相关的操作。 它们通常更改资源的状态及其配置。 在 Azure 中，这些操作属于控制平面操作，可以通过 Azure 门户、Azure CLI 或使用基础结构即代码的方式执行。 示例包括创建新的模型部署、更改内容筛选配置、更改提供的模型版本或更改部署的 SKU。

• 开发人员访问：与资源消耗相关的操作。 例如，调用聊天补全 API。 但是，用户无法更改资源的状态及其配置。

在 Azure 中，始终使用 Microsoft Entra ID 执行管理操作。 认知服务参与者等角色允许你执行这些操作。 另一方面，开发人员操作可以使用访问密钥或/和 Microsoft Entra ID 来执行。 认知服务用户等角色允许你执行这些操作。

按照以下步骤配置开发人员对 Azure AI Foundry 模型的推理访问权限。

先决条件

若要完成本文，需要做好以下准备：

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 具有Microsoft.Authorization/roleAssignments/write和Microsoft.Authorization/roleAssignments/delete权限的帐户，例如基于管理员角色的访问控制。

• 若要分配角色，必须指定三个元素：

  • 安全主体：例如用户帐户。
  • 角色定义：认知服务用户角色。
  • 范围：Azure AI 服务资源。

• 如果要创建自定义角色定义而不是使用 认知服务用户 角色，请确保该角色具有以下权限：

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• 安装 Azure CLI。

• 标识以下信息：

  • Azure 订阅 ID。

关于本教程

本文中的示例基于 Azure-Samples/azureai-model-inference-bicep 存储库中包含的代码示例。 要在本地运行命令而无需复制或粘贴文件内容，请使用以下命令克隆存储库并转到你的编码语言所对应的文件夹：

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

此示例的文件位于以下位置：

cd azureai-model-inference-bicep/infra

了解资源

本教程可帮助你创建：

会使用以下资产创建这些资源：

1. 使用模板 modules/ai-services-template.bicep 描述你的 Azure AI Foundry（以前称为 Azure AI 服务）资源。

   modules/ai-services-template.bicep

   @description('Location of the resource.')
   param ___location string = resourceGroup().___location
   
   @description('Name of the Azure AI Services account.')
   param accountName string
   
   @description('The resource model definition representing SKU')
   param sku string = 'S0'
   
   @description('Whether or not to allow keys for this account.')
   param allowKeys bool = true
   
   @allowed([
     'Enabled'
     'Disabled'
   ])
   @description('Whether or not public endpoint access is allowed for this account.')
   param publicNetworkAccess string = 'Enabled'
   
   @allowed([
     'Allow'
     'Deny'
   ])
   @description('The default action for network ACLs.')
   param networkAclsDefaultAction string = 'Allow'
   
   resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
     name: accountName
     ___location: ___location
     identity: {
       type: 'SystemAssigned'
     }
     sku: {
       name: sku
     }
     kind: 'AIServices'
     properties: {
       customSubDomainName: accountName
       publicNetworkAccess: publicNetworkAccess
       networkAcls: {
         defaultAction: networkAclsDefaultAction
       }
       disableLocalAuth: allowKeys
     }
   }
   
   output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
   output id string = account.id
   

   提示

   请注意，此模板可以采用参数 allowKeys，当 false 时，将在资源中禁用密钥的使用。 此配置是可选的。

2. 使用模板 modules/role-assignment-template.bicep 描述 Azure 中的角色分配：

   modules/role-assignment-template.bicep

   @description('Specifies the role definition ID used in the role assignment.')
   param roleDefinitionID string
   
   @description('Specifies the principal ID assigned to the role.')
   param principalId string
   
   @description('Specifies the resource ID of the resource to assign the role to.')
   param scopeResourceId string = resourceGroup().id
   
   var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
   resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: roleAssignmentName
     properties: {
       roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
       principalId: principalId
     }
   }
   
   output name string = roleAssignment.name
   output resourceId string = roleAssignment.id
   

创建资源

在控制台中，执行以下步骤：

1. 定义主部署：

   deploy-entra-id.bicep

   @description('Location to create the resources in')
   param ___location string = resourceGroup().___location
   
   @description('Name of the resource group to create the resources in')
   param resourceGroupName string = resourceGroup().name
   
   @description('Name of the AI Services account to create')
   param accountName string = 'azurei-models-dev'
   
   @description('ID of the developers to assign the user role to')
   param securityPrincipalId string
   
   module aiServicesAccount 'modules/ai-services-template.bicep' = {
     name: 'aiServicesAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       accountName: accountName
       ___location: ___location
       allowKeys: false
     }
   }
   
   module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
     name: 'roleAssignmentDeveloperAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
       principalId: securityPrincipalId
     }
   }
   
   output endpoint string = aiServicesAccount.outputs.endpointUri
   

2. 登录到 Azure：

   az login
   

3. 确保你位于正确的订阅中：

   az account set --subscription "<subscription-id>"
   

4. 运行部署：

   RESOURCE_GROUP="<resource-group-name>"
   SECURITY_PRINCIPAL_ID="<your-security-principal-id>"
   
   az deployment group create \
     --resource-group $RESOURCE_GROUP \
     --securityPrincipalId $SECURITY_PRINCIPAL_ID
     --template-file deploy-entra-id.bicep
   

5. 该模板输出 Azure AI Foundry 模型终结点，可用于访问您已创建的任意模型部署。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天完成模型：

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 时的凭据选项

DefaultAzureCredential 是一个有主见的有序认证机制序列，用于向 Microsoft Entra ID 进行身份验证。 每个身份验证机制都是一个派生自 TokenCredential 类的类，称为“凭据”。 在运行时，DefaultAzureCredential 尝试使用第一个凭据进行身份验证。 如果该凭据无法获取访问令牌，则会尝试序列中的下一个凭据，以此类推，直到成功获取访问令牌。 这样，应用就可在不同的环境中使用不同的凭据，而无需编写特定于环境的代码。

上述代码在本地开发工作站上运行时，它会在应用程序服务主体的环境变量或本地安装的开发人员工具（如 Visual Studio）中查找一组开发人员凭据。 在本地开发期间，两种方法都可用于对访问 Azure 资源的应用进行身份验证。

部署到 Azure 时，此代码也可以对访问 Azure 资源的应用进行身份验证。 DefaultAzureCredential 可以检索环境设置和托管标识配置，以自动向其他服务进行身份验证。

最佳做法

• 在生产环境中使用确定性凭据：强烈建议在生产环境中从 DefaultAzureCredential 迁移到以下确定性解决方案之一：

  • 特定的 TokenCredential 实现，例如 ManagedIdentityCredential。 有关选项，请参阅派生列表。
  • 针对运行应用的 Azure 环境优化的精简版 ChainedTokenCredential 实现。 ChainedTokenCredential 本质上创建了一个可接受的凭据选项的特定允许列表，例如用于生产的 ManagedIdentity 和用于开发的 VisualStudioCredential。

• 如果可能，为代码正在运行的 Azure 资源配置系统分配或用户分配的托管标识。 配置对这些特定标识的 Microsoft Entra ID 访问权限。

故障排除

在进行故障排除之前，请验证是否分配了正确的权限：

1. 转到 Azure 门户 ，找到正在使用的 Azure AI Foundry （以前已知的 Azure AI 服务） 资源。

2. 在左窗格中，选择 “访问控制”（IAM）， 然后选择“ 检查访问权限”。

3. 键入用于连接到服务的用户或身份的名称。

4. 验证 角色认知服务用户 是否已列出（或包含 先决条件中所述所需权限的角色）。

   重要

   所有者或参与者等角色不通过Microsoft Entra ID 提供访问权限。

5. 如果未列出，请在继续之前按照本指南中的步骤进行操作。

下表包含多个方案，可帮助对 Microsoft Entra ID 进行故障排除：

在资源中禁用基于密钥的身份验证

在实现了 Microsoft Entra ID 并且解决了所有使用该服务的应用程序中的兼容性或回退问题时，建议禁用基于密钥的身份验证。 可以通过更改属性 disableLocalAuth 来实现此目的：

modules/ai-services-template.bicep

@description('Location of the resource.')
param ___location string = resourceGroup().___location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  ___location: ___location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id