Agent 365 CLI 的自定义客户端应用注册

代理 365 CLI 需要在 Microsoft Entra ID 租户中注册自定义客户端应用程序，以便对代理标识蓝图进行身份验证和管理。

本文将该过程分为四个主要步骤：

1. 注册应用
2. 设置重定向URI
3. 复制应用程序（客户端） ID
4. 配置 API 权限需要管理员权限

如果遇到问题，请查看 故障排除 部分。

先决条件

在开始之前，请确保你可以访问Microsoft Entra管理门户，并在需要时具备授予许可所需的管理员角色之一。

注册该应用程序

默认情况下，租户中的 any 用户可以在 Microsoft Entra 管理中心 中注册应用程序。 然而， 租户管理员可以限制这一功能。 如果你无法注册应用，请联系你的管理员。

添加权限并授予同意

你需要其中一个管理员角色来配置API权限。

• 应用管理员：推荐——能够管理应用注册并授予同意
• 云应用管理员：可以管理应用注册并授予同意
• 全局管理员：拥有所有权限，但非必需

1. 注册应用

这些说明总结了 创建应用注册的完整说明。

1. 转到 Microsoft Entra 管理中心

2. 选择 App 注册

3. 选择“新建注册”

4. 输入：

   • 名称：为你的应用输入一个有意义的名称，例如 my-agent-app。 应用用户会看到此名称，你可以随时对其进行更改。 可以有多个具有相同名称的应用注册。

     提示

     如果要使用免配置 a365 setup all --agent-name 流，请按 Agent 365 CLI 精确命名应用程序。 CLI 会自动通过此已知显示名称查找客户端应用，因此无需将客户端 ID 复制到配置文件中。

   • 支持的账户类型： 仅限本组织目录中的账户 （单租户）

   • 重定向 URI：选择 Public client/native （移动端和桌面端） 并进入 http://localhost:8400/

5. 选择注册

CLI 总共需要三个重定向 URI。 CLI 会在您运行 a365 setup requirements 时自动添加缺失的部分。

有关详细信息 ，请参阅 CLI 自动配置的内容 。

2. 设置重定向 URI

1. 进入 概览 ，复制 应用程序（客户端）ID 值。
2. 进入认证（预览），选择添加重定向URI。
3. 选择 移动端和桌面应用 ，并将值设为 ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}，其中 {client-id} 是你复制的 应用程序（客户端 ID） 值。
4. 选择 配置 以添加该值。

3. 复制应用程序（客户端） ID

从应用 的概览 页面，复制应用程序 （客户端）ID ，格式为GUID。 运行 a365 setup all 或手动创建 a365.config.json时，请使用此值。

4. 配置 API 权限

选择合适的方法：

• Option A：如果“beta 权限”可见，则使用 Microsoft Entra 管理中心管理所有权限。
• Option B：使用Microsoft 图形 API添加所有权限（如果 beta 权限不可见，建议）

选项 A：Microsoft Entra 管理中心（标准方法）

如果在租户中可以看到 beta 权限，请使用此方法。

1. 在应用注册中，转到 API 权限。

2. 选择添加权限>Microsoft Graph>委托权限。

   重要

   必须使用 委派权限 （而不是 应用程序权限）。 CLI是交互式认证的——你登录，它会代表你行动。 若要了解详细信息，请参阅 “权限类型错误”。

3. 逐个添加以下 13 个权限：

   许可	Purpose
   AgentIdentityBlueprintPrincipal.Create	创建 Agent Blueprint 服务主体（beta API）
   AgentIdentityBlueprint.ReadWrite.All	管理代理蓝图配置（测试版API）
   AgentIdentityBlueprint.UpdateAuthProperties.All	Update Agent Blueprint 可继承权限（beta API）
   AgentIdentityBlueprint.AddRemoveCreds.All	在蓝图上添加或删除客户端机密和联合标识凭据（beta API）
   AgentIdentityBlueprint.DeleteRestore.All	清理期间删除代理蓝图应用程序（beta API）
   AgentInstance.ReadWrite.All	通过代理注册表 API 注册和管理代理实例（beta API）
   AgentIdentity.Create.All	从蓝图创建代理标识 （beta API）
   AgentIdentity.DeleteRestore.All	在清理期间删除代理身份服务主体（测试版 API）
   AgentIdentity.Read.All	读取代理标识数据（beta API）
   AgentRegistration.ReadWrite.All	读取和写入所有代理注册信息
   DelegatedPermissionGrant.ReadWrite.All	授予代理蓝图权限
   Directory.Read.All	读取目录数据进行验证
   User.Read	读取用于蓝图所有者分配的已登录用户配置文件

   注意

   AgentRegistration.ReadWrite.All 是代理设置所必需的。 CLI 通过.default无提示地获取此权限，Agent 365 CLI 验证器不会显式检查这一点，但它必须存在于您的应用注册中并已经获得管理员同意。

   对于每项许可：

   • 在搜索框中输入权限名称（例如， AgentIdentityBlueprint.ReadWrite.All。
   • 勾选权限旁边的复选框。
   • 选择添加权限。
   • 对所有 13 个权限重复此操作。

4. 选择 授予[您的租户]的管理员同意。

   • 为什么需要这一点？ 代理标识蓝图是多个用户和应用程序可以引用的租户范围资源。 如果没有租户全体同意，CLI在认证过程中会失败。
   • 如果失败了怎么办？ 你需要应用管理员、云应用管理员或全局管理员角色。 向你的租户管理员求助。

5. 验证所有权限在 状态 下显示为绿色勾选标记。

如果 beta 权限（AgentIdentityBlueprint.*）不可见，请转到 选项 B。

选项 B：Microsoft 图形 API（适用于 Beta 权限）

如果 Microsoft Entra 管理中心未显示 AgentIdentityBlueprint.* 权限，请使用此方法。

1. 打开 图谱浏览器。

2. 使用您的管理员账户（应用管理员或云应用管理员）登录。

3. 使用 图形 API 授予管理员同意。 若要完成此步骤，需要：

   • 服务负责人身份证。 你需要一个 SP_OBJECT_ID 可变值。
   • 图形资源ID。 你需要一个 GRAPH_RESOURCE_ID 可变值。
   • 通过使用 oAuth2PermissionGrant 资源类型和SP_OBJECT_IDGRAPH_RESOURCE_ID变量值创建（或更新）委托权限。

请利用以下章节中的信息完成这些步骤。

获取你的服务负责人身份证

服务主体（Service Principal）是你应用在租户中的身份。 你需要先获得它，才能通过API授予权限。

1. 将Graph Explorer方法设置为 GET ，并使用该URL。 将<YOUR_CLIENT_APP_ID>替换为步骤3中的实际应用客户端ID：复制应用（客户端）ID。

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. 选择“运行查询”。

   • 如果查询成功，返回的值就是你的 SP_OBJECT_ID。

   • 如果查询失败且出现权限错误，选择修改 权限 标签，同意所需权限，然后再次选择 运行查询 。 返回的值是你的 SP_OBJECT_ID。

   • 如果查询返回空结果（"value": []），则通过以下步骤创建服务主体：

     1. 设置方法为 POST ，并使用这个URL：

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        请求正文（将YOUR_CLIENT_APP_ID替换为您的应用程序客户端实际ID）：

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. 选择“运行查询”。 你应该会得到 201 Created 回复。 返回的 id 值是你的 SP_OBJECT_ID。

获取你的Graph资源 ID

1. 将图探索器方法设置为 GET ，并使用以下URL：

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. 选择“运行查询”。

   • 如果查询成功，复制该 id 值。 这个值就是你的 GRAPH_RESOURCE_ID。
   • 如果查询失败且出现权限错误，选择修改 权限 标签，同意所需权限，然后再次选择 运行查询 。 复制 id 值。 这个值就是你的 GRAPH_RESOURCE_ID。

创建委托权限

此 API 调用为租户范围内的所有 13 个权限授予管理员同意，包括 Microsoft Entra 管理中心中不可见的 beta 权限。

1. 将图资源管理器方法设置为 POST ，并使用以下URL和请求主体：

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   请求正文：

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

2. 选择“运行查询”。

   • 如果你得到 201 Created 响应：成功！ scope响应中的字段显示所有 13 个权限名称。 大功告成。
   • 如果查询因权限错误失败 （很可能 DelegatedPermissionGrant.ReadWrite.All），选择 修改权限 标签，同意 ， DelegatedPermissionGrant.ReadWrite.All然后再次选择 运行查询 。
   • 如果出现错误 Request_MultipleObjectsWithSameKeyValue：资助已经存在。 也许有人之前添加了权限。 请参见以下 更新委托的权限。

更新委派权限

当你按照Request_MultipleObjectsWithSameKeyValue的步骤出现错误时，请使用以下步骤更新委托权限。

1. 将图探索器方法设置为 GET ，并使用以下URL：

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. 选择“运行查询”。 复制响应中的 id 值。 该值为 YOUR_GRANT_ID。

3. 将图探索器方法设置为PATCH并使用此 URLYOUR_GRANT_ID。

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   请求正文：

   {
      "scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

4. 选择“运行查询”。 应获得一个包含所有 13 个权限的200 OK响应，并在scope字段中显示。

安全最佳做法

请查看这些指南，以确保您的应用注册安全且合规。

建议做法：

• 使用单一租户注册。
• 只授予所需的委派权限。
• 定期审核权限。
• 不需要时就移除应用。

不要：

• 授予应用程序权限。 只使用委托。
• 公开客户ID。
• 授予其他不必要的许可。
• 把这个应用用在其他用途上。

CLI 自动配置的内容

运行 a365 setup requirements时，CLI 会验证应用注册，可能需要进行更改。 在应用任何更改之前，CLI 会显示摘要并要求确认：

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

若要跳过确认提示（例如，在 CI 环境中），请使用标志 --yes ：

a365 setup requirements --yes

下表描述了 CLI 可能做出的每个更改：

如果拒绝提示，CLI 不会修改应用注册。 如果 CLI 需要更改才能正常运行，则可以在 Microsoft Entra 管理中心 中手动配置这些更改，或使用 --yes 重新运行它们。

后续步骤

注册自定义客户端应用后，将其与代理 365 CLI 配合使用以完成代理 365 设置：

故障排除

本节介绍如何排查自定义客户端应用注册的错误。

CLI验证在配置过程中失败

症状： 运行 a365 setup 或 a365 setup requirements 会失败，并产生关于自定义客户端应用的验证错误。

解决方案： 请使用这份清单来验证您的应用注册是否正确：

# Run requirements validation to see validation messages
a365 setup requirements

预期结果： CLI显示 Custom client app validation successful。

如果没有得到预期结果，请验证以下每项检查：

必须委派权限：

• AgentIdentityBlueprintPrincipal.Create [测试版]
• AgentIdentityBlueprint.ReadWrite.All [测试版]
• AgentIdentityBlueprint.UpdateAuthProperties.All [测试版]
• AgentIdentityBlueprint.AddRemoveCreds.All [测试版]
• AgentIdentityBlueprint.DeleteRestore.All [测试版]
• AgentInstance.ReadWrite.All [测试版]
• AgentIdentity.Create.All [测试版]
• AgentIdentity.DeleteRestore.All [测试版]
• AgentIdentity.Read.All [测试版]
• AgentRegistration.ReadWrite.All
• DelegatedPermissionGrant.ReadWrite.All
• Directory.Read.All
• User.Read

管理员同意被错误地授予

症状： 即使添加了权限，验证也会失败。

根本原因：您未授予管理员同意，或授予方式不正确。

Solution： 在 Microsoft Entra 管理中心 的应用注册中，转到 API 权限并选择授予 [你的租户]的管理员同意。 验证所有权限在 状态 下显示为绿色勾选标记。

错误的权限类型

症状：CLI因认证错误或权限拒绝错误而失败。

根本原因：你添加了 应用程序权限 而不是 委托权限。

本表描述了不同类型的权限。

为什么选择委派？

• 你通过浏览器进行交互式登录
• CLI会以你的身份执行操作（审计轨迹显示你的身份）
• 更安全——受限于你的实际权限
• 确保问责和合规

解决方案；

1. 转到Microsoft Entra 管理中心>应用注册> 您的应用>API 权限
2. 移除所有应用权限。 这些权限显示在类型列中的应用程序。
3. 添加与 委托 权限相同的权限。
4. 再次授予管理员授权。

经过Microsoft Entra管理中心的管理员许可后，Beta权限不再可用。

症状：你使用了选项 B：Microsoft 图形 API（用于测试版权限）来添加测试版权限，但在 Microsoft Entra 管理中心中选择授予管理员同意后，这些权限就会消失。

根本原因：Microsoft Entra 管理中心在 UI 中不显示 beta 权限。 当你选择 “授予管理员同意”时，门户只授予 可见 权限的同意，并覆盖API授予的同意。

原因：

1. 使用 图形 API （选项 B）添加所有 13 个权限，包括 beta 权限。
2. API consentType: "AllPrincipals" 调用已经授予了全租户管理员的权限。
3. 您前往 Microsoft Entra 管理中心后，只能看到部分权限，因为 beta 权限在门户中不可见。
4. 你选择了 授予管理员同意 ，以为你需要这样做。
5. Microsoft Entra 管理中心将用仅有的可见权限覆盖你的 API 授予的许可。
6. Beta 权限现已删除。

解决方案；

• 不要在 API 方法后使用 Microsoft Entra 管理中心的管理员同意：API 方法已授予管理员同意。
• 如果意外删除 beta 权限，请重新运行 Option B 步骤 3（使用 图形 API 授予管理员同意）以还原它们。 如果出现 Request_MultipleObjectsWithSameKeyValue 错误，请按照步骤更新 委派权限。
• 若要验证是否列出了所有 13 个权限，请检查scope或POST响应中的PATCH字段。

验证时找不到应用

症状： CLI报告 Application not found 或 Invalid client ID 错误。

Solution:

1. 确认你复制的是GUID格式的 应用程序（客户端）ID ，而不是 对象ID：

   • 转到 Microsoft Entra 管理中心>应用注册>您的应用程序>概览
   • 复制应用（客户端）ID 下的值
   • 格式应为： xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. 确认你的租户中是否存在该应用：

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

了解如何在 Microsoft Entra ID 中注册应用程序。