控制用户对代理的访问

本文介绍如何使用应用角色和 assignmentRequired 属性控制用户和代理对应用程序的访问。其中介绍了如何定义应用角色、强制实施显式角色分配、使用 Microsoft Graph 或 Microsoft Entra 管理中心分配角色，以及安全访问管理的最佳做法。

先决条件

已创建和配置的现有代理标识蓝图
用于管理代理标识和分配的代理 ID 管理员角色
用于管理应用角色和 assignmentRequired 属性的应用程序管理员角色或云应用程序管理员角色
如果采用编程方法，则需要具有 Microsoft 图形 API 的 AppRoleAssignment.ReadWrite.All 权限。

什么是应用角色？

应用角色定义应用程序的逻辑权限或访问级别。它们在代理标识蓝图中声明，可分配给用户、组、服务主体或代理标识。以下部分显示了一个示例应用角色定义：

{
  "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
  "allowedMemberTypes": ["User", "Application"],
  "description": "Grants ability to invoke agent actions",
  "displayName": "AgentInvoker",
  "isEnabled": true,
  "value": "AgentInvoker"
}

allowedMemberTypes 控制谁可以被分配（用户、应用或两者皆可）。
value 是在分配时出现在令牌角色声明中的字符串。

如果代理标识蓝图未公开任何应用角色，则可以使用默认应用角色 <guid of all zeros> 将主体分配给代理标识。

在为代理应用程序设计角色时，请定义能够区分职能和职责的精细角色。例如，为可以调用代理作的用户创建特定角色，例如“AgentInvoker”，并为可以管理代理配置的用户创建“AgentAdmin”。此方法提供更好的安全控制，并使审核访问模式更容易。

什么是 assignmentRequired？

应用程序或代理标识上的 assignmentRequired 属性确定角色分配是否是访问必需的。

assignmentRequired = true →只有显式分配了应用角色的主体才能登录或调用代理标识。
assignmentRequired = false →任何经过身份验证的主体都可以访问代理标识（受其他条件的约束）。

为何使用 assignmentRequired？

出于以下原因，可以使用 assignmentRequired 属性：

通过要求显式分配来强制实施最低特权。
防止未打算使用该代理的用户或代理意外访问。

启用 assignmentRequired 敏感代理标识蓝图以强制实施显式角色分配，并确保只有授权主体可以访问关键代理功能。如果用户可以访问没有显式分配的应用程序，则表示已 assignmentRequired 设置为 false。将此设置更改为 true，并显式分配角色以维护安全控制。

配置 assignmentRequired（指定必需）

以下示例使用 Update 应用程序 API 设置 assignmentRequired 属性。

PATCH https://microsoftgraph.chinacloudapi.cn/v1.0/applications/<agent-app-id>
Content-Type: application/json
Authorization: Bearer <token>

{
  "appRoleAssignmentRequired": true
}

该 assignmentRequired 属性可确保只有显式分配了应用角色的主体才能访问代理标识蓝图，强制实施最低特权并防止意外访问。

分配应用角色来控制访问

应用角色是通过应用角色分配授予的。它们将主体（用户、组或代理标识）链接到目标代理标识上的特定应用角色。如果代理标识在配置后无法访问应用程序，请使用以下示例所示的 API 验证是否已为代理标识创建一个 appRoleAssignment 。

向用户分配应用角色

以下示例使用“为用户授予appRoleAssignment”API，将应用角色分配给用户。

POST https://microsoftgraph.chinacloudapi.cn/v1.0/users/<user-id>/appRoleAssignments
Authorization: Bearer <token with AppRoleAssignment.ReadWrite.All>
Content-Type: application/json

{
  "principalId": "<user-id>",
  "resourceId": "<agent-identity-blueprint-principal-id>",
  "appRoleId": "<app-role-id>"
}

将应用角色分配给代理标识

以下示例使用“授予 appRoleAssignment 给服务主体 API”将应用角色分配给代理标识。

POST https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Authorization: Bearer <token with AppRoleAssignment.ReadWrite.All>
Content-Type: application/json

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<agent-identity-blueprint-principal-id>",
  "appRoleId": "<app-role-id>"
}

验证角色分配

若要验证角色分配，请务必确保执行以下操作：

用户或代理标识的列表 appRoleAssignments 。
登录后检查令牌中的角色声明。

如果令牌中缺少角色声明，请验证分配是否存在正确的 appRoleId，然后请求新的令牌。使用 Microsoft Graph 或 Microsoft Entra 管理中心定期审核这些分配，以确保它们保持适当状态并删除任何不必要的访问。

上次更新时间为 2026-09-03