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

Agent 365 CLI 默认使用 Microsoft 管理的 Agent 365 企业级应用，只要租户中可用。本文将解释如何为Agent 365 CLI完成自定义客户端应用注册，以便你能够为租户拥有的应用进行身份验证和权限配置。

在以下情况下使用租户拥有的定制应用：

Microsoft管理的企业应用的分阶段部署尚未到达您的租户。
你的组织要求专门的客户端应用注册。
现有的Agent 365配置指定了自定义 clientAppId。

Important

本文仅适用于租户拥有的应用注册。不要将这些步骤应用到Microsoft管理的Agent 365 CLI应用程序上。f54280f4-395e-4ea8-9e48-bf2d4952aa14 CLI验证Microsoft管理的应用程序，无需更改其注册、重定向URI、权限、可选声明或权限授予。

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

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

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

先决条件

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

注册应用程序

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

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

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

Tip

没有管理员权限？你可以自己完成第1-3步，然后请租户管理员完成第4步。提供你第3步的 应用（客户端）ID ，以及配置API权限部分的链接。

在创建自定义应用之前先运行 a365 setup requirements 。 CLI 在可用时首先使用由 Microsoft 管理的企业应用程序，然后回退到一个名为 Agent 365 CLI 的租户拥有的应用程序。如果这两个应用程序都不可用，全局管理员可以在提示符处输入 C，以创建并配置租户拥有的应用程序。

1. 注册应用

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

转到 Microsoft Entra 管理中心
选择 App 注册
选择新建注册。
输入：
- 名称：为你的应用输入一个有意义的名称，例如 my-agent-app。应用用户会看到此名称，你可以随时对其进行更改。可以有多个具有相同名称的应用注册。
  
  Tip
  
  要将此应用用作 a365 setup all --agent-name 的无配置后备应用，请将其名称精确设为 Agent 365 CLI。 CLI在检查Microsoft管理的企业应用后会使用这个显示名称，因此你无需将客户端ID复制到配置文件中。
- 支持的账户类型： 仅限本组织目录中的账户 （单租户）
- 重定向 URI：选择 Public client/native （移动端和桌面端） 并进入 http://localhost:8400/
选择注册。

CLI 要求在由租户拥有的自定义应用上配置三个重定向 URI。 CLI 会在您运行 a365 setup requirements 时自动添加缺失的部分。

URI	Purpose
`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

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

Tip

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

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

4. 配置 API 权限

Important

你需要管理员权限才能完成这一步。如果你是没有管理员权限的开发者，把第3步的应用（客户端）ID发给租户管理员，让他们完成这一步。

注释

截至 2025 年 12 月，AgentIdentityBlueprint.*、AgentInstance.* 和 AgentIdentity.* 权限是 beta API，在Microsoft Entra 管理中心中可能不可见。如果这些权限在租户中变得普遍可用，你可以使用选项A获得所有权限。

选择合适的方法：

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

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

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

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

Important

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

逐个添加这七个权限：

许可	Purpose
`AgentIdentityBlueprint.ReadWrite.All`	蓝图创建、客户端密码管理、可继承权限、联合标识凭据和删除（beta API）
`AgentIdentityBlueprintPrincipal.Create`	创建 Agent Blueprint 服务主体（beta API）
`AgentIdentity.Read.All`	幂等性检查和代理身份服务主体查找（测试版 API）
`AgentIdentity.DeleteRestore.All`	在清理期间删除代理身份服务主体（测试版 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.* 权限，请使用此方法。

Warning

如果使用此 API 方法，之后不要使用Microsoft Entra 管理中心的“授予管理员同意”按钮。 API 方法会自动授予管理员同意，并使用Microsoft Entra管理中心按钮删除 beta 权限。更多信息请参见 “Beta权限消失”。

打开图谱浏览器。
使用您的管理员账户（应用管理员或云应用管理员）登录。
使用图形 API 授予管理员同意。若要完成此步骤，需要：
- 服务负责人身份证。你需要一个 SP_OBJECT_ID 可变值。
- 图形资源ID。你需要一个 GRAPH_RESOURCE_ID 可变值。
- 通过使用 oAuth2PermissionGrant 资源类型和SP_OBJECT_IDGRAPH_RESOURCE_ID变量值创建（或更新）委托权限。

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

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

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

将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
```
选择 运行查询。
- 如果查询成功，返回的值就是你的 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

将图探索器方法设置为 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 管理中心中不可见的测试版权限。

将图资源管理器方法设置为 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：已存在授权。也许有人之前添加了权限。请参见以下更新委托的权限。

Warning

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

更新委派权限

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

将图探索器方法设置为 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为自定义应用自动配置了什么

对于 Microsoft 管理的企业应用，CLI 验证租户本地服务主体和有效委派范围，而不更改应用注册。

当你选择租户所有的自定义应用时，a365 setup requirements 会验证应用注册，并且可能需要进行更改。在应用任何更改之前，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 操作系统的身份验证代理。详细了解如何获取设备绑定令牌。
启用“允许公共客户端流”	此功能在 macOS、Linux、适用于 Linux 的 Windows 子系统 (WSL)、无头环境中用于设备代码身份验证回退，并在 Windows 上作为条件访问策略的回退方案。
向应用注册添加缺少的权限	在 CLI 更新后，使应用注册与新所需的权限保持同步。
扩展管理员的同意授权	扩展现有的 OAuth2 权限授予以包含任何新预配的权限。

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

后续步骤

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

Agent 365 开发入门

Troubleshooting

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

Tip

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）	转到 Microsoft Entra 管理中心中的应用程序概述
✅ 授权授权	API 权限中显示类型：委托	参见错误的权限类型
✅ 所有权限已添加	请参见以下部分列出的所有权限	请再次执行第四步
✅ 已授予管理员同意	所有设备在状态下都显示绿色勾选	参见错误授予的管理员同意

必须委派权限：

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

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

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

Solution： 在 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 权限
移除所有应用权限。这些权限显示在类型列中的应用程序。
添加与委托权限相同的权限。
再次授予管理员授权。

症状：你使用了选项 B：Microsoft 图形 API（用于测试版权限）来添加测试版权限，但在 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 权限，请重新运行 Option B 步骤 3（使用图形 API 授予管理员同意）以还原它们。如果出现 Request_MultipleObjectsWithSameKeyValue 错误，请按照步骤更新委派权限。
若要验证是否列出了所有七个权限，请检查scope或POST响应中的PATCH字段。

验证时找不到应用

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

Solution:

确认你复制的是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-09-02

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

先决条件

注册应用程序

添加权限并授予同意

1. 注册应用

2. 设置重定向 URI

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

4. 配置 API 权限

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

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

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

获取你的Graph资源 ID

创建委托权限

更新委派权限

5. 添加 wids 角色声明

安全最佳做法

CLI为自定义应用自动配置了什么

后续步骤

Troubleshooting

CLI验证在配置过程中失败

管理员同意被错误地授予

蓝图创建失败，原因是“未授予管理员同意”

错误的权限类型

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

验证时找不到应用

反馈

其他资源