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

Agent 365 CLI 需要在您的 Microsoft Entra ID 租户中实现自定义客户端应用注册，以进行身份验证并管理智能体标识蓝图。

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

注册应用程序
设置重定向 URI
复制应用程序（客户端）ID
配置 API 权限需要管理员特权
添加 wids 角色声明

如果您遇到问题，请参阅故障排除部分。

必备条件

在开始之前，请确保您有权访问 Microsoft Entra 管理中心，并在需要时拥有授予同意所需的管理员角色之一。

要注册应用

默认情况下，在 Microsoft Entra 管理中心中，租户中的任何用户都可以注册应用程序。但是，租户管理员可以限制此功能。如果您无法注册应用，请联系您的管理员。

您需要具备以下管理员角色之一：4. 配置 API 权限。

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

提示

没有管理员访问权限？您可以自行完成步骤 1-3，然后请求租户管理员完成步骤 4。向他们提供步骤 3 中的应用程序（客户端）ID 以及指向配置 API 权限部分的链接。

提示

全局管理员可以跳过手动注册。 运行 a365 setup requirements，如果在您的租户中未找到 Agent 365 CLI 应用，CLI 会提示您创建该应用并自动授予管理员同意。在提示中键入 C，即可在一个步骤中创建应用。如果您使用此自动路径，可以跳过本部分中的步骤。

1. 注册应用程序

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

转到 Microsoft Entra 管理中心
选择应用注册
选择新建注册
输入：
- 名称：为您的应用输入一个有意义的名称，例如 my-agent-app。应用用户可以看到此名称，您可以随时更改它。您可以使用相同的名称进行多个应用注册。
  
  提示
  
  如果您想要使用无配置 a365 setup all --agent-name 流，请将应用准确地命名为 Agent 365 CLI。 CLI 会根据该知名显示名称自动查找客户端应用，因此您无需将客户端 ID 复制到配置文件中。
- 支持的帐户类型：仅限此组织目录中的帐户（单租户）
- 重定向 URI：选择公共客户端/本机（移动和桌面），然后输入 http://localhost:8400/
选择注册

CLI 总共需要三个重定向 URI。当您运行 a365 setup requirements 时，CLI 会自动添加任何缺失的设置：

URI	用途
`http://localhost:8400/`	Microsoft 身份验证库 (MSAL) 交互式浏览器身份验证
`http://localhost`	Microsoft Graph PowerShell SDK `Connect-MgGraph`
`ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}`	使用 Web 帐户管理器 (WAM)

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

2. 设置重定向 URI

转到概述，然后复制应用程序（客户端）ID 值。
转到身份验证（预览版），然后选择添加重定向 URI。
选择移动和桌面应用程序，然后将值设置为 ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}，其中 {client-id} 是您复制的应用程序（客户端 ID）值。
选择配置以添加值。

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

从应用的概述页面中，以 GUID 格式复制应用程序（客户端）ID。在运行 a365 setup all 或手动创建 a365.config.json 时，您需要使用此值。

提示

不要将此值与对象 ID 混淆 - 您需要应用程序（客户端）ID。

如果您在步骤 1 中已将应用命名为 Agent 365 CLI，在使用 a365 setup all --agent-name 时可以跳过此步骤。 CLI 按显示名称自动解析客户端 ID。

4. 配置 API 权限

重要提示

您需要管理员特权才能完成此步骤。如果您是没有管理员访问权限的开发人员，请将步骤 3 中的应用程序（客户端）ID 发送给租户管理员，让他们完成此步骤。

备注

截至 2025 年 12 月，AgentIdentityBlueprint.*、AgentInstance.* 和 AgentIdentity.* 权限是 Beta 版 API，可能在 Microsoft Entra 管理中心中不可见。如果这些权限在您的租户中变为公开可用，您可以针对所有权限使用选项 A。

选择适当的方法：

选项 A：针对所有权限使用 Microsoft Entra 管理中心（如果 Beta 版权限可见）
选项 B：使用 Microsoft 图形 API 添加所有权限（如果 Beta 版权限不可见，建议使用此方法）

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

若您的租户中可见 beta 权限，请使用此方法。

在您的应用注册中，转到 API 权限。
选择添加权限>Microsoft Graph>委托的权限。

重要提示

必须使用委托的权限（而不是应用程序权限）。 CLI 以交互方式进行身份验证 - 您登录后，它会代表您执行操作。若要了解详细信息，请参阅错误的权限类型。

依次添加七个权限：

权限	用途
`AgentIdentityBlueprint.ReadWrite.All`	蓝图创建、客户端密码管理、可继承权限、联合身份凭据和删除（Beta 版 API）
`AgentIdentityBlueprintPrincipal.Create`	创建智能体蓝图服务主体（Beta 版 API）
`AgentIdentity.Read.All`	幂等性检查与智能体标识服务主体查找（Beta 版 API）
`AgentIdentity.DeleteRestore.All`	在清理过程中删除智能体标识服务主体（Beta 版 API）
`AgentRegistration.ReadWrite.All`	读取并写入所有智能体注册
`Application.Read.All`	按应用 ID 查找服务主体（缩小 Directory.Read.All 的替代方案）
`User.Read`	读取已登录用户的个人资料以分配蓝图所有者和赞助人

备注

AgentRegistration.ReadWrite.All 是智能体设置所必需的。 CLI 验证器会显式检查此权限。此权限必须添加到您的应用注册中，并获得管理员同意。

对于每个权限：

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

选择为 [您的租户] 授予管理员同意。
- 为什么需要此操作？智能体标识蓝图是多个用户和应用程序可以引用的租户范围资源。未获得租户范围同意时，CLI 会在身份验证期间失败。
- 如果失败怎么办？ 您需要应用程序管理员、云应用程序管理员或全局管理员角色。向您的租户管理员寻求帮助。
请确认状态下所有权限均显示绿色勾选标记。

如果 Beta 版权限 (AgentIdentityBlueprint.*) 不可见，请继续选项 B。

选项 B：Microsoft 图形 API（适用于测试版权限）

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

警告

如果您使用此 API 方法，之后请勿使用 Microsoft Entra 管理中心的“授予管理员同意”按钮。 API 方法会自动授予管理员同意，使用 Microsoft Entra 管理中心按钮删除您的 Beta 版权限。有关详细信息，请参阅 Beta 版权限消失。

打开 Graph 浏览器。
使用您的管理员帐户（应用程序管理员或云应用程序管理员）登录。
通过使用图形 API 授予管理员同意。若要完成此步骤，您需要：
- 服务主体 ID。您需要 SP_OBJECT_ID 变量值。
- Graph 资源 ID。您需要 GRAPH_RESOURCE_ID 变量值。
- 通过将 oAuth2PermissionGrant 资源类型与 SP_OBJECT_ID 和 GRAPH_RESOURCE_ID 变量值结合使用，创建（或更新）委托的权限。

使用以下部分中的信息完成这些步骤。

获取您的服务主体 ID

服务主体是您的应用在租户中的标识。您需要先获得它，才能通过 API 授予权限。

将 Graph 浏览器方法设置为 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
```
选择运行查询。
- 如果查询成功，返回的值就是您的 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

将 Graph 浏览器方法设置为 GET 并使用此 URL：

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

选择运行查询。
- 如果查询成功，复制 id 值。此值就是您的 GRAPH_RESOURCE_ID。
- 如果查询失败并具有权限错误，请选择修改权限选项卡，同意所需权限，然后再次选择运行查询。复制 id 值。此值就是您的 GRAPH_RESOURCE_ID。

创建委托的权限

此 API 调用将授予租户范围的管理员同意，涵盖全部七项权限，包括在 Microsoft Entra 管理中心中不可见的测试版权限。

将 Graph 浏览器方法设置为 POST，并使用此 URL 和请求正文：

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

请求正文：

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

选择运行查询。
- 如果您收到 201 Created 回复：成功！回复中的 scope 字段显示全部七个权限名称。大功告成！
- 如果查询失败并具有权限错误，请选择修改权限选项卡，同意所需权限，然后再次选择运行查询。
- 如果您收到错误 Request_MultipleObjectsWithSameKeyValue：已存在授权。也许有人之前添加了权限。请参阅以下更新委托的权限。

警告

POST 请求中的 consentType: "AllPrincipals" 已授予租户范围的管理员同意。在使用此 API 方法后，请勿在 Microsoft Entra 管理中心中选择“授予管理员同意” - 这样做会删除您的 Beta 版权限，因为 Microsoft Entra 管理中心无法识别 Beta 版权限，并且会用仅可见的权限覆盖 API 授予的同意。

更新委托的权限

当使用创建委托的权限步骤收到 Request_MultipleObjectsWithSameKeyValue 错误时，使用以下步骤更新委托的权限。

将 Graph 浏览器方法设置为 GET 并使用此 URL：

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

选择运行查询。复制响应中的 id 值。此值为 YOUR_GRANT_ID。

将 Graph Explorer 方法设置为 PATCH，并使用具有 YOUR_GRANT_ID 的此 URL 进行操作。

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

请求正文：

{
   "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
}

选择运行查询。您应该会收到 200 OK 回复，所有七个权限都显示在 scope 字段中。

5. 添加 wids 角色声明

Agent 365 CLI 会直接从访问令牌读取您的 Entra 目录角色分配，以确定您是否拥有管理员特权。这需要将 wids 声明添加到为您的应用注册颁发的访问令牌。

如果没有此声明，CLI 无法检测您的角色，并在需要管理员特权的每个步骤中返回显示 PowerShell 说明，即使您是管理员。完成此步骤以获取正确的行为。

在应用注册中，转到令牌配置。
选择添加可选声明。
对于令牌类型，选择访问。
在声明列表中，选中 wids 旁边的复选框。
选择添加。

如果提示需要打开 Microsoft Graph profile 权限以启用该声明，请选择是，添加。

备注

wids 声明包含直接分配给已登录用户的 Entra 目录角色的角色模板 GUID。 CLI 使用这些 GUID 检测全局管理员和智能体 ID 管理员角色，无需额外的图形 API 调用。

限制：wids 仅反映直接分配 角色。如果租户通过可分配角色的安全组分配目录角色，CLI 可能无法检测到这此基于组的角色分配。直接分配角色是智能体 ID 开发人员和管理员角色的标准模式。

安全性最佳做法

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

建议事项：

使用单一租户注册。
仅授予所需委托的权限。
定期审核权限。
不再需要时删除应用。

禁止事项：

授予应用程序权限。仅使用委托的权限。
公开共享客户端 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 可能进行的每个更改：

更改	原因
添加重定向 URI `http://localhost`	Microsoft Graph PowerShell SDK 需要此 URI 以进行浏览器身份验证。若未启用此功能，OAuth2 授权操作将回退至缺少所需委托权限的令牌，并返回 403 错误。
添加重定向 URI `http://localhost:8400/`	MSAL 需要此 URI 以进行交互式浏览器身份验证。
添加重定向 URI `ms-appx-web://Microsoft.AAD.BrokerPlugin/{id}`	Web 帐户管理器 (WAM) 所必需，Windows OS 身份验证代理。了解有关获取设备绑定令牌的详细信息。
启用“允许公共客户端流”	此功能在 macOS、Linux、适用于 Linux 的 Windows 子系统 (WSL)、无头环境中用于设备代码身份验证回退，并在 Windows 上作为条件访问策略的回退方案。
向应用注册添加缺失的权限	在 CLI 更新后，使应用注册与新获取的权限保持同步。
扩展管理员同意授予	扩展现有 OAuth2 权限授予以包括任何新预配的权限。

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

后续步骤

注册自定义客户端应用后，将其与 Agent 365 CLI 结合使用以完成您的 Agent 365 设置：

Agent 365 开发入门

故障排除

本部分介绍如何对自定义客户端应用注册的错误进行故障排除。

提示

Agent 365 故障排除指南包含高层次的故障排除建议、最佳实践，以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

配置过程中 CLI 验证失败

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

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

# Run requirements validation to see validation messages
a365 setup requirements

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

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

检查	如何验证	修复
✅ 已使用正确 ID	已复制应用程序（客户端）ID（而不是对象 ID）	在 Microsoft Entra 管理中心中，转到应用概述
✅ 委托的权限	API 权限中显示类型：委托	请参阅错误的权限类型
✅ 所有权限已添加	请参阅下面列出的所有权限	再次按照步骤 4 操作
✅ 管理员同意已授予	在“状态”下全部显示绿色复选标记	请参阅管理员同意授予不正确

所需委托的权限：

AgentIdentityBlueprint.ReadWrite.All [Beta 版]
AgentIdentityBlueprintPrincipal.Create [Beta 版]
AgentIdentity.Read.All [Beta 版]
AgentIdentity.DeleteRestore.All [Beta 版]
AgentRegistration.ReadWrite.All
Application.Read.All
User.Read

症状：即使您添加了权限，验证仍然失败。

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

解决方案：在 Microsoft Entra 管理中心中的应用注册中，转到 API 权限，然后选择为 [您的租户] 授予管理员同意。请确认状态下所有权限均显示绿色勾选标记。

症状：a365 setup all 打印“已成功确保委托的应用程序同意”，但在创建蓝图期间立即失败，并出现：

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

根本原因：您的租户已经有自定义客户端应用的 oauth2PermissionGrant 记录（来自之前的部分安装运行或 Microsoft Entra 管理中心中针对其他范围执行的早先的“授予管理员同意”操作），但该记录缺少所需的范围 (AgentIdentityBlueprint.ReadWrite.All)。 CLI 会检测缺少的范围，并显示供管理员完成授权的同意 URL。

解决方案：

与应用程序管理员或全局管理员共享错误输出中打印的同意 URL。 URL 如下所示：

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

管理员授予同意后，重新运行 a365 setup all --agent-name <name>。

如果您有管理员访问权限，可以直接在浏览器中打开 URL，无需等待即可授予同意。

错误的权限类型

症状：CLI 失败，并具有身份验证错误或权限拒绝错误。

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

此表描述不同类型的权限。

权限类型	何时使用	Agent 365 CLI 如何使用它
已委派（“范围”）	用户以交互方式登录	Agent 365 CLI 使用它 - 您登录后，CLI 将代表您执行操作
应用程序（“角色”）	服务无需用户运行	请勿使用 - 仅限于后台服务/守护程序

为什么已委派？

您以交互方式登录（浏览器身份验证）
CLI 以您的身份执行操作（审核线索、显示您的标识）
更安全 - 受限于您的实际权限
确保责任制和合规性

解决方案：

转到 Microsoft Entra 管理中心>应用注册>您的应用 >API 权限
删除任何应用程序权限。这些权限在 Type 列中显示为应用程序。
添加与委托的权限相同的权限。
再次授予管理员同意。

症状：您使用了选项 B：Microsoft 图形 API（用于 Beta 版权限）添加 Beta 版权限，但它们会在您选择 Microsoft Entra 管理中心中的授予管理员同意后消失。

根本原因：Microsoft Entra 管理中心在 UI 中不显示 Beta 版权限。当您选择授予管理员同意时，门户仅为可见权限授予同意，并覆盖 API 授予的同意。

为什么会发生此情况：

您使用图形 API（选项 B）添加所有七个权限，包括 Beta 版权限。
consentType: "AllPrincipals" 已授予租户范围的管理员同意的 API 调用。
您转到 Microsoft Entra 管理中心，只能看到部分权限，因为 Beta 版权限在门户中不可见。
在您需要时，选择授予管理员同意。
Microsoft Entra 管理中心会将您通过 API 授予的同意权限覆盖为仅可见的权限。
Beta 版权限现已删除。

解决方案：

请勿在 API 方法后使用 Microsoft Entra 管理中心管理员同意：API 方法已授予管理员同意。
如果您意外删除 Beta 版权限，请重新运行步骤 3（使用图形 API 授予管理员同意）中的选项 B以还原它们。如果您收到 Request_MultipleObjectsWithSameKeyValue 错误，请按照相关步骤更新委托的权限。
若要验证所有七个权限是否已列出，请检查 POST 或 PATCH 回复中的 scope 字段。

验证期间未找到应用

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

解决方案：

验证您复制了采用 GUID 格式的应用程序（客户端）ID，而不是对象 ID：
- 转到 Microsoft Entra 管理中心>应用注册> 您的应用 >概述
- 在应用程序（客户端）ID 下复制值
- 格式应为：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

验证您的租户中是否存在应用：

# 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 中注册应用程序。

反馈

此页面是否有帮助？

Last updated on 2026-07-29

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

必备条件

要注册应用

添加权限并授予同意

1. 注册应用程序

2. 设置重定向 URI

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

4. 配置 API 权限

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

选项 B：Microsoft 图形 API（适用于测试版权限）

获取您的服务主体 ID

获取您的 Graph 资源 ID

创建委托的权限

更新委托的权限

5. 添加 wids 角色声明

安全性最佳做法

CLI 自动配置的内容

后续步骤

故障排除

配置过程中 CLI 验证失败

管理员同意授予不正确

蓝图创建失败，并具有“管理员同意未授予”

错误的权限类型

在 Microsoft Entra 管理中心管理员同意后，Beta 版权限会消失

验证期间未找到应用

反馈

其他资源