鉴权流程

baozi 使用 OIDC（OpenID Connect） 做用户身份认证。第三方集成使用 OAuth2 M2M（client_credentials），详见 third-party.md。

本文档只讲人类用户登录。

1. 登录入口

`GET /login`

打开 baozi 登录页面。前端会自动触发 OIDC 跳转。

`GET /auth/sign-in`

后端触发 OIDC 跳转：

curl -i https://baozi.ohoooho.com/auth/sign-in
# HTTP/2 302
# Location: https://login.ohoooho.com/oidc/auth?...

浏览器收到 302 后跳转到 baozi OIDC 登录页，用户输账号密码。

2. OIDC 回调

`GET /auth/callback`

用户在 OIDC 完成登录后，OIDC 跳转回这个 URL（含 code 查询参数）。

后端流程：

用 code 换 OIDC access_token + id_token
拿 userinfo
在 baozi 后端自动建号（首次登录的用户）
签发 baozi 自己的 baozi_token cookie
302 跳到 baozi 首页

3. 查询当前用户

`GET /auth/userinfo`

返回当前 baozi 用户的 userinfo（与 /api/me 类似，但兼容老接口）。

响应 200：

{
  "success": true,
  "data": {
    "id": 42,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "tier": "pro"
  }
}

错误码：

HTTP	code	含义
401	`NOT_AUTHENTICATED`	未登录或 token 失效

4. 登出

`GET /auth/logout`

清 baozi session cookie，302 跳到 OIDC 登出页。

`GET /auth/logout-callback`

OIDC 登出后回调 URL，清完状态后跳 baozi 登录页 ?signed_out=1。

5. 自动登录 new-api（内部机制）

`GET /auth/login-newapi`

这是 baozi 内部跳转，不是用户直接调用的。后端用 baozi 用户的派生密码登录 new-api，设 session cookie 到 baozi.ohoooho.com。

浏览器无需手动调，baozi 内部走 OIDC callback 时已经处理。

6. baozi_token 是什么

属性	值
格式	JWT (HS256)
字段	`sub` (用户 ID), `iat`, `exp`
默认有效期	7 天
存放	HTTP-only Cookie `baozi_token`（浏览器自动管理）

服务端调用：

curl https://baozi.ohoooho.com/api/me \
  -H "Authorization: Bearer <baozi_token>"

7. 完整登录时序图

浏览器                baozi 前端              baozi 后端            OIDC Provider
  |                      |                        |                       |
  | 打开 baozi 首页       |                        |                       |
  |--------------------->|                        |                       |
  |                      | GET /login             |                       |
  |                      |----------------------->|                       |
  |                      |                        | GET /auth/sign-in      |
  |                      |                        |---------------------->|
  |                      |                        |  302 to /oidc/auth    |
  |<----- 302 to OIDC -------------------------------------------->|
  |                      |                        |                       |
  | 用户输账号密码         |                        |                       |
  |----------------------------------------------------------->|
  | OIDC 验证后 302 回 baozi /auth/callback?code=xxx              |
  |<-----------------------------------------------------------|
  |                      | GET /auth/callback?code=xxx                |
  |                      |----------------------->|                       |
  |                      |                        | 用 code 换 token       |
  |                      |                        | 拿 userinfo           |
  |                      |                        | 自动建号（首次）       |
  |                      |                        | 签 baozi_token cookie |
  |                      | 302 + Set-Cookie       |                       |
  |<---------------------| baozi_token=xxx        |                       |
  |                      |                        |                       |
  | 之后所有请求自动带 baozi_token cookie          |                       |
  |--------------------->|----------------------->|                       |

8. 常见问题

Q: 登录失败，提示 Invalid state？ A: OIDC state 校验失败，可能是 CSRF 攻击或 session 过期。重新打开登录页即可。

Q: 已登录但调用 /api/me 返 401？ A: baozi_token cookie 过期（默认 7 天），重新走一次 OIDC 登录即可续期。

Q: 第三方能否用 OIDC 流程？ A: 不能。第三方必须用 OAuth2 M2M（client_credentials），详见 third-party.md。

联系 baozi

文档不全？发邮件到 support@ohoooho.com 或在飞书群里 @ 闲云。