使用 Microsoft Entra ID 身份验证 SDK （sidecar）获取令牌并调用下游 API

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

先决条件

在开始之前，请确保：

部署容器化服务

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

配置 Microsoft Entra ID 身份验证 SDK（sidecar）设置

请按照以下步骤配置 Microsoft Entra ID 身份验证 SDK（sidecar）设置：

Warning

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

在 Microsoft Entra ID 中设置必要的组件。确保在 Microsoft Entra ID 租户中注册应用程序。
配置客户端证书。此凭据可以是您正在使用的客户端机密、证书或作为联合标识凭据的托管标识。
如果要调用下游 API，请确保授予必要的权限。调用自定义 Web API 需要你在 SDK 配置中提供 API 注册详细信息。

有关详细信息，请参阅配置Microsoft Entra ID身份验证 SDK （sidecar）设置。

使用 Microsoft Entra ID 身份验证 SDK （sidecar）获取令牌

以下是使用 Microsoft Entra ID 身份验证 SDK（sidecar）获取令牌的步骤：

使用 Microsoft Entra ID 身份验证 SDK（sidecar）获取令牌。这因代理是自主作还是代表用户运行而异。需要考虑三种方案：
- 自治代理：代理通过为其创建的服务主体，自主进行运作。
- 自治代理的用户帐户：代理使用专门为代理创建的用户主体（例如代理具有自己的邮箱）自行操作。
- 交互式代理：这些代理代表人类用户操作。
根据 Microsoft Entra ID 身份验证 SDK（sidecar）配置，通过在请求 URL 中包含下游 API 的名称来指定该 API。授权标头终结点采用 SDK 设置中配置的下游 API 的名称的格式/AuthorizationHeader/{serviceName}serviceName。

若要获取自治代理的仅限应用（客户端凭据）令牌，请在请求中提供代理标识客户端 ID。

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

若要获取自治代理用户帐户的令牌，请提供用户对象 ID 或用户主体名称，但不能同时提供这两者。这意味着提供AgentUsername或AgentUserId。提供这两者都会导致验证错误。还必须提供 AgentIdentity 来指定用于令牌获取的代理标识。如果缺少代理标识参数，则请求失败并出现验证错误。
```
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>&AgentUserId=<agent-user-object-id>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```
```
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-identity-client-id>&AgentUsername=<agent-user-principal-name>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```
对于交互式代理，请使用代表用户 (OBO) 流程。在获取资源令牌以调用下游 API 之前，代理首先验证向其授予的用户令牌。

代理 Web API 从调用应用接收用户令牌，并通过 Microsoft Entra ID 身份验证 SDK（sidecar）/Validate 终结点验证该令牌；仅使用 AgentIdentity 和传入的授权标头调用 /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-identity-client-id>
Authorization: Bearer <user-token>
```

调用 API

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

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

Last updated on 2026-09-03