用户池客户端 OIDC 协议和使用

本指南面向已经创建好 identity 客户端的团队，帮助你把应用接入到 identity，并将所属 identity UserPool 的运行时作为 OpenID Connect（OIDC）issuer 来使用。

能力

主题	说明
适用对象	已创建 identity 客户端，并准备通过 OIDC 集成应用的团队。
运行时依据	应用应以 identity UserPool 暴露的 issuer 和 discovery 文档作为端点配置依据。
典型流程	常见接入方式是 authorization code flow，并结合 JWKS 校验 ID token。

identity 提供什么

对于每个 identity UserPool，identity 都会暴露标准 OIDC 运行时端点，应用应以这些端点作为配置依据。

这些端点包括：

issuer

discovery 文档

authorization 端点

token 端点

UserInfo 端点

JWKS 端点

前置条件

已创建并启用一个 identity UserPool

已在该 identity UserPool 下创建客户端

客户端已配置至少一个合法的重定向 URI

你已经拿到客户端标识；如果是 confidential client，还需要客户端密钥

控制台引导

OIDC 客户端接入在实际操作中最适合按四个界面顺序校验：先确认 UserPool，再查看真实客户端详情页，然后再对照客户端配置表单，最后读取 discovery 元数据。

先从真实 identity 控制台首页确认目标 UserPool 已存在，并且当前操作处于正确的租户边界中。

再打开真实客户端详情页，确认当前 Client ID、回调地址、登录页 URL 以及 Token 时长配置，再继续填写依赖方应用参数。

当您需要回看建连时的表单结构时，再通过客户端创建界面对照客户端类型和回调地址配置。

最后通过 discovery 与 issuer 元数据界面获取精确运行时值，而不是手工拼接端点路径。

管理 API

当前产品 admin surface 没有直接建模终端用户的 authorize 或 token 运行时请求，但它清楚地表明了哪些控制面 Action 用于为 OIDC 运行时接入做准备。

管理目标	对应 Action	通常最关键的请求字段
创建依赖 identity 的应用	CreateUserPoolClient、GetUserPoolClient、ListUserPoolClients、UpdateUserPoolClient	UserPoolUid、ClientUid、Name、ClientType、AllowedCallbackUrls、AllowedLogoutUrls、AllowedWebOrigins、AllowedCors
配置 consent 和托管登录行为	CreateUserPoolClient、UpdateUserPoolClient	SkipConsentEnabled、DismissLoginPageEnabled、DevelopmentModeEnabled、LogoUri
决定令牌与授权模式	CreateUserPoolClient、UpdateUserPoolClient	IdToken、RefreshToken、DeviceFlowEnabled
确保 issuer 在正确边界上可用	CreateUserPool、GetUserPool、UpdateUserPool	UserPoolUid，以及会影响 issuer 与托管登录体验的品牌、域名和登录设置

关键 API 参数

admin surface 清楚表明，OIDC 集成是否顺利，取决于控制面客户端配置是否与应用在运行时实际发送的请求保持一致。

字段或字段块	作用说明
AllowedCallbackUrls	必须包含授权请求中实际使用的 redirect_uri。这是 OIDC 中最关键的浏览器回调白名单。
AllowedLogoutUrls	当应用在登出后需要浏览器跳转回指定地址时，必须与实际目标保持一致。
AllowedWebOrigins 和 AllowedCors	对前端应用直接从浏览器调用运行时端点的场景尤为重要。
ClientType	决定接入的是哪类应用模型，以及哪些授权模式更适合。
SkipConsentEnabled	影响运行时授权过程中是否可能展示 consent 页面。
DismissLoginPageEnabled	会改变登录路由行为，因为在绕过托管登录页时，authorize 请求需要显式指定目标 identity_provider。
DeviceFlowEnabled	会改变支持的授权姿态，适用于需要 device code 行为的原生或受限输入设备场景。
IdToken 和 RefreshToken	影响令牌生命周期与刷新行为，从而直接影响依赖方应用的会话设计。
identity UserPool 的品牌与域名设置	会影响 issuer 主机名，以及用户在登录过程中看到的托管体验。

集成步骤

从 identity UserPool 运行时信息中获取 issuer URL。

读取 discovery 文档，确认精确的端点地址和支持能力。

为应用配置以下参数：

issuer

client_id

client_secret（仅 confidential client 需要）

redirect_uri

按需申请 openid、profile、email 等 scope

将终端用户重定向到 authorization 端点，启动 authorization code flow。

在 token 端点用 authorization code 交换令牌。

使用同一 issuer 发布的 JWKS 校验 ID token 签名。

当应用需要额外资料声明时，调用 UserInfo 端点。

配置模板

可以按下面的方式在应用配置中使用占位符：

Discovery 示例

Authorization Code 与 Token 示例

先在浏览器中打开授权地址：

然后使用 authorization code 交换令牌：

UserInfo 示例

使用提示

优先通过 discovery 文档读取精确的运行时端点地址，而不是手工猜测固定路径

为客户端注册与授权请求中完全一致的重定向 URI

只有在应用需要额外资料声明时，才调用 UserInfo 端点

安全注意事项

将客户端密钥保存在密钥管理系统中，不要提交到代码仓库

为客户端注册精确的重定向 URI，避免过宽的匹配范围

始终校验 state 和 nonce，降低重放和 CSRF 相关风险

校验令牌的 iss、aud、exp 以及签名

下一步

客户端

identity UserPool

产品概览

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