将自定义应用注册迁移到代理 ID

如果使用标准Microsoft Entra应用注册或服务主体生成 AI 代理，代理将像任何其他应用程序一样进行身份验证。 它们不利用代理特定的治理功能，例如条件访问策略、集中式审核日志记录和代理 ID 提供的生命周期管理。

本文介绍如何将你拥有代码和标识配置的智能体迁移到智能体 ID。 您创建代理ID资源（蓝图和代理身份）、更新您的应用程序代码并停用旧的代理标识。

先决条件

• 使用应用注册或服务主体进行身份验证的现有 AI 代理。
• 用于创建蓝图和代理标识的代理 ID 开发人员或代理 ID 管理员角色。
• 特权角色管理员角色用于授予Microsoft Graph应用程序权限。
• 访问 Microsoft Graph v1.0 API。
• 对代理标识关键概念的熟悉。 有关详细信息，请参阅 代理标识概念。

许可要求

Microsoft Entra 智能体 ID是Microsoft Entra中的产品，提供用于创建和管理代理标识和代理标识蓝图的平台。 代理 ID 适用于所有Microsoft Entra客户。

Microsoft Agent 365 使代理能够跨 Microsoft 365 服务和企业工作流运行，这要求每位用户都具有 Microsoft Agent 365 许可证。

将Microsoft Entra安全功能扩展到代理需要Microsoft Agent 365。 代理 365 包含在 Microsoft 365 E7 中，作为 Microsoft E5/A5/Business Premium（或 Microsoft Defender 套件 + Microsoft Purview 套件）的加载项提供。 有关更多详细信息，请参阅我们最新的 Agent 365 产品条款。

查看迁移好处

Microsoft Entra 智能体 ID为 AI 代理身份验证和授权提供专用标识构造。 代理标识蓝图充当治理模板，代理标识是代理用来进行身份验证、获取令牌和访问资源的运行时主体。 通过迁移到 Agent ID，将获得：

代理 ID 将代理置于与用户和工作负载相同的治理模型下。 迁移至代理 ID 功能后，你将获得以下优势：

访问控制

• 实施条件访问控制。 像用户一样，将条件访问策略和控制直接应用于代理及其访问的资源。

代理治理

• 生命周期管理。 Microsoft Entra ID 治理可以管理代理访问生命周期策略，因此代理不会累积过时的权限。
• 多云可见性。 跨Azure、本地和其他云环境运行的代理通过单个标识平面进行管理。

可见性和审核

• 特定于代理的审核线索。 审核和登录日志将代理的操作及其访问的资源归因于特定的代理身份，而不是通用的应用注册。 此方法使调查和归因变得简单明了。
• 代理注册表可见性。 这些代理会显示在你的组织代理注册表中，从而为你提供一份完整的代理清单，避免出现监控盲区。

审查迁移阶段

迁移到代理 ID 的过程是分阶段的过程，而不是单步切换。 本指南将该过程分为四个阶段，每个阶段都基于上一阶段的输出。 分阶段模型可防止过早删除可能支持活动工作负荷的服务主体。 在进行任何迁移或停用操作之前，都需要正确地进行发现和分类。

阶段 1：查找现有应用注册

在迁移任何内容之前，请在您的租户中建立一个代理相关标识的完整清单。 从组织全范围的扫描开始，查找所有迁移候选者，然后缩小到单个代理，以获取迁移期间所需的配置详细信息。

创建组织级清单

扫描租户中可能表示 AI 代理的所有服务主体。 目标是创建一个结构化报表，用于显示使用情况信号，并帮助在下一阶段对每个标识进行分类。

对于每个候选服务主体对象，记录：

• 标识元数据： 显示名称、应用程序 ID、对象 ID、创建日期、租户。
• 所有权： 分配的所有者、拥有团队或部门（如果有）。
• 登录活动： 最后一次交互式和非交互式登录，过去30天、90天和180天的登录次数。
• 审核日志信号： 创建服务主体、创建事件、最近修改或权限更改的源系统。
• 标记分析： 应用于服务主体的标记；检查它是否携带任何特定于构建器的标记模式。
• API 权限： 已授予委派权限和应用程序权限、管理员同意状态、权限敏感度级别。
• 其他标识配置： 使用的凭据、OAuth 流、自定义属性、RBAC 角色分配、重定向 URI 和任何下游依赖项。 迁移过程中需要这些配置详细信息才能正确重新创建标识作为代理 ID。

通过日志和权限分析识别代理

对于没有标记的服务主体，请使用行为和配置信号来标识可能代理标识。 没有单个信号是明确的。 将它们组合在一起以生成置信度分数。

若要操作启发式发现，请使用Microsoft Graph以编程方式查询服务主体登录日志和权限授予。 对于具有扩展日志保留期（通过Microsoft Sentinel或其他 SIEM）的租户，请将分析窗口扩展到Microsoft Entra的默认 30 天登录保留期之外，以提高信号准确性。

启发式发现生成候选，而非确认的智能体。 在继续分类之前，请查看每个匹配项。 可能会出现误报，例如调用 Azure OpenAI 但不是自治代理的后端微服务。

通过组织知识源发现代理

自动化方法可能无法找到每个代理，尤其是那些具有通用 API 权限并由用户特制开发的代理，因为它们缺乏命名约定重叠，因此对基于标签的扫描和启发式扫描不可见。 因此，应考虑：

CMDB 和资产清单对帐

将您发现的服务主体与贵组织的配置管理数据库或应用程序组合注册表进行交叉引用。 注册为“AI 代理”、“聊天机器人”或 CMDB 中的“虚拟助手”工作负荷类型的应用程序应与相应的服务主体匹配，并将其添加到迁移清单中。

开发人员自我证明

对于具有大量应用注册的租户，请向应用程序所有者发布迁移清单，并要求他们证明其服务主体是否表示 AI 代理。 由于应用程序所有者对工作负荷类型有明确的了解，因此此方法可缩放发现，超出任何自动扫描可以实现的发现。 将自证明与最后期限和升级路径相结合，以推动完成。

建议的发现序列

按顺序运行这些方法：

1. 基于标记的扫描： 自动标识所有标记的代理。 这些代理是确认的候选者。
2. 启发式分析： 扫描剩余未标记的服务主体以获取行为信号。 将高置信度匹配标记为潜在候选对象。
3. CMDB 对帐： 将剩余的服务主体与资产清单匹配，以捕获在非明显名称下注册的代理。
4. 开发人员证明： 向应用程序所有者发布未匹配的剩余列表以进行最终分类。

阶段 2：对用于迁移的代理身份进行分类

使用发现报告，按使用级别对每个服务主体进行分类，该级别决定如何继续迁移。

30 天的登录阈值基于Microsoft Entra的默认保留期。 如果您的组织通过 Microsoft Sentinel 或其他 SIEM 系统保留审核日志，请相应调整阈值。

阶段 3：将应用注册迁移到代理 ID

此阶段介绍标识创建为标准应用注册或服务主体的代理的技术迁移步骤。 创建新的代理 ID 资源并更新应用程序代码以使用两阶段令牌获取模型。 步骤 1 到 3 面向 Microsoft Entra 租户。 步骤 4 针对应用程序代码的更改。

步骤 1：创建代理标识蓝图

若要完成此步骤，需要 Agent ID Developer 或 Agent ID Administrator 角色来创建蓝图和代理标识，以及特权管理员角色来授予Microsoft Graph应用程序权限。

蓝图是代理的治理模板。 它定义在它下创建的所有代理标识继承的凭据和权限策略。

使用Microsoft Graph创建蓝图：

POST https://microsoftgraph.chinacloudapi.cn/v1.0/applications/microsoft.graph.agentIdentityBlueprint
Content-Type: application/json

{
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        "https://microsoftgraph.chinacloudapi.cn/v1.0/users/<sponsor-user-id>"
    ],
    "owners@odata.bind": [
        "https://microsoftgraph.chinacloudapi.cn/v1.0/users/<owner-user-id>"
    ]
}

或者使用 PowerShell：

$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Blueprint"
    "sponsors@odata.bind" = @("https://microsoftgraph.chinacloudapi.cn/v1.0/users/<sponsor-user-id>")
    "owners@odata.bind" = @("https://microsoftgraph.chinacloudapi.cn/v1.0/users/<owner-user-id>")
} | ConvertTo-Json -Depth 5

Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://microsoftgraph.chinacloudapi.cn/v1.0/applications/microsoft.graph.agentIdentityBlueprint" `
    -Headers @{ "OData-Version" = "4.0" } `
    -Body $body `
    -ContentType "application/json"

在蓝图中配置凭据

代理 ID 使用联合标识凭据（FIC）作为推荐的凭据类型。 托管标识是生产部署的首选选项，因为它们消除了机密管理。 在生产环境中也支持客户端密钥和证书。 若要减少迁移工作量，请考虑重用现有应用注册使用的相同凭据类型。

建议的凭据取决于托管环境：

配置凭据后，为蓝图创建服务主体。 在蓝图下创建代理标识之前，需要服务主体：

POST https://microsoftgraph.chinacloudapi.cn/v1.0/servicePrincipals
Content-Type: application/json

{
    "appId": "<blueprint-app-id>"
}

步骤 2：创建代理标识

若要完成此步骤，需要 代理 ID 开发人员 或 代理 ID 管理员 角色。

代理身份是您的代理在运行时使用的运行主体。 在蓝图下创建它，并为该代理指派一个发起人（必需），以及一个负责该代理的人工用户或用户组。 出于管理目的，建议分配 所有者 。

POST https://microsoftgraph.chinacloudapi.cn/beta/serviceprincipals/Microsoft.Graph.AgentIdentity
OData-Version: 4.0
Content-Type: application/json

{
    "displayName": "Customer Service Agent - Production",
    "agentIdentityBlueprintId": "<blueprint-app-id>",
    "sponsors@odata.bind": [
        "https://microsoftgraph.chinacloudapi.cn/v1.0/users/<sponsor-user-id>"
    ]
}

从响应中记录代理标识的客户端 ID。 更新应用程序代码时需要此值。

步骤 3：配置权限

将 API 权限从原始应用注册复制到代理标识。 若要完成此步骤，需要 特权角色管理员 角色才能授予需要管理员同意的应用程序权限。 您有两个选项：

• 直接分配： 直接将权限分配给代理标识。 当每个代理标识需要不同的权限时，请使用此选项。
• 继承的权限： 配置蓝图的权限并启用继承。 当蓝图下的所有代理标识共享相同的权限时，请使用此选项。

若要复制 Microsoft Graph 应用程序权限，请使用 appRoles API，向代理标识的服务主体授予相同的 。 对于委派权限，请使用 oauth2PermissionGrants API 添加所需的权限。 确保为需要管理员权限的应用程序权限授予管理员许可。

配置 OBO 支持（仅限交互式代理）

如果代理使用代表 （OBO） 流代表用户执行操作，则需要将自定义范围添加到蓝图中，以便前端应用程序可以为其请求令牌。 添加范围后，更新前端应用程序以请求蓝图资源的令牌，而非以前的资源。 有关完整的 OBO 配置演练，请参阅 交互式代理身份验证和授权流。

如果原始应用注册已分配 Azure RBAC 角色，请将相同的角色分配给新代理标识对应的服务主体，以便其能够在运行时访问所需的 Azure 资源：

New-AzRoleAssignment `
    -ObjectId "<agent-identity-service-principal-id>" `
    -RoleDefinitionName "Contributor" `
    -Scope "/subscriptions/<sub-id>/resourceGroups/<rg-name>"

步骤 4：更新应用程序代码

代理 ID 使用两阶段令牌获取模型。 代理首先使用蓝图的凭据获取启动令牌，然后将其交换为特定于代理的令牌。 有关更新代码的详细信息，请参阅以下方案：

• 自治智能体身份验证和授权流，获取完整令牌的分步指南。
• 交互式代理身份验证和授权流 ，用于交互式代理指南、代码示例和令牌配置。 在这些代理中的令牌流中，添加了 OBO 交换，用户令牌被交换为带有用户上下文的代理令牌。

阶段 4：验证和停用

迁移代理标识后，验证新代理 ID 在解除旧标识授权之前是否正常工作。

验证迁移的代理标识

并行运行旧身份和新身份

对于使用率较高的代理，请在切换之前并行运行旧标识和新标识：

1. 部署使用新代理 ID 配置的代理的并行实例。
2. 将流量百分比路由到新实例（从 5 到 10%开始）。
3. 监视两个实例的错误、延迟差异和权限问题。
4. 在一到两周的时间内逐渐增加对新实例的流量。
5. 在新的标识上运行 100% 流量后，继续停用。

使用特性标志或流量分配基础设施来控制发布。 此方法允许在出现问题时立即还原到旧标识。

退役安全措施

验证新智能体 ID 并承载生产流量后，停用旧标识。 遵循以下安全措施将风险降到最低：

• 删除前快照： 在删除之前导出服务主体的元数据、权限和审核历史记录。 如果验证期间遗漏了任何内容，则此导出提供回滚引用。
• 分阶段批处理： 如果要停用多个标识，请分批删除（每次 20-50 个服务主体），而不是一次性删除所有标识。
• 首先进行软删除：在执行硬删除之前，利用 Microsoft Entra 的软删除功能（提供给应用程序的 30 天回收站）。 此步骤提供恢复窗口。

停用原始应用注册

若要退役旧标识，请执行以下步骤：

1. 从旧应用注册中删除 API 权限。
2. 撤销旧服务主体的 Azure RBAC 角色分配。
3. 删除或轮换旧应用注册上的客户端机密和证书。
4. 删除应用注册（进入 30 天软删除）。
5. 30 天后，确认应用注册已永久删除或在需要时进行硬删除。

排查常见问题

下表列出了在迁移过程中可能会遇到的常见问题以及如何解决这些问题。

相关内容

• 代理标识概念
• 创建代理标识蓝图
• 创建和删除代理标识
• 代理 ID 的最佳做法