通过

使用 Microsoft Entra SDK for Agent ID 获取令牌并调用下游 API

用于代理 ID 的 Microsoft Entra SDK 是一种容器化 Web 服务，用于处理代理的令牌获取、验证和下游 API 调用。 无论技术堆栈如何，此 SDK 都通过 HTTP API 与应用程序通信，提供一致的集成模式。 Microsoft Agent ID 的 Entra SDK 通过标准 HTTP 请求管理令牌获取、验证和 API 调用，而不是直接在应用程序代码中嵌入标识逻辑。

先决条件

在开始之前，请确保具备：

部署容器化服务

将 Microsoft Entra SDK for Agent ID 部署为环境中的容器化服务。 按照“设置 Microsoft Entra SDK for Agent ID 指南”中的说明，使用代理身份详细信息配置该服务。

为 Microsoft Entra SDK 配置代理 ID 设置

请按照以下步骤配置 Microsoft Entra SDK 的代理 ID 设置选项：

警告

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

  1. 在 Microsoft Entra ID 中设置必要的组件。 确保在 Microsoft Entra ID 租户中注册应用程序。

  2. 配置客户端证书。 此凭据可以是您正在使用的客户端机密、证书或作为联合标识凭据的托管标识。

  3. 如果要调用下游 API，请确保授予必要的权限。 调用自定义 Web API 需要你在 SDK 配置中提供 API 注册详细信息。

有关更多信息，请参阅 配置 Microsoft Entra SDK 以设置 AgentID

使用用于代理 ID 的 Microsoft Entra SDK 获取令牌

以下是使用用于代理 ID 的 Microsoft Entra SDK 获取令牌的步骤：

  1. 使用用于代理 ID 的 Microsoft Entra SDK 获取令牌。 这因代理是自主作还是代表用户运行而异。 需要考虑三种方案：

    • 自治代理：代理通过为其创建的服务主体，自主进行运作。
    • 自主代理用户：代理使用专门为代理创建的用户主体（例如代理拥有自己的邮箱）进行自主操作。
    • 交互式代理：这些代理代表人类用户操作。

    根据代理 ID SDK 配置在请求 URL 中包括其名称来指定下游 API。 授权标头终结点采用 SDK 设置中配置的下游 API 的名称的格式/AuthorizationHeader/{serviceName}serviceName。

  2. 若要为自主代理获取仅供应用程序使用的令牌，请在请求中提供代理身份客户端 ID。

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-ID>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  3. 若要获取自治代理用户的令牌，请提供用户对象 ID 或用户主体名称，但不同时提供这两者。 这意味着提供AgentUsername或AgentUserId。 提供这两者都会导致验证错误。 还必须提供 AgentIdentity 来指定用于令牌获取的代理标识。 如果缺少代理标识参数，则请求失败并出现验证错误。

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUserId=<agent-user-object-id>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUsername=<agent-user-principal-name>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  4. 对于交互式代理，请使用代表流。 在获取资源令牌以调用下游 API 之前，代理首先验证向其授予的用户令牌。

    代理 Web API 从调用应用程序接收用户令牌，并通过代理 ID SDK /Validate 终结点验证该令牌；然后只需调用/AuthorizationHeader 和传入的授权标头，以获取下游 API 的令牌。

    # Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

调用 API

获取用于调用下游 API 的授权标头时，Microsoft Entra 的 Agent ID SDK 返回的 Authorization 标头值可以直接在 API 调用中使用。

可以使用此标头调用下游 API。 Web API 应通过调用 Microsoft Entra SDK 提供的用于代理 ID 的/Validate终结点来验证令牌。 此终结点返回的令牌声明可用于进一步做出授权决策。

相关内容

  • Last updated on