Microsoft Foundry 中的身份验证和授权

Microsoft Foundry 中的身份验证和授权控制主体如何证明身份并获取执行操作的权限。 Foundry 将操作划分为控制平面（资源管理）和数据平面（运行时使用情况），每个操作都有自己的身份验证和基于角色的访问控制（RBAC）图面。

Foundry 支持两种身份验证方法：Microsoft Entra ID和 API 密钥。 Microsoft Entra ID 支持条件访问、托管标识和细粒度 RBAC。 API 密钥仍可用于快速原型制作，但缺乏每用户可追溯性。 本文比较了这些方法，将标识映射到角色，并介绍了常见的最低特权方案。

先决条件

• 一个 Azure 订阅。 如果没有帐户， 请创建一个免费帐户。
• 配置了自定义子域的 Microsoft Foundry 资源。
• 对 Azure RBAC 概念 的理解。
• 若要分配角色，需要在适当的范围内使用 “所有者” 角色或 “用户访问管理员” 角色。
• （可选）安装 Azure CLI 或 Azure SDK for Python用于编程身份验证。
• （可选）代码示例的Python包：pip install azure-identity requests

控制平面和数据平面

Azure操作分为两类：控制平面和数据平面。 Azure将资源管理（控制平面）与操作运行时（数据平面）分开。 因此，可以通过控制平面管理订阅中的资源，并通过数据平面使用由资源类型的实例提供的功能。 若要详细了解控制平面和数据平面，请参阅Azure控制平面和数据平面。 在 Foundry 中，控制平面操作与数据平面操作之间存在明显的区别。 下表说明了这两者之间的差异、Foundry 中的范围、用户的典型操作、示例工具和功能以及要使用的授权图面。

有关所有 Bicep、Terraform 和 SDK 示例，请参阅 GitHub 上的 foundry-samples 存储库以获取 Foundry 的信息。

以下列表和关系图详细说明了控制平面和数据平面操作之间的分离。 Foundry 中的控制平面操作包括：

• Foundry 资源创建
• Foundry 项目创建
• 帐户能力主机创建
• 项目能力主机创建
• 模型部署
• 创建帐户和项目连接

Foundry 中的数据平面操作包括：

• 构建代理
• 进行评估
• 跟踪和监视
• 微调

下图显示了 Foundry 中控制平面与数据平面分离的视图，以及基于角色的访问控制（RBAC）分配，以及控制平面或数据平面中用户可能拥有的访问权限。 如图所示，RBAC“操作”与控制平面关联，而 RBAC“dataActions”与数据平面关联。

身份验证方法

Foundry 支持Microsoft Entra ID（基于令牌、无密钥）和 API 密钥。

Microsoft Entra ID

Microsoft Entra ID 使用范围限定为 https://ai.azure.com/.default 的 OAuth 2.0 持有者令牌。

将Microsoft Entra ID用于：

• 生产工作负荷。
• 条件访问、多重身份验证（MFA）和实时访问。
• 最小特权 RBAC 与托管身份集成。

优势：精细的角色分配、主体级审计、可控令牌生命周期、自动密钥管理以及服务托管身份。

限制：较高的初始设置复杂性。 需要了解基于角色的访问控制（RBAC）。 有关 Foundry 中的 RBAC 的详细信息，请参阅 Microsoft Foundry 的基于角色的访问控制。

API 密钥

API 密钥是限定为 Foundry 资源的静态密钥。

对以下项使用 API 密钥：

• 快速原型制作。
• 可以接受单机密轮换的独立测试环境。

优点：简单、与语言无关，并且不需要获取令牌。

限制：无法表达用户标识，难以精细确定范围，更难进行审核。 企业生产工作负载通常不被接受，Microsoft不推荐使用。

有关启用无密钥身份验证的详细信息，请参阅使用 Microsoft Entra ID。

使用Microsoft Entra ID进行身份验证（Python）

以下示例演示如何使用 azure-identity 库对 Microsoft Entra ID 进行身份验证，并向 Foundry 终结点发出请求：

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://ai.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

预期输出：列出模型部署的 JSON 响应;如果未配置凭据或未配置角色分配，则会出现身份验证错误。

参考： DefaultAzureCredential | azure-identity 库

使用 API 密钥进行身份验证（Python）

以下示例演示如何使用 API 密钥进行身份验证。 仅使用此方法进行快速原型制作;建议将Microsoft Entra ID用于生产。

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

预期输出：列出模型部署的 JSON 响应;如果 API 密钥无效，则会出现 401 错误。

参考： 轮换 API 访问密钥

功能支持矩阵

参考以下矩阵，了解 Foundry 中哪些功能支持 API 密钥与 Microsoft Entra ID。

标识类型

Azure资源和应用程序使用不同的标识类型进行身份验证，每个类型都专为特定方案而设计。 用户主体表示人类用户，服务主体表示应用程序或自动化过程，托管标识为Azure资源提供安全、无凭据的方式来访问其他服务。 了解这些区别有助于为交互式登录、应用到应用通信或工作负荷自动化选择正确的标识。

Azure支持以下标识类型。

内置角色概述

在 Foundry 中，使用内置角色分隔用户允许的操作。 大多数企业希望对其内置角色的控制平面操作和数据平面操作进行分离。 其他人预计数据与控制平面的合并角色可以减少所需的角色分配数量。 下表列出了方案和最适合每个方案的相应内置 Foundry 角色。

若要了解内置角色的细分以及控制和数据平面操作，请查看下图。

设置Microsoft Entra ID

有关在 Foundry 中设置Entra ID身份验证的高级指南，请参阅配置无密钥身份验证。

1. 确保 Microsoft Foundry 资源已配置自定义子域。 请参阅 自定义子域。 基于令牌的身份验证需要自定义子域。

2. 为每个主体分配所需的内置或自定义角色。 你需要目标范围的所有者或用户访问管理员角色才能分配角色。 常见角色分配：

   • Azure AI 用户：对于需要使用预部署的模型进行生成和测试的开发人员。
   • Azure AI Project Manager：对于需要创建项目和管理部署的团队主管。
   • Azure AI 帐户所有者：针对需要全面管理资源的管理员，允许有条件地分配 Azure AI 用户以访问数据平面。
   • Azure AI 所有者：适用于需要完全资源管理和数据平面访问的用户。 用于分配 Azure AI 用户角色的示例 CLI 命令：

   az role assignment create \
     --assignee <principal-id> \
     --role "Azure AI User" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

   若要验证角色分配，请运行 az role assignment list --assignee <principal-id> --scope <resource-scope> 并确认该角色显示在输出中。

3. （可选）对于服务主体，请创建应用注册、添加客户端密码或证书，并记下租户 ID、客户端 ID 和机密或证书。

4. （可选）对于托管标识，请在调用服务上启用系统分配的标识或附加用户分配的标识，然后在 Foundry 资源上为其分配角色。

5. 在所有调用方使用令牌身份验证后，删除基于密钥的身份验证。 （可选）在部署模板中禁用本地身份验证。

Reference：分配 Azure 角色 | Foundry 角色访问控制

排查常见身份验证错误

相关内容

• Foundry 的基于角色的访问控制
• 使用 Microsoft Entra ID
• 轮换 API 访问密钥
• Azure内置角色（AI + 机器学习）
• 认证与授权对比（Microsoft Entra ID）
• 身份基础知识