Microsoft Foundry 中的身份验证和授权

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

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

先决条件

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

控制平面和数据平面

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

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

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

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

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

• 构建代理
• 进行评估
• 跟踪和监视
• Fine-tuning

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

身份验证方法

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

Microsoft Entra ID

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

将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 响应;如果未配置凭据或未配置角色分配，则会出现身份验证错误。

Reference： DefaultAzureCredential | azure-identity library

使用 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 错误。

Reference：轮换 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. 在所有调用方使用令牌身份验证后，删除基于密钥的身份验证。 （可选）在部署模板中禁用本地身份验证。

参考：分配 Azure 角色 | 基于角色的 Foundry 访问控制

排查常见身份验证错误

相关内容

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