OIDC 登录流程

Code Bird Cloud 的登录流程基于 OIDC Authorization Code 流程，结合 Interaction API 实现灵活的用户认证体验。本文档详细说明 OIDC 授权码流程的各个步骤，以及 Interaction API 的登录接口。

OIDC 授权码流程

标准的 OIDC 授权码流程如下：

用户/客户端                  Code Bird Cloud                    登录页
    |                            |                               |
    |-- 1. 访问受保护资源 -------->|                               |
    |                            |                               |
    |<- 2. 302 重定向到           |                               |
    |   /oidc/authorize          |                               |
    |                            |                               |
    |-- 3. GET /oidc/authorize ->|                               |
    |                            |-- 4. 302 重定向到登录页 -------->|
    |                            |                               |
    |                            |   5. 用户在登录页输入凭据        |
    |                            |                               |
    |                            |<- 6. Interaction API 验证 -----|
    |                            |                               |
    |<- 7. 302 重定向到回调地址    |                               |
    |   携带 authorization_code  |                               |
    |                            |                               |
    |-- 8. POST /oidc/token ---->|                               |
    |   (用 code 换取令牌)        |                               |
    |                            |                               |
    |<- 9. 返回令牌 -------------|                               |
    |   access_token             |                               |
    |   refresh_token            |                               |
    |   id_token                 |                               |

流程说明

发起授权请求：客户端将用户重定向到 /oidc/authorize 端点，携带必要的 OIDC 参数
重定向到登录页：授权端点验证请求参数后，将用户重定向到登录页面
用户认证：用户在登录页面输入凭据（用户名/邮箱/手机号 + 密码，或使用验证码）
Interaction API 验证：登录页通过 Interaction API 提交用户凭据进行验证
授权码回调：验证成功后，系统将用户重定向到客户端注册的回调地址，URL 中携带授权码（authorization_code）
令牌交换：客户端使用授权码向 /oidc/token 端点换取令牌

授权请求参数

GET /oidc/authorize?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}&
  scope=openid profile email&
  state={random_state}

参数	必填	说明
`response_type`	是	固定值 `code`，表示授权码流程
`client_id`	是	应用的客户端 ID
`redirect_uri`	是	授权成功后的回调地址，需与应用配置中的回调地址一致
`scope`	是	请求的权限范围，`openid` 为必填项
`state`	推荐	随机字符串，用于防止 CSRF 攻击

令牌交换请求

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code={authorization_code}&
redirect_uri={redirect_uri}&
client_id={client_id}&
client_secret={client_secret}

Interaction API 登录

Interaction API 是登录页面与后端交互的核心接口，负责处理用户的认证请求。

登录接口

POST /api/interaction/sign-in
Content-Type: application/json

请求参数

json

{
  "identifier": "用户标识符",
  "password": "用户密码"
}

identifier 标识符类型

identifier 字段支持以下类型的值，系统会自动识别标识符类型：

标识符类型	示例	说明
用户名	`admin`	使用注册时设置的用户名
邮箱	`user@example.com`	使用绑定的邮箱地址
手机号	`13800138000`	使用绑定的手机号码

响应示例

登录成功后返回重定向信息，引导完成 OIDC 授权流程：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "redirect_to": "/oidc/authorize/callback?interaction_id=xxx"
  }
}

错误处理

HTTP 状态码	错误码	说明
400	`invalid_request`	请求参数不完整或格式错误
401	`invalid_credentials`	用户名或密码错误
403	`account_disabled`	用户账号已被禁用
429	`too_many_requests`	登录尝试次数过多，请稍后再试

管理端登录

管理端（Admin Console）使用独立的登录流程，直接通过管理端 API 进行认证：

POST /api/v1/admin/sign-in
Content-Type: application/json

{
  "username": "admin",
  "password": "admin_password"
}

管理端登录成功后直接返回 HS256 签名的 JWT 令牌，无需经过 OIDC 授权码流程。

OIDC 登录流程 ​

OIDC 授权码流程 ​

流程说明 ​

授权请求参数 ​

令牌交换请求 ​

Interaction API 登录 ​

登录接口 ​

请求参数 ​

identifier 标识符类型 ​

响应示例 ​

错误处理 ​

管理端登录 ​

相关文档 ​