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

Agent 365 CLI需要在您的Microsoft Entra ID租户中注册自定义客户端应用，以认证和管理代理身份蓝图。

先决条件

注册应用 （步骤1和2）：

• 默认情况下， 租户中的任何用户都可以在Microsoft Entra 管理中心注册应用程序。 然而， 租户管理员可以限制这一功能。

添加权限和授予同意 （步骤3）：

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

步骤1：注册申请

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

1. 前往 Microsoft Entra 管理中心
2. 选择 应用注册
3. 选择“新建注册”
4. 进入：
   • 姓名： Agent365 CLI （或您偏好的名字）
   • 支持的账户类型： 仅限本组织目录中的账户 （单租户）
   • 重定向 URI：选择 公共客户端/原生（移动端和桌面端） → 进入 http://localhost:8400/
5. 选择注册

步骤2：复制申请（客户）ID

从应用 的概览 页面复制 应用程序（客户端）ID （GUID格式）。 使用 a365 config init 命令时输入这个值。

步骤3：配置API权限

选择合适的方法：

• 选项A：使用Microsoft Entra管理中心获取所有权限（如果测试版权限可见）
• 选项B：使用 Microsoft Graph API 添加所有权限（如果测试版权限不可见，建议使用）

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

如果租户中显示了测试权限，请使用此方法。

1. 在你的应用注册中，进入 API 权限

2. 选择Microsoft图→添加权限→委托权限

   重要

   你必须使用 委托权限 （不是应用程序权限）。 CLI是交互式认证的——你登录，它会代表你行动。 如果你不小心添加了应用程序权限，请查看 错误的权限类型 。

3. 将这五个权限逐一添加：

   许可	目的
   AgentIdentityBlueprint.ReadWrite.All	管理代理蓝图配置（测试版API）
   AgentIdentityBlueprint.UpdateAuthProperties.All	Update Agent Blueprint 可继承权限（beta API）
   Application.ReadWrite.All	创建和管理应用程序及代理蓝图
   DelegatedPermissionGrant.ReadWrite.All	授予代理蓝图权限
   Directory.Read.All	读取目录数据进行验证

   对于每项许可：

   • 在搜索框中输入权限名称（例如，） AgentIdentityBlueprint.ReadWrite.All
   • 勾选权限旁边的复选框
   • 选择“添加权限”
   • 对所有五个权限重复此过程

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

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

5. 验证所有权限，状态下显示绿色勾选

如果测试权限AgentIdentityBlueprint.*（）不可见，请进入选项B。

选项B：Microsoft Graph API（用于测试权限）

如果 AgentIdentityBlueprint.* 权限在 Microsoft Entra 管理中心看不到，可以使用这个方法。

1. 开放 图探索器

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

3. 使用Graph API授予管理员同意。 要完成这项工作，你需要：

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

请利用以下章节中的信息来完成此项工作。

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

服务主体是租户中应用的身份，在通过API授予权限前必须有。

1. 将图资源管理器方法设置为 GET ，并使用该 URL（替换 <YOUR_CLIENT_APP_ID> 为步骤 2：复制应用（客户端）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。

获取你的图资源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 调用授予租户范围内所有五项权限的管理员同意，包括 Microsoft Entra 管理中心中不可见的两个测试版权限。

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

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

   请求正文：

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. 选择 运行查询。

   • 如果你得到 201 Created 回复：成功！ scope回复中的字段显示了所有五个权限名称。 大功告成。
   • 如果查询因权限错误（ 很可能 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 ，并使用该URL使用 YOUR_GRANT_ID。

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

   请求正文：

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. 选择 运行查询。 你应该会收到 200 OK 包含字段中全部五个权限 scope 的回复。

Troubleshooting

本节包含如何排查自定义客户端应用注册错误的信息。

错误的权限类型（委托权限 vs 应用程序）

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

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

为什么选择委派？

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

解决方案：

1. 前往 Microsoft Entra 管理中心>应用注册> 你的应用 >API 权限
2. 移除所有应用权限（这些权限在 类型 列中显示为“应用程序”）
3. 添加与 委派 权限相同的权限
4. 再次授予管理员同意

Microsoft Entra 管理员中心管理员同意后，测试权限消失

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

根本原因：Microsoft Entra 管理中心在 UI 中没有显示测试版权限，所以当你选择 授予管理员权限时，它只授予 可见 权限，并覆盖 API 授予的权限。

原因：

1. 你使用图谱API（选项B）添加包括测试权限在内的全部五个权限
2. API consentType: "AllPrincipals" 调用已经授予了全租户管理员的同意
3. 你去 Microsoft Entra 管理中心只看到三个权限，因为测试版权限是看不见的
4. 你选择 了授予管理员同意 ，认为需要
5. Microsoft Entra 管理中心只覆盖你 API 授予的 同意，仅有三个可见权限
6. 你的两个测试权限现在已被删除

解决方案：

• 在API方法之后，切勿使用Microsoft Entra管理员中心的管理员同意：API方法已经授予管理员同意
• 如果你不小心删除了测试权限，请重新执行选项B步骤3（使用Graph API授予管理员同意）来恢复权限。 你遇到 Request_MultipleObjectsWithSameKeyValue 错误——请按照步骤 更新委派权限。
• 请检查 scope or PATCH 回复中的字段POST，确认所有五个权限都被列出了

验证错误

当 CLI 运行a365 setupa365 config init或 时，CLI 会自动验证你的客户端应用。

常见问题：

• 找不到应用：确认你复制的是 应用程序（客户端）ID （非对象ID）
• 缺少权限：添加全部五个必需权限
• 管理员未获批准：
  • 如果您使用了选项A（仅限Microsoft Entra管理中心）：在Microsoft Entra管理中心选择授予管理员同意
  • 如果你用了选项B（图API）：重新运行或POSTPATCH请求。 不要使用 Microsoft Entra 管理员中心的同意按钮
• 错误的权限类型：使用委派权限，而非应用程序权限

有关详细的故障排除，请参见 “在 Microsoft Entra ID 注册应用程序”。

安全最佳做法

建议做法：

• 使用单一租户注册
• 只授予所需的五个授权
• 定期审计权限
• 不需要时就移除应用

不要：

• 授予应用权限（仅限授权使用）
• 公开分享客户端ID。
• 授予其他不必要的权限
• 请将应用用于其他用途

后续步骤

现在你已经注册了自定义客户端应用，可以搭配 Agent 365 CLI 一起使用：

• 开始使用 Agent 365 CLI - 用客户端应用安装并配置 CLI
• 设置代理蓝图和实例 ——创建并配置你的代理身份
• 部署和发布代理 ——将代理部署到Azure并发布到Microsoft 365