用于代理 ID 的 Microsoft Entra SDK 是一种容器化 Web 服务，用于处理令牌获取、验证和安全下游 API 调用。 它作为配套容器与应用程序一起运行，使你可以将标识逻辑卸载到专用服务。 通过在用于代理 ID 的 Microsoft Entra SDK 中集中标识操作，无需在每个服务中嵌入复杂的令牌管理逻辑，从而减少代码重复和潜在的安全漏洞。
如果正在使用 Kubernetes、Docker 容器化服务或在 Azure 上构建现代微服务，Microsoft Entra SDK for Agent ID 提供了一种标准化的方法，用于处理云原生应用程序中的身份验证和授权。
什么是 Microsoft Entra SDK 的代理 ID？
用于代理 ID 的 Microsoft Entra SDK 通过 HTTP API 与应用程序通信，以实现身份验证和授权，无论技术堆栈如何，都提供一致的集成模式。 Microsoft Entra SDK for Agent ID 通过标准 HTTP 请求处理令牌管理、验证和 API 调用，而不是直接在应用程序代码中嵌入标识逻辑。
此方法支持 polyglot 微服务体系结构，其中不同的服务可以采用 Python、Node.js、Go、Java 和其他服务编写，同时保持一致的身份验证模式。
典型的体系结构如下所示：
客户端应用程序 → 你的 Web API → Microsoft Entra SDK 用于代理 ID → Microsoft Entra ID
有关最新的容器映像和版本标记，请参阅 容器映像 以开始使用。
安全性
确保用于代理 ID 部署的 Microsoft Entra SDK 遵循安全操作的最佳做法。 SDK 必须在具有受限网络访问的容器化环境中运行，以防止未经授权的访问。 公开 SDK API 可能会导致安全漏洞，例如未经授权的令牌获取。
请参阅 安全最佳做法 ，确保网络、凭据和运行时安全建议的最佳做法。
注意
SDK API 不得公开访问。 只有同一信任边界（例如，同一 Pod 或虚拟网络）的应用程序才能访问它，以防止令牌被未经授权地获取。
快速入门
若要开始使用适用于代理 ID 的 Microsoft Entra SDK，建议执行以下步骤：
主要优势
该体系结构将标识问题与业务逻辑分开，提供以下优势：
| 益处 | Description |
|---|---|
| 多语言支持 | 通过 HTTP 从 Python、Node.js、Go、Java 等进行调用 |
| 集中式安全配置 | 标识配置、令牌管理和凭据管理的一个位置 |
| 容器原生 | 为 Kubernetes、Docker、AKS 和其他新式部署构建 |
| 零信任 Ready | 与托管标识和所有权证明令牌集成 - 使敏感数据远离应用程序代码 |
何时使用 Microsoft Entra SDK 来处理 Agent ID 或 Microsoft Identity.Web
| Scenario | 将 Microsoft Entra SDK 用于代理标识 | 使用Microsoft。Identity.Web |
|---|---|---|
| 语言支持 | 多种语言（Python、Node.js、Go、Java等） | 仅适用于.NET |
| 部署模型 | 容器（Kubernetes、Docker、AKS） | 任何部署模型 |
| 标识模式 | 所有服务的一致模式 | 深度.NET框架集成 |
| 代理标识 | 在所有受支持的语言中可用 | 仅限于.NET |
| 令牌验证 | 在所有受支持的语言中可用 | 仅限于 .NET |
| 安全模型 | 与应用程序代码相隔离的机密和令牌 | 与应用程序集成 |
| 性能 | 需要额外的网络跃点 | 直接进程内调用 |
| 框架集成 | HTTP API 集成 | 原生.NET集成 |
| 容器化 | 专为容器化环境而设计 | 可在使用或不使用容器的情况下运行 |
请参阅 与 Microsoft.Identity.Web 的比较以获取在两种方法之间进行选择时的详细指导。
令牌验证
用于代理 ID 的 Microsoft Entra SDK 验证Microsoft Entra ID颁发的访问令牌和 ID 令牌、根据Microsoft Entra ID公钥验证其签名、检查过期时间以及确保令牌适用于应用程序。 验证后，可以提取用户声明、角色和作用域，以在应用程序逻辑中做出明智的授权决策。
令牌获取/授权标头创建
- On-Behalf-Of OAuth 2.0 流程 - 将用户上下文委派给后续 API
- 客户端凭据 - 应用程序到应用程序身份验证
- Managed Identity - 本机Azure服务身份验证
- 代理标识 - 自治代理模式或委派代理模式
下游 API 调用
- 自动获取和附加令牌
- 可选请求替代（范围、方法、标头）
- 签名 HTTP 请求 （PoP/SHR）支持
场景和教程
以下指南是全面的分步教程，其中演示了如何将用于代理 ID 的 Microsoft Entra SDK 集成到应用程序中的实际代码示例。 每个方案都提供针对不同编程语言和框架定制的完整的请求/响应示例、代码片段和实现模式。
| Scenario | Description |
|---|---|
| 验证授权标头 | 从持有者令牌中提取声明以用于访问控制和自定义授权中间件 |
| 获取授权标头 | 获取用于安全地调用下游 API 的令牌 |
| 调用下游 API | 使用多语言微服务的自动令牌附件对受保护的 API 进行 HTTP 调用 |
| 使用托管标识 | 作为 Azure 服务进行身份验证，以调用 Microsoft Graph 或其他 Azure 服务 |
| 实现 Long-Running OBO 流 | 使用刷新令牌和 On-Behalf-Of 委派在长期操作时处理用户上下文 |
| 使用签名的 HTTP 请求 | 使用 PoP 令牌实现所有权证明安全性 |
| 代理自治批处理 | 使用自治代理标识处理批处理作业 |
| 从 TypeScript 集成 | 在 Node.js/Express/NestJS 应用程序中使用 Microsoft Entra SDK 用于 Agent ID |
| 从 Python 集成 | 在 Flask/FastAPI/Django 应用程序中使用 Microsoft Entra SDK 获取代理 ID |
体系结构模式
客户端调用 Web API 的典型流，API 通过 HTTP 终结点将标识操作委托给 Microsoft Entra SDK for Agent ID。 SDK 使用/Validate终结点验证入站令牌，使用/AuthorizationHeader和/AuthorizationHeaderUnauthenticated获取令牌，并可以直接使用/DownstreamApi和/DownstreamApiUnauthenticated调用下游 API。
它与用于令牌颁发和 Open ID Connect 元数据检索的Microsoft Entra ID交互，体系结构在以下代码片段中演示：
%%{init: {
"theme": "base",
"themeVariables": {
"background": "#121212",
"primaryColor": "#1E1E1E",
"primaryBorderColor": "#FFFFFF",
"primaryTextColor": "#FFFFFF",
"textColor": "#FFFFFF",
"lineColor": "#FFFFFF",
"labelBackground": "#000000"
}
}}%%
flowchart LR
classDef dnode fill:#1E1E1E,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
linkStyle default stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
client[Client Application]:::dnode -->| Bearer over HTTP | webapi[Web API]:::dnode
subgraph Pod / Host
webapi -->|"/Validate<br/>/AuthorizationHeader/{name}<br/>/DownstreamApi/{name}"| sidecar[Microsoft Entra SDK for Agent ID]:::dnode
end
sidecar -->|Token validation & acquisition| entra[Microsoft Entra ID]:::dnode
支持和资源
以下资源提供全面的指导和帮助，帮助排查问题和常见问题的解答。
| Resource | Description |
|---|---|
| 代理标识 | 了解适用于高级场景的自治代理模式和委派代理模式 |
| API 参考 | 包含请求/响应格式、查询参数和错误代码的完整终结点文档 |
| 故障 排除 | 部署和运行时问题的常见问题和分步解决方案 |
| 常见问题 | 涵盖配置、安全性和集成主题的常见问题解答 |
如需其他帮助：
- 报告有关 Microsoft-identity-web 存储库 的问题
- 检查 Microsoft Entra ID 故障排除指南