Code Bird Cloud

Appearance

OIDC / OAuth 2.1 基础 ​

概述 ​

Code Bird Cloud 基于 OpenID Connect（OIDC）和 OAuth 2.1 标准构建身份认证与授权体系。本文档介绍这些标准的核心概念，帮助你理解 Code Bird Cloud 的工作原理以及如何与之集成。

什么是 OAuth 2.1 ​

OAuth 2.1 是 OAuth 2.0 的简化和安全增强版本。OAuth 协议的核心目标是允许第三方应用在用户授权的前提下，安全地访问用户在某个服务上的资源，而无需用户直接提供自己的密码。

从 OAuth 2.0 到 2.1 ​

OAuth 2.0 自 2012 年发布以来（RFC 6749），社区在实践中积累了大量安全经验，并发布了多个补充规范。OAuth 2.1 将这些最佳实践整合为一个统一的规范，主要变化包括：

  • 强制 PKCE：Authorization Code 授权流程必须使用 PKCE（Proof Key for Code Exchange）扩展，防止授权码拦截攻击
  • 移除 Implicit 授权类型：不再支持直接在 URL 中返回 Access Token 的方式，因其存在安全风险
  • 移除 Resource Owner Password Credentials 授权类型：不再推荐直接使用用户名密码换取令牌
  • Refresh Token 限制：Refresh Token 必须是一次性使用的（sender-constrained）或限定范围的

什么是 OpenID Connect ​

OpenID Connect（OIDC）是建立在 OAuth 2.0/2.1 之上的身份认证层。OAuth 本身只解决"授权"问题（允许访问哪些资源），而 OIDC 在此基础上增加了"认证"能力（确认用户是谁）。

OIDC 的核心扩展：

  • 引入 ID Token：一种包含用户身份信息的 JWT 令牌
  • 定义 UserInfo 端点：获取用户详细信息的标准 API
  • 标准化 Discovery 端点：通过 /.well-known/openid-configuration 自动发现服务配置
  • 定义 标准 Claims：如 sub（用户标识）、name、email 等用户信息字段

简单来说：OAuth 2.1 负责授权，OIDC 负责认证。

核心概念 ​

角色实体 ​

在 OAuth/OIDC 协议中，有四个核心角色：

角色说明Code Bird Cloud 中的对应
Authorization Server / Identity Provider负责认证用户身份并签发令牌的服务Code Bird Cloud 本身
Resource Server托管受保护资源的服务，验证 Access Token 后提供资源你的业务 API 服务
Client（客户端/应用）代表用户请求访问资源的应用程序Code Bird Cloud 中注册的应用（Application）
Resource Owner（资源拥有者）拥有受保护资源的实体，通常是终端用户Code Bird Cloud 中的用户（User）

Scopes 和 Claims ​

Scope（作用域）定义了客户端请求的访问范围。常见的 OIDC Scope 包括：

Scope说明
openid必须包含，表示这是一个 OIDC 请求
profile请求用户基本信息（姓名、头像等）
email请求用户邮箱信息
offline_access请求 Refresh Token，用于令牌续期

Claim（声明）是令牌中包含的键值对信息。ID Token 中的标准 Claims 包括：

Claim说明
sub用户的唯一标识（Subject）
iss令牌签发方的标识（Issuer）
aud令牌的预期接收方（Audience）
exp令牌过期时间（Expiration）
iat令牌签发时间（Issued At）
name用户的显示名称
email用户的邮箱地址

令牌类型 ​

OIDC/OAuth 体系中有三种核心令牌：

令牌类型用途格式有效期
Access Token访问受保护资源的凭证JWT（可选 opaque）短期（通常数分钟到数小时）
Refresh Token获取新的 Access Token不透明字符串长期（数天到数月）
ID Token携带用户身份信息的凭证JWT短期

Access Token 由客户端在请求受保护资源时携带，资源服务器验证其合法性后提供资源。

Refresh Token 用于在 Access Token 过期后获取新令牌，避免用户频繁重新登录。

ID Token 是 OIDC 特有的令牌类型，包含用户身份信息（Claims），客户端可直接解析获取用户基本信息。

授权类型（Grant Types） ​

Code Bird Cloud 支持以下授权类型：

Authorization Code（授权码模式） ​

最常用的授权流程，适用于有服务端的 Web 应用和原生应用：

1. 用户在客户端点击登录
2. 客户端将用户重定向到 Code Bird Cloud 授权端点
3. 用户在 Code Bird Cloud 完成认证（输入用户名密码等）
4. Code Bird Cloud 将用户重定向回客户端，URL 中携带授权码（code）
5. 客户端用授权码向 Code Bird Cloud 换取令牌（Access Token + ID Token）

Client Credentials（客户端凭证模式） ​

适用于 Machine-to-Machine（M2M）通信，无需用户参与：

1. 客户端使用自己的 client_id 和 client_secret 向 Code Bird Cloud 请求令牌
2. Code Bird Cloud 验证客户端身份后签发 Access Token

此模式下没有用户上下文，令牌代表的是应用本身的身份。

PKCE 扩展 ​

PKCE（Proof Key for Code Exchange，发音 "pixy"）是 Authorization Code 流程的安全扩展，在 OAuth 2.1 中被强制要求。

PKCE 通过在授权请求时附加一个动态生成的 code_verifier 和 code_challenge，确保只有发起授权请求的客户端才能使用返回的授权码换取令牌，防止授权码在传输过程中被拦截利用。

1. 客户端生成随机字符串 code_verifier
2. 客户端计算 code_challenge = SHA256(code_verifier)
3. 授权请求中携带 code_challenge
4. 令牌请求中携带 code_verifier
5. 服务端验证 SHA256(code_verifier) == code_challenge

JWKS 和令牌签名 ​

JWKS（JSON Web Key Set）是一种发布令牌签名公钥的标准格式。Code Bird Cloud 通过 JWKS 端点发布当前所有有效签名密钥的公钥：

GET /.well-known/jwks.json

资源服务器和客户端通过此端点获取公钥，用于验证 JWT 令牌的签名。每个密钥通过 kid（Key ID）标识，令牌头部中的 kid 字段指示应使用哪个公钥进行验证。

Code Bird Cloud 与 OIDC 概念映射 ​

以下表格展示 Code Bird Cloud 的功能实体与 OIDC 标准概念之间的对应关系：

Code Bird Cloud 概念OIDC/OAuth 概念说明
Code Bird Cloud 平台Authorization Server / Identity Provider负责用户认证和令牌签发
应用（Application）Client注册在平台上的客户端应用
用户（User）Resource Owner / End-User系统中的终端用户
API 资源（API Resource）Resource Server受保护的 API 服务
权限（Scope）ScopeAPI 资源下的具体访问权限
签名密钥（Signing Keys）JWKS用于令牌签名和验证的密钥
Access TokenAccess Token访问资源的短期凭证
Refresh TokenRefresh Token用于令牌续期的长期凭证
ID TokenID Token携带用户身份信息的令牌

发现端点 ​

Code Bird Cloud 遵循 OIDC Discovery 规范，通过以下端点公开服务配置信息：

GET /.well-known/openid-configuration

该端点返回的信息包括：

  • 授权端点（Authorization Endpoint）URL
  • 令牌端点（Token Endpoint）URL
  • UserInfo 端点 URL
  • JWKS 端点 URL
  • 支持的 Scope 列表
  • 支持的 Response Type 列表
  • 支持的 Grant Type 列表

客户端可通过此端点自动发现和配置与 Code Bird Cloud 的集成参数。

相关文档 ​

Released under the MIT License.

Copyright 2024-present Code Bird Team