代理机群是在共享云运行时上运行的一组代理。 例如,允许团队或客户部署自己的代理的平台在同一计算和代码库上托管每个新代理。 车队中的每个代理都获得自己的 代理标识,因此其登录、权限和审核记录与其他代理保持独立。
运行时保存单个 代理标识蓝图 凭据,并使用它来获取从该蓝图创建的任何代理标识的令牌。 运行时选择要在每个令牌请求中使用的代理标识。
在单个代理和代理组之间进行选择
| 注意事项 | 单个代理 | 代理集合 |
|---|---|---|
| 每个部署的代理数 | 一个 | 许多项可在运行时添加和删除 |
| 创建代理标识时 | 在部署代理之前,由开发人员或管理员 | 当每个代理由运行时或 Agent 365 部署时 |
| 代理标识 ID 的来源 | Configuration | 每次请求时进行查找 |
| 如何授予访问权限 | 对于代理标识,在部署代理之前 | 在预配代理时,为每个代理标识 |
| Guidance | 使用 ASP.NET Core 构建云代理 或 Auth SDK sidecar | 本文及其后面的 fleet 相关文章 |
fleet 运行时为每个操作选择代理身份。 在整个学习过程中,请始终参考 fleet 示例:cloud-agent 教程使用一个已配置的身份,并省略了 fleet 所需的每次请求身份选择。
Components
| 组分 | Purpose | Cardinality |
|---|---|---|
| 代理标识蓝图 | 定义车队的权限、入站范围和应用角色。 创建和删除代理标识。 | 每个机群一个,或每个代理类型一个 |
| 蓝图凭据 | 以蓝图身份验证运行时。 在生产环境中使用托管标识联合凭据。 | 每个蓝图对应一个 |
| 代理标识 | 表示一个代理。 接收用于调用 API 的访问令牌。 | 每个代理一个 |
| 代理的用户帐户 | 为代理提供Microsoft 365工作负载(例如邮箱或 Teams 成员身份)的用户对象。 | 可选,每个代理标识最多一个 |
| 代理目录 | 运行时的存储,将每个代理映射到其代理标识和代理的用户帐户。 | 每个机队对应一个 |
| 预配服务 | 在部署和停用代理时创建和删除标识。 | 每个机队一个 |
| 令牌中介 | 获取给定代理标识的令牌。 Microsoft.Identity.Web(在运行时进程中)或 Auth SDK sidecar。 | 每个运行时对应一个或多个 |
代理生命周期
- 部署。 用户或管道将新代理部署到运行时。
- 规定。 预配服务从蓝图创建代理标识。 如果代理需要Microsoft 365用户功能,它还会创建代理的用户帐户。 它记录代理目录中的 ID,并授予代理标识此代理所需的访问权限。
- 跑。 对于每个操作,运行时都会在代理目录中查找代理的标识,并将其传递给令牌代理。
- 停用。 预配服务将删除代理的用户帐户,然后删除代理标识,并删除代理目录条目。
选择如何预配坐席
| 选项 | 工作原理 | 在以下情况下使用 |
|---|---|---|
| 运行时预配标识 | 预配服务作为蓝图进行身份验证,并调用Microsoft Graph来创建和删除代理标识和代理的用户帐户。 | 运行时控制代理部署。 |
| 代理 365 预配标识 | 代理 365 在预配代理时创建代理标识。 运行时侦听代理预配事件,其中包括代理标识 ID,并将其记录在代理目录中。 | 代理是通过Microsoft 365体验创建的。 有关详细信息,请参阅 Agent 365 开发人员文档。 |
这两个选项都生成相同的代理目录条目。 其余代理组指南适用于任一选项。
在每个请求中选择代理标识
蓝图凭据可以获取从蓝图创建的每个代理标识的令牌。 因此,选择代理标识的运行时代码是安全边界。
- 使用运行时控制的密钥(例如自己的代理 ID)从代理目录中解析代理标识。
- 不接受来自请求、提示或工具输出的代理标识客户端 ID 或代理的用户帐户 ID。
- 在请求令牌之前,确认调用方有权使用目标代理。
规划信任边界
- 使凭据远离代理代码。 将蓝图凭据保存在运行时或 sidecar 中,绝不在代理作者或模型控制的代码中。
- 隔离令牌代理程序。 如果代理运行不受信任的代码或客户提供的代码,请不要让该代码直接调用令牌代理程序。 可以访问中介服务的进程可以请求代理群组中任何代理的令牌。
- 将预配与令牌获取分开。 预配服务使用可创建和删除标识的蓝图令牌。 让它通过自己的访问路径运行,以便代理代码无法请求这些令牌。
- 限制波及范围。 当多个代理组在不同的信任区域中运行或属于不同客户时,请使用多个蓝图。
限制说明
蓝图主体最多可以创建 250 个代理标识。 对于更大的机群,请创建更多蓝图,并在预配每个代理时将其分配给某个蓝图。 在代理目录条目中记录蓝图。 有关详细信息,请参阅 代理标识蓝图主体。
以下实现文章使用每个运行时配置一个蓝图。 如果将它们扩展到多个蓝图,还解析每个代理的匹配蓝图配置和凭据;仅选择代理 ID 不会选择其他蓝图。 需要针对该设计扩展示例目录记录。
向每个代理授予访问权限
仅为每个代理标识提供其代理所需的访问权限。 将应用程序权限、委派权限、Azure 角色分配以及对其他资源的访问权限直接授予代理标识,作为预配的一部分或之后不久。 每个代理授予的授权使每个代理的访问权限保持独立,因此可以查看、更改或撤销一个代理的访问权限,而不会影响车队的其余部分。 有关授予访问权限的方法,请参阅 “授予应用程序权限 ”和 “授予委派权限”。
对于车队中每个代理所需的权限,为了方便,可以使用 可继承的权限。 管理员在蓝图主体上授予这些权限一次,从蓝图创建的每个代理标识都会在其令牌中接收这些权限。 继承的权限不会显示在代理标识上,因此每个代理的授权更易于审核。
将用户请求路由到代理
用户使用针对蓝图的 access_agent 范围的访问令牌调用机群代理。 机群中的每个代理共享该受众,因此令牌可证明用户是谁,但不标识代理。 运行时必须:
- 根据请求确定目标代理,例如根据路由段。
- 确认允许用户使用该代理。 蓝图上的应用角色适用于整个机群,因此需要在运行时针对每个代理实施访问控制。
- 将目标代理的标识用于任何 On-Behalf-Of (OBO) 令牌请求。