📚 课程目录第1章 OIDC协议基础

1. OIDC 协议基础：OIDC 与 OAuth 2.0 的关系、ID Token 结构、OpenID Provider 角色

1.1 OIDC 与 OAuth 2.0 的关系

OpenID Connect (OIDC) 是在 OAuth 2.0 协议之上构建的身份认证层。OAuth 2.0 本身只解决授权问题——允许第三方应用获取受保护的资源（如 API）；而 OIDC 在此基础上增加了身份认证能力，使客户端能够验证终端用户的身份并获取用户的基本信息。

维度	OAuth 2.0	OIDC
核心目标	授权：颁发 Access Token 访问资源	认证 + 授权：验证用户身份并颁发 ID Token
Token 类型	Access Token（不透明或 JWT）	ID Token（JWT）+ Access Token
用户信息	不直接提供	通过 ID Token 和 UserInfo Endpoint 获取
协议层	授权框架	在 OAuth 2.0 之上增加身份层
典型场景	API 授权、设备授权	单点登录 (SSO)、用户登录

  关键理解：OIDC 不是替代 OAuth 2.0，而是扩展。OAuth 2.0 提供 Access Token 用于访问资源，OIDC 额外提供 ID Token 用于证明用户身份。在异步任务调试中，ID Token 的验证失败往往是认证流程卡住的根本原因。

下图展示了 OIDC 在 OAuth 2.0 授权码流程上的扩展关系：

1.2 ID Token 结构详解

ID Token 是一个 JWT (JSON Web Token)，由三部分组成：Header、Payload、Signature。在异步任务调试中，ID Token 的解析和验证是排查认证失败的核心环节。

1.2.1 ID Token 的三段式结构

// 示例 ID Token (JWT)
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiIxMjM0NTY3ODkwIiwiYXVkIjoiY2xpZW50X2lkIiwiZXhwIjoxNzAwMDAwMDAwLCJpYXQiOjE2OTk5OTY0MDAsIm5vbmNlIjoiYWJjMTIzIn0.
signature_value_here

部分	内容	调试关注点
Header	签名算法 (alg)、Token 类型 (typ)	alg 必须与 OP 的 JWKS 端点公开的算法一致
Payload	Claims：iss、sub、aud、exp、iat、nonce 等	iss 和 aud 验证失败是常见错误
Signature	使用 OP 私钥签名，客户端用公钥验证	签名验证失败通常意味着 Token 被篡改或密钥不匹配

1.2.2 核心 Claims 字段

Claim	含义	验证规则
`iss`	签发者 (Issuer)	必须与 OP 的 issuer 标识完全一致
`sub`	用户唯一标识 (Subject)	在同一 issuer 下唯一，不可变
`aud`	受众 (Audience)	必须包含客户端的 client_id
`exp`	过期时间 (Expiration)	当前时间必须小于 exp
`iat`	签发时间 (Issued At)	可用于判断 Token 新鲜度
`nonce`	一次性随机值	防止重放攻击，必须与认证请求中的 nonce 一致
`auth_time`	用户认证时间	可选，用于判断认证会话时长

调试提示：在开发环境中，使用 jwt.io 或 jwt-cli 工具解码 ID Token 的 Payload 部分，检查 iss、aud、exp 三个字段是否与 OP 配置一致。这是异步任务中 Token 验证失败的最常见原因。

1.3 OpenID Provider 角色

OpenID Provider (OP) 是 OIDC 协议中的核心实体，负责认证用户身份并颁发 ID Token。在异步任务调试中，OP 的配置和端点可用性直接影响流程的成败。

1.3.1 OP 的核心职责

用户认证：验证用户的身份凭证（用户名/密码、MFA、SSO 等）
Token 签发：生成并签名 ID Token 和 Access Token
密钥管理：维护 JWKS (JSON Web Key Set) 用于 Token 签名和验证
端点暴露：提供认证端点、Token 端点、UserInfo 端点、JWKS 端点
会话管理：维护用户认证会话状态，支持单点登出

1.3.2 OP 的元数据发现

OIDC 定义了 Discovery 机制，客户端可以通过 /.well-known/openid-configuration 端点获取 OP 的配置信息：

// 示例：OP 元数据端点响应
{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/userinfo",
  "jwks_uri": "https://auth.example.com/jwks",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code", "id_token", "token id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256"]
}

异步任务调试注意：在开发环境中，OP 的元数据端点可能因为网络延迟、DNS 解析或证书问题导致不可用。建议在异步任务启动前，先通过 curl 或 HTTP 客户端验证 /.well-known/openid-configuration 的可达性。

1.3.3 OP 的端点与异步任务的关系

端点	HTTP 方法	异步任务中的常见问题
`authorization_endpoint`	GET	重定向 URL 不匹配、scope 缺失 openid
`token_endpoint`	POST	授权码过期、client_secret 错误、超时
`userinfo_endpoint`	GET/POST	Access Token 无效、scope 不足
`jwks_uri`	GET	公钥缓存过期、密钥轮换未同步
`end_session_endpoint`	GET/POST	登出回调未实现、会话未清除

下图展示了 OP 的内部组件及其在 OIDC 流程中的交互关系：

1.4 本章小结

OIDC 是 OAuth 2.0 的身份认证扩展层，通过 ID Token 解决“谁在访问”的问题。
ID Token 是 JWT 格式，包含 iss、sub、aud、exp、nonce 等关键 Claims，验证时必须逐项检查。
OpenID Provider 是 OIDC 流程的核心，负责认证、Token 签发、密钥管理和端点暴露。
在异步任务调试中，OP 端点的可达性、ID Token 的签名验证、Claims 的字段匹配是三个最常出错的环节。