无头身份验证

本指南面向需要在不展示托管登录页的情况下签发 identity 令牌的团队。内容覆盖两类运行时模式：使用 InitiateAuth 完成本地用户名密码或刷新令牌认证，以及使用 ExternalIdentityProviderTokenExchange 将受信任的上游身份提供方令牌交换为 identity 令牌。

能力摘要

方法	适合场景	主要运行时调用	主要结果
InitiateAuth + USER_PASSWORD_AUTH	第一方应用直接收集 identity 原生用户的用户名和密码	POST /api/v1/InitiateAuth 或 POST /userpool/{UserPoolUid}/api/v1/InitiateAuth	identity access token、ID token、refresh token 和过期时间
InitiateAuth + REFRESH_TOKEN_AUTH	已经持有 refresh token，需要续期会话	同一个 InitiateAuth 端点	同一客户端上下文下的新令牌响应
ExternalIdentityProviderTokenExchange	另一个 OIDC 或 OAuth 提供方已经完成用户认证，需要换取 identity 令牌	POST /api/v1/ExternalIdentityProviderTokenExchange 或 POST /userpool/{UserPoolUid}/api/v1/ExternalIdentityProviderTokenExchange	identity access token、ID token、refresh token、token type 和过期时间

前置条件

使用 InitiateAuth 前

已创建并启用 identity UserPool。

该 UserPool 下已经创建客户端。

对于 USER_PASSWORD_AUTH，目标用户必须是带可用密码的 identity 原生用户，并且 UserPool 已启用密码登录。

对于 REFRESH_TOKEN_AUTH，调用方已经持有同一客户端上下文下签发的有效 refresh token。

如果客户端有 client secret，请在 AuthParameters 中携带 SECRET_HASH。计算方式是：对 USER_PASSWORD_AUTH 使用 {USERNAME}{ClientId}，对 REFRESH_TOKEN_AUTH 使用 {REFRESH_TOKEN}{ClientId}，以 client secret 作为 HMAC-SHA256 密钥计算后再做 Base64 编码。

使用联邦 Token Exchange 前

同一个 UserPool 中已经存在并启用一个 Token Exchange 连接。

连接已经配置为您要使用的上游提供方类型：OIDC 或 OAuth。

调用 identity 前，您能够先从上游身份提供方获取有效令牌。

对于 OIDC，上游提供方需要暴露 issuer discovery 和密钥；可交换的 subject token 可以是 ID token 或 access token。使用 access token 交换时，上游需要提供可用的 UserInfo endpoint。

对于 OAuth，subject token 是上游 access token，连接需要配置 UserInfo endpoint 以及用于识别上游用户的用户 ID 属性路径。

用于换取 identity 令牌的客户端必须存在于同一个 UserPool。如果该客户端有 client secret，请在交换请求中提供 ClientSecret。

Token Exchange 连接中的 audience、client、scope 或 claim-value 允许规则必须与上游 token 或 UserInfo claims 匹配。

流程 1：通过 InitiateAuth 完成原生用户密码登录

当应用直接收集原生用户登录标识和密码时，使用该流程。

请求结构

示例

响应字段

字段	含义
AuthenticationResult.AccessToken	用于调用接受 identity access token 的 API。
AuthenticationResult.IdToken	已认证用户的 OIDC 身份令牌。
AuthenticationResult.RefreshToken	后续通过 REFRESH_TOKEN_AUTH 续期会话时使用。
AuthenticationResult.ExpiresIn	access token 的有效期，单位为秒。

流程 2：通过 InitiateAuth 刷新令牌

当应用已经持有 refresh token，并且希望不重新要求用户登录就获取新令牌时，使用该流程。

在运营上，请对 refresh token 做加密存储，按客户端策略进行轮换，并在刷新失败时回退到交互式登录路径。

流程 3：联邦 Token Exchange

当外部 OIDC 或 OAuth 提供方已经完成用户认证，并且应用可以向 identity 提交受信任上游令牌时，使用该流程。

请求结构

如果上游是 OAuth 提供方，请使用 SubjectTokenType 值 urn:ietf:params:oauth:token-type:access_token。如果上游是 OIDC 提供方，可以在需要基于签名校验时使用 ID token；也可以使用 access token，并通过提供方的 UserInfo endpoint 解析 claims。

identity 会检查什么

检查项	为什么重要
客户端查找与可选 ClientSecret 校验	确认交换请求绑定到已知 identity 客户端。
Token Exchange 连接查找	确认所选连接属于客户端所在 UserPool，并且处于启用状态。
上游 OIDC 或 OAuth 令牌校验	确认令牌有效、未过期，并且可以识别外部用户。
允许规则	在 claims 可用后执行 AllowedAudiences、AllowedClients、AllowedScopes 和 AllowedClaimsAndValues。
账号落地策略	使用连接的 provider options 和属性映射来解析、创建、关联或更新 identity 用户。

响应字段

管理 API

管理目标	暴露动作	最值得关注的请求字段
创建接收令牌的客户端	CreateUserPoolClient、UpdateUserPoolClient	UserPoolUid、ClientType、令牌时长字段、refresh token 设置和 client secret 行为
启用原生密码登录姿态	CreateUserPool、UpdateUserPool、UpdateEnableUserPool	UserPool 登录开关与状态字段
创建 Token Exchange 信任对象	CreateIdentityProviderTokenExchange	ProviderType、ExternalIdentityProviderConfiguration、AllowedAudiences、AllowedClients、AllowedScopes、AllowedClaimsAndValues、ProviderOptions、ClaimsPropagationConfig、AttributeMappings
维护 Token Exchange 策略	GetIdentityProviderTokenExchange、ListIdentityProvidersTokenExchange、UpdateIdentityProviderTokenExchange	UserPoolUid、ConnectionUid、允许规则、映射和 provider options

运营注意事项

当同一个 host 暴露多个 UserPool 时，优先使用 /userpool/{UserPoolUid}/api/... 形式，让调用方明确租户边界。

谨慎选择 Scopes。只有客户端确实需要 refresh token 时才加入 offline_access。

对于 OIDC token exchange，请确认上游 issuer URL 稳定，并且 discovery document 发布有效的 JWKS URI。

对于 OAuth token exchange，请确认 UserInfo 响应中包含连接配置的用户 ID 属性路径。

如果外部令牌被拒绝，请先检查连接启用状态、provider type、subject token type、client secret 以及允许列表取值，再考虑放宽信任策略。

下一步

Token Exchange 连接

OIDC 连接

OAuth 连接

客户端

用户

OIDC 客户端使用指南

智能体身份和权限管理平台