注册与登录
Code Bird Cloud 基于 OIDC (OpenID Connect) / OAuth 2.1 标准协议构建认证体系，为 Web 应用、单页应用、移动端及后端服务提供安全的身份认证能力。本文档介绍系统支持的认证方式、注册流程、登录流程以及 Token 体系。
支持的认证方式
| 认证方式 | 说明 | 要求 |
|---|---|---|
| 用户名 + 密码 | 传统账号密码登录 | 无额外要求 |
| 邮箱 + 验证码 | 通过邮箱接收一次性验证码登录 | 需配置邮件连接器 |
| 手机号 + 验证码 | 通过手机号接收一次性验证码登录 | 需配置短信连接器 |
| M2M (Client Credentials) | 后端服务间的机器对机器认证 | 需创建 M2M 类型应用 |
邮箱验证码和短信验证码登录需要在系统中配置对应的邮箱连接器 (Email Connector) 或短信连接器 (SMS Connector) 后方可使用。具体配置方法请参阅连接器文档。
注册流程
用户注册流程取决于管理员在登录体验中配置的注册设置。
注册标识符
注册时用户需要提供的身份信息由注册标识符决定，可以同时要求多种标识符：
- 用户名：用户设置一个唯一的用户名
- 邮箱：用户提供邮箱地址
- 手机号：用户提供手机号码
注册选项
| 选项 | 说明 |
|---|---|
| 需要密码 | 注册时是否必须设置密码。密码需符合系统配置的密码策略 |
| 需要验证 | 注册时是否需要验证邮箱或手机号。启用后系统会发送验证码，用户需输入正确验证码才能完成注册 |
注册流程步骤
- 用户在登录页点击 "注册" 链接
- 系统根据注册配置展示注册表单（包含要求的标识符字段）
- 用户填写必要信息（用户名、邮箱、手机号、密码等）
- 如果启用了验证，系统通过连接器发送验证码，用户输入验证码
- 验证通过后用户账户创建成功
- 系统自动完成 OIDC 授权流程，将用户重定向回应用
相关 API
POST /api/interaction/register登录流程
用户登录时，系统会根据登录体验配置中的登录方式设置，展示可用的登录选项。
密码登录
- 用户输入标识符（用户名、邮箱或手机号）和密码
- 系统验证凭据
- 验证成功后完成 OIDC 授权流程
验证码登录
- 用户输入邮箱或手机号
- 系统通过对应连接器发送验证码
- 用户输入验证码
- 验证成功后完成 OIDC 授权流程
验证码登录需要预先配置并启用对应的邮件或短信连接器。
相关 API
POST /api/interaction/sign-in
POST /api/interaction/verification-code
POST /api/interaction/verify-codeToken 体系
系统采用 JWT (JSON Web Token) 进行身份认证，根据使用场景区分签名算法和令牌类型。
签名算法
| 场景 | 算法 | 说明 |
|---|---|---|
| OIDC 令牌 | ES256 (ECDSA P-256) | 面向终端用户和第三方应用的标准 OIDC 令牌 |
| Admin 管理端令牌 | HS256 (HMAC-SHA256) | 后台管理控制台 (Admin Console) 的认证令牌 |
| M2M 令牌 | ES256 | JWT 中包含 token_type: "m2m" 声明，标识机器对机器认证 |
令牌类型与有效期
| 令牌类型 | 用途 | 默认有效期 |
|---|---|---|
| Access Token | JWT 格式，作为访问受保护资源的凭证，包含在 API 请求的 Authorization 头中 | 1 小时 |
| Refresh Token | 用于在 Access Token 过期后获取新的令牌对，避免用户重复登录 | 14 天 |
| ID Token | 符合 OIDC 规范的身份令牌，包含用户基本信息（如 sub、email、name 等 claims） | 1 小时 |
支持的 OAuth 2.1 流程
Code Bird Cloud 支持以下标准 OAuth 2.1 授权流程：
| 流程 | 适用场景 | 说明 |
|---|---|---|
| Authorization Code Flow | 有后端的 Web 应用 | 标准授权码流程，通过后端交换令牌，安全性最高 |
| Authorization Code Flow + PKCE | 单页应用 (SPA)、移动端 | 在授权码流程基础上增加 PKCE 扩展，防止授权码拦截攻击 |
| Client Credentials | 后端服务 (M2M) | 服务间直接使用 client_id 和 client_secret 获取访问令牌，无需用户参与 |
相关文档
- OIDC 登录流程详解 -- OIDC 授权码流程与 Interaction API 登录机制
- 忘记密码 -- 密码重置流程
- 登出 -- 用户退出登录
- 登录体验配置 -- 自定义登录和注册流程
- 连接器 -- 配置邮件、短信和社交登录
- 应用集成指南 -- 如何将应用接入 Code Bird Cloud 认证
- M2M 认证 -- 机器对机器认证的配置与使用
- 传统 Web 应用集成 -- 标准 OIDC 端点与授权码流程说明