为代理选择身份验证协议

正确的身份验证协议取决于代理的运行位置及其用于访问资源的标识。 从这些问题开始:

  1. 代理在用户的设备上运行,还是作为托管服务运行?
  2. 代理是代表已登录用户、代表自身,还是代表专用代理用户帐户?
  3. 如果代理对已登录用户执行操作,代理是否启动登录或从另一个应用程序接收用户访问令牌?

使用Microsoft 身份验证库(MSAL)或其他受支持的身份验证库,而不是直接构造协议请求。

警告

Microsoft 建议使用经认可的 SDK 和库(如 Microsoft.Identity.Web 和 Microsoft Entra ID 身份验证 SDK(sidecar)库)来实现这些协议。 手动实现这些协议非常复杂且容易出错,并且使用 SDK 有助于确保安全性和符合最佳做法。

选择协议

用例 推荐协议 访问类型 客户端类型
本地代理在终结点设备上运行并使用户登录 使用用于代码 Exchange 的证明密钥(PKCE)的授权代码流 委托的 Public
托管代理从客户端应用程序接收用户访问令牌,并为该用户调用另一个服务 代理 (OBO) 流 委托的 Confidential
托管代理在没有用户的情况下运行,并作为自身访问资源 客户端凭据流;多实例代理 ID 的蓝图身份模拟 Application Confidential
自治代理需要邮箱或其他仅对某个用户可用的资源 代理的用户帐户身份模拟 分配给代理用户帐户的委派权限 Confidential

如果有多行适用,请为每个操作模式使用单独的令牌获取路径。 例如,托管代理可能会对用户发起的请求使用 OBO,并且仅对没有用户上下文的计划工作进行应用访问。

蓝图的 实例模式 也会影响令牌获取。 单实例代理 ID(预览版)直接使用共享蓝图客户端 ID 对授权代码、刷新令牌、客户端凭据和 OBO 请求进行授权。 它不获取中间蓝图身份模拟令牌。 单实例模式不限于本地或公共客户端。 有关同意和 SDK 演练的概述和链接,请参阅 单实例代理标识的身份验证。 若要从特定于平台的演练开始,请参阅 选择代理的集成路径。

可让用户登录的本地代理

当代理满足以下情况时,选择带 PKCE 的授权代码流:

  • 在桌面、移动设备或其他终结点上运行。
  • 可以打开浏览器进行交互式登录。
  • 访问已登录用户的受保护服务。
  • 无法安全地存储客户端机密、证书或联合标识凭据。

本地代理是公共客户端。 它将用户发送到Microsoft 标识平台/authorize终结点,在其已注册的重定向 URI 处接收授权代码,并使用 PKCE 验证程序兑换代码。 它不提供客户端凭据。

已注册的公共客户端代理 ID 必须使用 单实例模式。 每个安装都使用相同的客户端 ID;不要为每个设备创建代理 ID。 本地代理还可以使用 客户端 ID 元数据文档 (CIMD) URL 作为客户端 ID。

不要对此类从其他应用程序接收用户访问令牌的托管代理使用此流程。 请改用 OBO。

有关实现和协议的详细信息,请参阅:

为已登录用户操作的托管代理

在以下情况下选择 OBO 流:

  • 客户端应用程序让用户登录。
  • 客户端使用用户访问令牌调用托管代理或其 API。
  • 代理必须使用用户标识和委派权限调用下游 API。

托管代理是机密客户端。 它不会启动另一个交互式登录。 而是将传入的用户访问令牌交换为用于访问下游资源的令牌。 传入令牌必须适用于代理的蓝图;不要中继为另一资源颁发的令牌。

对于多实例代理 ID,请将所需的委派权限配置为蓝图上的可继承权限并获取管理员同意。

如果没有登录用户启动操作,请不要使用 OBO。 对无人参与的工作使用仅限应用的访问权限。

有关实现和协议的详细信息,请参阅:

充当其自身的托管代理

当代理满足以下情况时,选择带有 Agent ID 模拟的客户端凭据流:

  • 在可以保护凭据的托管服务中运行。
  • 执行计划、事件驱动或其他自治工作。
  • 以代理 ID 而不是用户身份访问资源。

对于多实例代理 ID,蓝图首先对其子代理 ID 进行身份验证并获取令牌交换令牌。 然后,代理 ID 使用该令牌作为客户端凭据流中的客户端断言。 单实例代理 ID 改为使用共享客户端 ID 和蓝图上的凭据直接进行身份验证。 资源令牌包含管理员授予的应用程序权限,并将代理 ID 标识为行为主体。

当托管环境支持它们时,请使用托管标识和联合标识凭据。 避免客户端机密。

托管标识集成

对于Azure托管代理,当托管服务提供托管标识时,首选托管标识。 其令牌通过配置的联合标识凭据对父蓝图进行身份验证;单独配置托管标识不会授予 API 对代理的访问权限。 本地开发人员Azure CLI登录不是托管标识。 有关托管要求和本地凭据替代项,请参阅“配置蓝图凭据”。

警告

由于安全风险,客户端机密不应在生产环境中用作代理标识蓝图的客户端凭据。 而是使用更安全的身份验证方法 ,例如将联合标识凭据(FIC)与托管标识 或客户端证书配合使用。 这些方法通过消除直接在应用程序配置中存储敏感机密的需要,从而提供增强的安全性。

当资源应应用已登录用户的权限或用户同意时,请勿使用应用程序权限。 请改用带 PKCE 的授权代码流或 OBO 流程。

有关实现和协议的详细信息,请参阅:

充当专用用户的自治代理

仅当自治代理需要用户可用的功能而不是应用程序标识时,才选择代理的用户帐户模拟。 例如,代理可能需要自己的邮箱。

代理的用户帐户是代理的专用用户标识,而不是使用代理的人员的帐户。 代理 ID 通过特定于代理的令牌交换冒充此帐户身份。 访问权限受分配给代理 ID 和代理用户帐户的权限限制。

不要仅为了运行无人参与的工作而创建代理程序的用户帐户。 如果资源支持应用程序权限,则首选仅限应用的访问权限,以便工作负荷不依赖于用户标识。

有关实现详细信息,请参阅:

以下设置会影响身份验证,但不能替代协议选择:

  • 公共或机密客户端 描述代理是否可以安全地保存凭据。 有关详细信息,请参阅 公共客户端和机密客户端应用程序。
  • 托管标识、证书、客户端密码或联合标识凭据 描述机密客户端如何证明其标识。 尽可能首选托管标识和联合标识凭据。
  • CIMD 或已注册的客户端 ID用于描述如何标识公共客户端。 这两个选项都可以将授权代码流与 PKCE 配合使用。
  • 刷新令牌 允许客户端在不重复原始授权的情况下获取新的访问令牌。 它继续现有的委托会话;它不是单独的操作模型。