630 lines
32 KiB
Markdown
630 lines
32 KiB
Markdown
# 任意项目接入 RainID（OIDC）实操指南
|
||
|
||
> 视角：**实现 / 落地**。不是协议科普，而是"从 0 到 1 动手做完 + 线上能跑"的操作手册。
|
||
> 素材来源：RainWeb × RainID 真实接入（`lib/rainid.js`、`routes/oidc.js`、`routes/auth.js`、`routes/settings.js`、前端 `Login.jsx`/`Register.jsx`），已上线并排过障。
|
||
> 技术栈：Node.js / Express / openid-client v6（函数式 API）。**每个模式旁标注"其他栈同理"**。
|
||
|
||
---
|
||
|
||
## 0. 全景图：一个站点接 RainID 需要什么
|
||
|
||
```
|
||
用户 ──→ 你的前端登录页
|
||
├─ 方式 A（ROPC）：输 RainID 账号密码 → 你的后端 POST rainid /oauth/token (password)
|
||
│ → 按 sub 建/找影子账号 → 发你的本地 JWT
|
||
└─ 方式 B（授权码+PKCE）：点"使用 RainID 登录" → 你的后端 302 到 RainID
|
||
→ RainID 登录/同意 → 回跳你的 callback
|
||
→ 后端换 token + userinfo → 影子账号 → 一次性 ticket
|
||
→ 前端拿 ticket 换本地 JWT（长 token 不进 URL）
|
||
登出：你的后端 302 到 RainID end_session → RainID 确认销毁 IdP 会话 → 303 回跳你的页面
|
||
```
|
||
|
||
**核心心智模型**：
|
||
1. **RainID 只认标准 OIDC/OAuth2**，你的项目只需要一个 `discovery_url`。
|
||
2. **身份归属 RainID，角色归属你**——影子账号按 `sub` 绑定，admin 等角色在你的本地库维护。
|
||
3. **access_token 是 opaque，id_token 只有 `sub`**——想要 email/name 必须调 userinfo 端点。
|
||
4. **你的会话是 JWT/session（本地），RainID 的会话是它的签名 cookie，两者不共享**。登出联动靠 end_session。
|
||
|
||
---
|
||
|
||
## 1. Step-by-step 接入步骤
|
||
|
||
### Step 1：RainID Admin 登记 client（前置，5 分钟）
|
||
|
||
RainID Admin → 应用管理 → 新增应用，填：
|
||
|
||
| 字段 | 值 | 说明 |
|
||
|---|---|---|
|
||
| `name` | 你的站点名（如 RainWeb） | 展示名 |
|
||
| `confidential` | ✅ 机密 client | 拿到 `client_secret`；**明文只在创建/轮换时返回一次，立即存好** |
|
||
| `redirect_uris` | `https://你的域名/api/auth/oidc/callback` | 授权码回跳白名单，**每行一个，未登记直接拒绝** |
|
||
| `grant_types` | `authorization_code` + `refresh_token`（+ `password` 若要 ROPC） | 按协议选 |
|
||
| `require_pkce` | ✅ 强制（默认） | 防授权码注入 |
|
||
| `scope` | `openid profile email offline_access` | 白名单必须覆盖你请求的 scope，否则 `invalid_scope` |
|
||
| `post_logout_redirect_uris` | `https://你的域名/login.html` | **登出回跳白名单，忘了登记 end_session 就 400** |
|
||
|
||
创建后**立即生效**（client 热更新，无需重启 RainID）。
|
||
|
||
> 踩过：登出配置好了但 `post_logout_redirect_uri` 没登记 → RainID 返回 400，用户登出卡死。
|
||
|
||
### Step 2：装依赖
|
||
|
||
```bash
|
||
npm install openid-client # Node 版；浏览器端等价物见下
|
||
npm install jose # 仅当你绕过 SDK 手动验签时（一般不需要，SDK 全包）
|
||
```
|
||
|
||
- **Node**：`openid-client` v6（函数式 API，本项目用的就是它）。
|
||
- **Python**：`authlib`；**Go**：`coreos/go-oidc`；**Java**：`spring-security-oauth2-client`。都是标准 OIDC，照着下面模式映射即可。
|
||
- **浏览器纯前端（SPA）**：不要 `oidc-client-ts` 全放前端！**SPA 必须 BFF**（后端代理），禁止前端持有 refresh_token。
|
||
|
||
### Step 3：配置项（先想清楚再写代码）
|
||
|
||
分两档（详见第 3 章）：
|
||
|
||
- **非敏感（可后台热改、可读）**：`rainid_enabled`、`rainid_client_id`、`rainid_discovery_url`、`rainid_register_redirect`。
|
||
- **机密（只写不读）**：`rainid_client_secret`——**优先 `.env.json`（gitignored）**，回退后台设置（可写、GET 不返回）。
|
||
|
||
### Step 4：后端三个路由（授权码流）/ 一个路由（ROPC）
|
||
|
||
统一挂载（RainWeb 挂 `/api/auth/oidc`）：
|
||
|
||
| 方法 | 路径 | 作用 |
|
||
|---|---|---|
|
||
| GET | `/login` | 生成 PKCE+state，302 到 RainID authorize |
|
||
| GET | `/callback` | 验 state → 换 token → userinfo → 影子账号 → 发一次性 ticket → 302 回前端 |
|
||
| POST | `/exchange` | 前端用 ticket 换本地 JWT（30s 一次性） |
|
||
| GET | `/logout` | 302 到 RainID end_session（登出联动） |
|
||
|
||
ROPC 不需要新路由——**复用你的现有登录 POST**，在处理器里加一个分支转发 RainID。
|
||
|
||
完整代码模式见第 2 章。
|
||
|
||
### Step 5：影子账号（数据层）
|
||
|
||
用户表加一列 `rainid_user_id`（唯一索引），按 `sub` 查/建。见 2.5。
|
||
|
||
### Step 6：前端入口（登录页/注册页）
|
||
|
||
- 登录页：`rainid_enabled=1` 时显示「使用 RainID 登录」按钮 → `window.location.href='/api/auth/oidc/login'`。
|
||
- 回跳收尾：URL 带 `?oidc_ticket=xxx` → POST `/exchange` 换 token → 存 localStorage → 通知登录态变更 → 跳首页；带 `?oidc_error=xxx` → 映射错误文案。
|
||
- 注册页：`rainid_register_redirect=1` 时整页跳 `https://rainid.rainnya.asia/register`，本地表单不渲染。
|
||
|
||
### Step 7：登出联动
|
||
|
||
你的登出按钮：`rainid_enabled=1` 时跳 `/api/auth/oidc/logout`（后端 302 到 RainID end_session），否则直接清本地会话。
|
||
|
||
### Step 8：验收（对照 RainID 文档 §15 checklist）
|
||
|
||
完整走一遍：注册 → RainID 登录 → 同意 → 回跳 → 影子账号 → 刷新页面保持登录 → 登出回跳。**再测一遍 2FA 用户、密码错误、未登记回调**三条错误路径。
|
||
|
||
---
|
||
|
||
## 2. 关键代码模式（可直接抄）
|
||
|
||
### 2.1 discovery 缓存（⚠️ v6 第一参数必须是 `new URL()`）
|
||
|
||
```js
|
||
const openidClient = require('openid-client'); // v6 函数式 API
|
||
const DISCOVERY_DEFAULT = 'https://rainid.rainnya.asia/oauth';
|
||
|
||
// 模块级缓存：discovery 是一次网络请求 + JWKS 拉取，不能每次登录都打
|
||
let configCache = null;
|
||
async function getOidcConfig() {
|
||
if (configCache) return configCache;
|
||
// ⚠️⚠️ v6 的 discovery() 第一个参数必须是 URL 实例！
|
||
// 传字符串会抛 "server must be an instance of URL" → 所有登录请求 502（线上踩过的根因，见 §5.1）
|
||
configCache = await openidClient.discovery(
|
||
new URL(discoveryUrl), // ← 必须是 new URL()，不是字符串
|
||
clientId,
|
||
clientSecret
|
||
);
|
||
return configCache;
|
||
}
|
||
```
|
||
|
||
要点：
|
||
- **缓存副作用：后台改了 discovery_url / client 配置，需重启进程生效**（RainWeb 注释里明确写了这条）。
|
||
- JWKS 多 key 轮换 SDK 自动处理，你不需要管。
|
||
- 其他栈同理：authlib 的 `discovery(url)`、go-oidc 的 `NewProvider` 接受 URL 字符串，但 Node 的 v6 就是严格。
|
||
|
||
### 2.2 PKCE + state 无 session 框架怎么存：内存 Map + TTL，取用即删
|
||
|
||
你的框架若没有 session（RainWeb 是无状态 JWT），PKCE 的 `code_verifier` 和 `state` 不能丢。**内存 Map + 定时清理**即可（单进程够用；多进程部署换 Redis，TTL 语义一样）：
|
||
|
||
```js
|
||
const OIDC_STATE_TTL = 10 * 60 * 1000; // 发起登录 → 回调
|
||
const oidcStates = new Map(); // state -> { verifier, createdAt }
|
||
|
||
// 每分钟清扫过期项（防内存泄漏）
|
||
setInterval(() => {
|
||
const now = Date.now();
|
||
for (const [k, v] of oidcStates) if (now - v.createdAt > OIDC_STATE_TTL) oidcStates.delete(k);
|
||
}, 60000);
|
||
|
||
// ① 发起登录
|
||
router.get('/login', async (req, res) => {
|
||
const config = await getOidcConfig();
|
||
const codeVerifier = openidClient.randomPKCECodeVerifier();
|
||
const codeChallenge = await openidClient.calculatePKCECodeChallenge(codeVerifier);
|
||
const state = openidClient.randomState();
|
||
oidcStates.set(state, { verifier: codeVerifier, createdAt: Date.now() });
|
||
const url = openidClient.buildAuthorizationUrl(config, {
|
||
redirect_uri: siteBase(req) + '/api/auth/oidc/callback',
|
||
scope: 'openid profile email', // 要 refresh 就加 offline_access（需用户同意）
|
||
code_challenge: codeChallenge,
|
||
code_challenge_method: 'S256',
|
||
state,
|
||
});
|
||
res.redirect(url.href);
|
||
});
|
||
```
|
||
|
||
要点：
|
||
- **`state` 一次性，回调里取用即删**——防重放。
|
||
- **不要手写 PKCE**，用 SDK 标准函数（`randomPKCECodeVerifier` / `calculatePKCECodeChallenge`）。
|
||
|
||
### 2.3 回调换 token + 验签 + userinfo（id_token 只含 sub！）
|
||
|
||
```js
|
||
router.get('/callback', async (req, res) => {
|
||
const state = req.query.state;
|
||
const stored = state && oidcStates.get(state);
|
||
if (!stored) return res.status(400).send('登录状态已失效，请重新使用 RainID 登录');
|
||
oidcStates.delete(state); // 一次性
|
||
|
||
const config = await getOidcConfig();
|
||
const base = siteBase(req);
|
||
const currentUrl = new URL(req.originalUrl, base); // 回调的完整 URL（含 query）
|
||
try {
|
||
// authorizationCodeGrant 自动完成：验 state + PKCE + 换 token
|
||
// + 自动验 id_token 签名(RS256/JWKS) + iss + aud + exp
|
||
const tokens = await openidClient.authorizationCodeGrant(config, currentUrl, {
|
||
pkceCodeVerifier: stored.verifier,
|
||
expectedState: state,
|
||
idTokenExpected: true,
|
||
});
|
||
|
||
const claims = tokens.claims(); // id_token 解码
|
||
const sub = claims && claims.sub; // ⚠️ 只有 sub！没有 email/name（见 §5.3）
|
||
if (!sub) throw new Error('id_token 缺少 sub');
|
||
|
||
// ⚠️ 必须调 userinfo 拿 email/name/email_verified
|
||
// fetchUserInfo 第三个参数传 sub = 校验 userinfo 的 sub 与 id_token 一致（防注入）
|
||
const userinfo = await openidClient.fetchUserInfo(config, tokens.access_token, sub);
|
||
|
||
const user = findOrCreateRainidUser(sub, userinfo); // 见 2.5
|
||
const token = jwt.sign({ id: user.id, username: user.username, role: user.role },
|
||
SECRET, { expiresIn: '7d' }); // ← 你的本地会话
|
||
|
||
const ticket = crypto.randomBytes(16).toString('hex');
|
||
oidcTickets.set(ticket, { jwt: token, username: user.username, role: user.role,
|
||
email: user.email, email_verified: user.email_verified,
|
||
createdAt: Date.now() });
|
||
res.redirect(frontLoginUrl(req, '?oidc_ticket=' + encodeURIComponent(ticket)));
|
||
} catch (err) {
|
||
// error 参数：access_denied / consent_required / invalid_grant 等 → 回前端带错误码
|
||
const code = err && err.error;
|
||
res.redirect(frontLoginUrl(req, '?oidc_error=' + encodeURIComponent(code || 'server_error')));
|
||
}
|
||
});
|
||
```
|
||
|
||
要点：
|
||
- `sub` 是**稳定、永不变更**的绑定键，跨应用唯一。
|
||
- 错误码映射表见 §6（前端把 `oidc_error` 码翻译成用户文案）。
|
||
|
||
### 2.4 一次性 ticket 换本地 JWT（避免长 token 进 URL）
|
||
|
||
JWT 动辄几百字符，塞进 302 URL 会进浏览器历史/反代日志。**用一个 30 秒一次性的随机 ticket 过渡**：
|
||
|
||
```js
|
||
const OIDC_TICKET_TTL = 30 * 1000;
|
||
const oidcTickets = new Map(); // ticket -> { jwt, ... }
|
||
|
||
router.post('/exchange', (req, res) => {
|
||
const ticket = req.body && req.body.ticket;
|
||
if (!ticket) return res.status(400).json({ error: '缺少 ticket' });
|
||
const rec = oidcTickets.get(ticket);
|
||
if (!rec) return res.status(401).json({ error: '登录已过期，请重新使用 RainID 登录' });
|
||
oidcTickets.delete(ticket); // 一次性
|
||
res.json({ token: rec.jwt, username: rec.username, role: rec.role,
|
||
email: rec.email, email_verified: rec.email_verified });
|
||
});
|
||
```
|
||
|
||
前端收尾（`Login.jsx` 实测模式）：
|
||
|
||
```js
|
||
useEffect(() => {
|
||
const params = new URLSearchParams(window.location.search);
|
||
const ticket = params.get('oidc_ticket');
|
||
const oidcError = params.get('oidc_error');
|
||
if (ticket) { handleOidcTicket(ticket); return; } // 先兑换，30s 有效期
|
||
if (oidcError) { setError(OIDC_ERROR_TEXT[oidcError] || 'RainID 登录失败'); clearOidcParams(); return; }
|
||
...
|
||
}, []);
|
||
|
||
const handleOidcTicket = async (ticket) => {
|
||
const data = await authApi.oidcExchange(ticket);
|
||
setToken(data.token);
|
||
notifyAuthChange();
|
||
clearOidcParams(); // history.replaceState 清掉 URL 上的 ticket，避免刷新重复兑换
|
||
navigate(from || '/');
|
||
};
|
||
```
|
||
|
||
### 2.5 影子账号创建/绑定逻辑（含 email_verified 闸门、并发兜底、首用户 admin）
|
||
|
||
```js
|
||
// ① 按 sub 查 → ② email_verified 且本地同邮箱未绑定 → 绑定 → ③ 否则创建
|
||
function findOrCreateRainidUser(sub, profile) {
|
||
if (!sub) throw new Error('RainID userinfo 缺少 sub');
|
||
const email = String(profile.email || '').trim().toLowerCase();
|
||
|
||
// 1) 已绑定：sub 命中直接返回
|
||
let user = db.get('SELECT * FROM users WHERE rainid_user_id = ?', [sub]);
|
||
if (user) return user;
|
||
|
||
// 2) 自动绑定：仅当 RainID 已验证该邮箱（email_verified=true）才允许绑
|
||
// 防撞绑：未验证邮箱的 userinfo 绝不能自动绑到本地已有账号
|
||
if (email && profile.email_verified) {
|
||
const local = db.get('SELECT * FROM users WHERE email = ?', [email]);
|
||
if (local && !local.rainid_user_id) {
|
||
// 条件 UPDATE：WHERE 再带 rainid_user_id=''，并发下第二个人写不进来
|
||
db.run('UPDATE users SET rainid_user_id = ? WHERE id = ? AND rainid_user_id = ?', [sub, local.id, '']);
|
||
const updated = db.get('SELECT * FROM users WHERE id = ?', [local.id]);
|
||
if (updated && updated.rainid_user_id === sub) return updated;
|
||
}
|
||
}
|
||
|
||
// 3) 创建影子账号
|
||
let username = profile.preferred_username || ('rainid_' + String(sub).slice(0, 8));
|
||
if (db.get('SELECT id FROM users WHERE username = ?', [username])) {
|
||
username = username + '_' + String(sub).slice(0, 4); // 冲突加后缀
|
||
}
|
||
// 影子账号给随机不可登录密码 —— 禁止本地密码登入（见 §4）
|
||
const randomHash = bcrypt.hashSync(crypto.randomBytes(24).toString('hex'), 10);
|
||
// 首用户 admin：全站无 admin 时第一个绑定的用户自动成为 admin（RainID 不管角色）
|
||
const adminCount = db.get("SELECT COUNT(*) AS c FROM users WHERE role = 'admin'");
|
||
const role = adminCount && adminCount.c > 0 ? 'user' : 'admin';
|
||
try {
|
||
const id = db.run(
|
||
'INSERT INTO users (username, password, email, email_verified, role, avatar, rainid_user_id) VALUES (?, ?, ?, 1, ?, ?, ?)',
|
||
[username, randomHash, email, role, profile.picture || '', sub]
|
||
);
|
||
return db.get('SELECT * FROM users WHERE id = ?', [id]);
|
||
} catch (e) {
|
||
// 并发兜底：唯一索引冲突 → 重查按 sub 返回（谁先建都行）
|
||
const dup = db.get('SELECT * FROM users WHERE rainid_user_id = ?', [sub]);
|
||
if (dup) return dup;
|
||
throw e;
|
||
}
|
||
}
|
||
```
|
||
|
||
配套 DDL（唯一索引是并发兜底的地基，**必须建**）：
|
||
|
||
```sql
|
||
ALTER TABLE users ADD COLUMN rainid_user_id TEXT DEFAULT ''; -- 幂等补列
|
||
CREATE UNIQUE INDEX IF NOT EXISTS idx_users_rainid
|
||
ON users(rainid_user_id) WHERE rainid_user_id <> ''; -- 部分唯一索引
|
||
```
|
||
|
||
要点：
|
||
- **email_verified 是自动绑定的闸门**：只有 RainID 验证过的邮箱才能绑本地号，防有人用他人邮箱注册 RainID 来接管本地账号。
|
||
- 绑定用**条件 UPDATE**（`WHERE rainid_user_id=''`）而非先查后改，并发安全。
|
||
|
||
### 2.6 ROPC 密码登录（`grant_type=password` + 2FA 拒绝文案）
|
||
|
||
```js
|
||
// 复用一个 getOidcConfig()。genericGrantRequest 自动带 client 认证（HTTP Basic）
|
||
async function rainidRopcLogin(username, password) {
|
||
const s = getOidcSettings();
|
||
if (!s.enabled) return { ok: false, status: 400, error: 'RainID 登录未启用' };
|
||
|
||
let config;
|
||
try { config = await getOidcConfig(); }
|
||
catch (e) {
|
||
if (e && e.code === 'RAINID_NOT_CONFIGURED')
|
||
return { ok: false, status: 500, error: 'RainID 客户端未配置' };
|
||
return { ok: false, status: 502, error: 'RainID 服务配置错误：Discovery 失败（检查端点是否为 https）' };
|
||
}
|
||
|
||
try {
|
||
const tokens = await openidClient.genericGrantRequest(config, 'password', {
|
||
username, password, scope: 'openid profile email',
|
||
});
|
||
// id_token 验签 SDK 负责；拿 sub 做 userinfo 的 subject 校验
|
||
let expectedSub = openidClient.skipSubjectCheck;
|
||
try {
|
||
const claims = tokens.claims();
|
||
if (claims && claims.sub) expectedSub = claims.sub;
|
||
} catch { /* id_token 解析失败不阻断，userinfo 为准 */ }
|
||
const userinfo = await openidClient.fetchUserInfo(config, tokens.access_token, expectedSub);
|
||
const user = findOrCreateRainidUser(userinfo.sub, userinfo);
|
||
return { ok: true, user };
|
||
} catch (err) {
|
||
return mapOidcError(err); // 见下
|
||
}
|
||
}
|
||
|
||
// RainID OAuth 错误 → HTTP 状态 + 文案（防枚举！不区分具体原因）
|
||
function mapOidcError(err) {
|
||
const code = err && err.error;
|
||
const desc = (err && err.error_description) || '';
|
||
switch (code) {
|
||
case 'invalid_grant':
|
||
// ⚠️ 2FA 用户 ROPC 被拒 → 固定文案引导走 RainID 登录页
|
||
return { ok: false, status: 401, error: desc.includes('二次验证')
|
||
? '该账号已开启二次验证，请使用 RainID 登录'
|
||
: '用户名/邮箱或密码错误' };
|
||
case 'rate_limited':
|
||
return { ok: false, status: 429, error: '尝试过于频繁，请稍后再试' };
|
||
case 'invalid_client':
|
||
case 'invalid_scope':
|
||
case 'invalid_request':
|
||
return { ok: false, status: 500, error: 'RainID 配置错误，请联系管理员' };
|
||
default:
|
||
return { ok: false, status: 502, error: 'RainID 服务暂不可用，请稍后再试' };
|
||
}
|
||
}
|
||
```
|
||
|
||
你的登录路由这样接线（`routes/auth.js` 实测模式）：
|
||
|
||
```js
|
||
router.post('/login', loginLimiter, async (req, res) => {
|
||
// ...验证码校验略
|
||
if (db.getSetting('rainid_enabled') === '1') {
|
||
// ① admin 逃生通道：本地 admin 且有本地密码 → 走本地 bcrypt（见 §4）
|
||
const localUser = db.get('SELECT * FROM users WHERE username = ?', [username]);
|
||
if (localUser && localUser.role === 'admin' && !!localUser.password) {
|
||
if (!bcrypt.compareSync(password, localUser.password))
|
||
return res.status(401).json({ error: '用户名或密码错误' });
|
||
const token = jwt.sign({...}, SECRET, { expiresIn: '7d' });
|
||
return res.json({ token, ... });
|
||
}
|
||
// ② 其余用户：转发 RainID（ROPC）
|
||
const r = await rainidRopcLogin(username, password);
|
||
if (!r.ok) return res.status(r.status).json({ error: r.error });
|
||
const token = jwt.sign({ id: r.user.id, ... }, SECRET, { expiresIn: '7d' });
|
||
return res.json({ token, ... });
|
||
}
|
||
// ③ RainID 未启用 → 本地 bcrypt 登录（原有逻辑保留）
|
||
...
|
||
});
|
||
```
|
||
|
||
### 2.7 登出联动 end_session
|
||
|
||
```js
|
||
router.get('/logout', async (req, res) => {
|
||
const s = getOidcSettings();
|
||
if (!s.enabled) return res.redirect('/');
|
||
try {
|
||
const config = await getOidcConfig();
|
||
const url = openidClient.buildEndSessionUrl(config, {
|
||
// ⚠️ 此地址必须在 RainID Admin 的 post_logout_redirect_uris 里登记过，否则 400
|
||
post_logout_redirect_uri: siteBase(req) + '/login.html',
|
||
});
|
||
res.redirect(url.href); // 用户确认后 RainID 303 回跳 login.html
|
||
} catch (err) {
|
||
console.error('[RainID] logout error:', err.message);
|
||
res.redirect('/'); // RainID 故障时至少能回站内
|
||
}
|
||
});
|
||
```
|
||
|
||
前端（`Layout.jsx` 实测）：`rainid_enabled=1` 时登出按钮跳 `/api/auth/oidc/logout`（整页跳，让 RainID 处理完再回来），否则直接清本地 token。
|
||
|
||
**清本地会话的时点**：RainID 回跳 `login.html` 后，前端 `logout()` 清 localStorage token 即可（你的 JWT 是有时效的；要彻底就再调一次 revocation，非必需）。
|
||
|
||
---
|
||
|
||
## 3. 配置项设计：哪些进设置、哪些进机密存储
|
||
|
||
**⚠️ 最易踩的坑：凡前端需要读的 key，必须同时加进"公开设置白名单"，否则前端 `getPublicSettings()` 拿不到 → 功能静默失效**（RainWeb 踩过 `rainid_register_redirect` 漏 PUBLIC_KEYS，见 §5.4）。
|
||
|
||
### 3.1 三个集合（RainWeb 实测结构）
|
||
|
||
```js
|
||
// ① 公开设置白名单：任何未登录用户可读（前端页面依赖）
|
||
const PUBLIC_KEYS = [
|
||
'site_name', /* ... */,
|
||
'rainid_enabled', 'rainid_register_redirect', // ← 前端判断显示 RainID 按钮/注册托管
|
||
/* ... */
|
||
];
|
||
|
||
// ② 管理端可读（adminOnly GET）：包含全部非敏感配置
|
||
const ALL_KEYS = [
|
||
/* ... */,
|
||
'rainid_enabled', 'rainid_client_id', 'rainid_discovery_url', 'rainid_register_redirect',
|
||
/* ... */
|
||
];
|
||
|
||
// ③ 可写白名单：管理端可写（adminOnly PUT）。机密 key 在此，但绝不在 ②
|
||
const ALLOWED_SET = [...ALL_KEYS, 'rainid_client_secret']; // ← secret 只写不读！
|
||
```
|
||
|
||
**机密存储原则**：
|
||
- `rainid_client_secret` **优先 `.env.json`（gitignored）**，server.js 启动时注入环境变量 `RAINID_CLIENT_SECRET`，运行时还有 `.env.json` 直读和后台设置两档回退（见 `lib/rainid.js getClientSecret()`）。
|
||
- 后台设置通道**可写不可读**：`ALLOWED_SET` 里有它（能写），`ALL_KEYS` 里没有它（GET `/api/settings` 不返回），浏览器和 API 都读不到明文。
|
||
- **fail-closed**：`rainid_enabled='1'` 但 `client_id`/`client_secret` 任一缺失 → `enabled=false`，RainID 按钮不出现、ROPC 拒绝，**本地登录不受影响**。启动时打 warning 日志。
|
||
|
||
### 3.2 配置清单
|
||
|
||
| key | 敏感 | 公开可读 | 说明 |
|
||
|---|---|---|---|
|
||
| `rainid_enabled` | 否 | ✅ | `'1'`/'0'，前端据此显示按钮 |
|
||
| `rainid_client_id` | 否 | ❌ | 管理端可改 |
|
||
| `rainid_client_secret` | ✅ | ❌ | 只写不读，双通道 |
|
||
| `rainid_discovery_url` | 否 | ❌ | 默认 `https://rainid.rainnya.asia/oauth` |
|
||
| `rainid_register_redirect` | 否 | ✅ | `'1'` 时前端整页跳 RainID 注册页 |
|
||
|
||
---
|
||
|
||
## 4. Admin 逃生通道（IdP 故障时的 break-glass）
|
||
|
||
**原则：启用 RainID 后，绝不能出现"RainID 挂了管理员也进不去后台"的死局。**
|
||
|
||
RainWeb 实践（`routes/auth.js`）：
|
||
|
||
```js
|
||
if (db.getSetting('rainid_enabled') === '1') {
|
||
// 逃生通道：本地 admin 账号（有本地 bcrypt 密码）始终可用本地密码登录
|
||
const localUser = db.get('SELECT * FROM users WHERE username = ?', [username]);
|
||
const isAdminEscape = localUser && localUser.role === 'admin' && !!localUser.password;
|
||
if (isAdminEscape) {
|
||
if (!bcrypt.compareSync(password, localUser.password)) {
|
||
return res.status(401).json({ error: '用户名或密码错误' });
|
||
}
|
||
const token = jwt.sign({ id: localUser.id, username: localUser.username, role: localUser.role },
|
||
SECRET, { expiresIn: '7d' });
|
||
return res.json({ token, username: localUser.username, role: localUser.role, ... });
|
||
}
|
||
// 其余用户 → ROPC 转发 RainID
|
||
const r = await rainidRopcLogin(username, password);
|
||
...
|
||
}
|
||
```
|
||
|
||
规则：
|
||
1. **本地 admin + 有本地密码** → 永远走本地 bcrypt，不经 RainID。即使 RainID 完全宕机、discovery 失败，admin 还能登录后台。
|
||
2. **影子账号（`rainid_user_id` 非空）给随机不可登录密码** → 在本地登录分支里显式禁止（`user.rainid_user_id && !user.password` 直接拒绝），防止影子账号被猜到密码本地登入。
|
||
3. 配套兜底：**首次接入前先建一个本地 admin 并记住密码**（RainWeb 播种的 `admin/admin123` 即为这个角色），再开 `rainid_enabled`。
|
||
|
||
---
|
||
|
||
## 5. 踩坑实录（按严重程度排序）
|
||
|
||
### 5.1 [致命] discovery 传字符串 → 全部登录 502
|
||
|
||
- **现象**：启用 RainID 后，ROPC 登录和授权码登录全部失败；后端日志 `server must be an instance of URL`。
|
||
- **根因**：openid-client **v6 函数式 API** 的 `discovery()` 第一参数必须是 `new URL()` 实例；v5 类式 API 接受字符串，升级后行为变了，网上旧示例都是字符串。传字符串直接抛 TypeError。
|
||
- **修复**：
|
||
```js
|
||
// ❌ v5 时代：openidClient.Issuer.discover('https://...')
|
||
// ✅ v6：必须 new URL()
|
||
configCache = await openidClient.discovery(new URL(discoveryUrl), clientId, clientSecret);
|
||
```
|
||
- **预防**：升级 openid-client 大版本后跑一遍登录全流程；读 changelog 的 breaking changes。
|
||
|
||
### 5.2 [高] RainID 端点写成 http:// 被 openid-client 拒绝（RFC 9700）
|
||
|
||
- **现象**：配置 `rainid_discovery_url=http://rainid...`（或反代配错协议）→ discovery 失败，登录 502。
|
||
- **根因**：openid-client 遵循 RFC 9700（OAuth 2.0 over HTTPS），**拒绝 http 端点**（localhost 除外）。RainWeb 错误文案就是为此写的："Discovery 失败（检查端点是否为 https）"。
|
||
- **修复**：端点统一 `https://rainid.rainnya.asia/oauth`；**确认反代回源协议**——如果你的站点跑在反代后面，回调的 `req.protocol` 会算错，redirect_uri 变成 `http://` 导致 RainID 侧"回调未登记"。处理：优先用 `site_url` 设置拼基址，或用 `app.set('trust proxy', 1)` + 反代带 `X-Forwarded-Proto`。
|
||
- **预防**：`siteBase(req)` 优先读 `site_url` 设置，回退请求头，且反代必须正确转发协议。
|
||
|
||
### 5.3 [高] id_token 无 email/name（`conformIdTokenClaims`）→ 必须 userinfo
|
||
|
||
- **现象**：回调里 `tokens.claims()` 只有 `sub`，`email`/`name` 全是 undefined → 影子账号 email 为空、头像昵称丢。
|
||
- **根因**：RainID 的 access_token 是 opaque，`conformIdTokenClaims=true` 语义下 **id_token 只带 openid scope 的声明（sub）**，`profile`/`email` 数据在 userinfo 端点（OIDC Core 5.4）。拿 id_token 当唯一数据源是普遍错觉。
|
||
- **修复**：
|
||
```js
|
||
const userinfo = await openidClient.fetchUserInfo(config, tokens.access_token, sub);
|
||
// userinfo: { sub, name, preferred_username, picture, email, email_verified }
|
||
```
|
||
并顺手用 `sub` 校验 userinfo 与 id_token 一致（防 userinfo 注入）。
|
||
|
||
### 5.4 [高] 设置 key 漏 PUBLIC_KEYS → 前端功能静默失效
|
||
|
||
- **现象**：后台打开了 `rainid_register_redirect`，注册页却仍显示本地表单；无任何报错。
|
||
- **根因**：注册页靠 `settingsApi.getPublicSettings()` 读 `rainid_register_redirect`，但该 key 只加了 `ALL_KEYS` 没加 `PUBLIC_KEYS` → 前端拿到 `undefined`，静默走本地注册分支。**公共配置接口返回 undefined 不报错，是最难排查的一类 bug**。
|
||
- **修复**：`rainid_register_redirect` 加入 `PUBLIC_KEYS`。
|
||
- **预防**：凡是"前端根据设置决定显示逻辑"的 key，写完务必在 `/api/settings/public` 响应里确认存在；加新前端依赖的 key 时列 checklist。
|
||
|
||
### 5.5 [中] end_session 卡确认页不回跳（RainID 侧 issue）
|
||
|
||
- **现象**：登出跳 RainID 后停在"确认退出"页，点了确认不回跳你的站点。
|
||
- **根因**：`post_logout_redirect_uri` 未在 RainID Admin 登记，或登记的与请求的不完全一致（域名大小写/结尾斜杠/协议）。RainID 侧拒绝回跳时只渲染提示页（oidc-provider 行为），没有 303。
|
||
- **修复**：在 RainID Admin 的 `post_logout_redirect_uris` 精确登记你 `buildEndSessionUrl` 传的完整 URL（含路径 `/login.html`）；检查域名规范化。
|
||
- **预防**：登出回跳地址做成常量与 `siteBase` 拼接，保证与登记一致；登记时复制请求里实际的 URL。
|
||
|
||
### 5.6 [中] ROPC 未进"密码直连白名单" → invalid_grant 静默失败
|
||
|
||
- **现象**：密码明明正确，ROPC 登录始终 `400 invalid_grant`，文案统一"用户名/邮箱或密码错误"。
|
||
- **根因**：RainID 对 `password` grant 有 **Admin 站点设置 → 密码直连白名单**（`system_settings.client_password_grant.allowed`）。client 不在白名单 → `invalid_grant`，**文案与凭据失败完全一致**（防枚举设计）→ 让你误以为密码错了。
|
||
- **修复**：RainID Admin 把该 client_id 加进密码直连白名单（前置条件：client 必须机密 client、grant_types 含 `password`）。
|
||
- **预防**：接入文档 §5.1 四条前置逐条核对；ROPC 配好第一件事就是 curl 一次 token 端点确认不是白名单问题（见 §6）。
|
||
|
||
### 5.7 [低] 测试端口避开 3k-4k（RainID 占 3001）
|
||
|
||
- **现象**：本地开发时浏览器明明打开了 RainID 页面，但跳回登录总失败/串数据。
|
||
- **根因**：RainWeb 开发端口 3001 与 RainID 本地实例端口**冲突**，你在开自己的服务时把 RainID 顶掉了（或反之）。
|
||
- **修复**：自己的开发端口避开 3k-4k 区间（RainID 用 3001，vite 代理硬编码 3101）；或至少确认本地测试时 RainID 实例可用。
|
||
- **预防**：多项目共存时先在项目文档里登记"占用的端口清单"。
|
||
|
||
---
|
||
|
||
## 6. 快速排障指南：登录报错按什么顺序查
|
||
|
||
**自顶向下，每层 30 秒内能判**。RainWeb 线上排障就是这个顺序：
|
||
|
||
### L1 进程层
|
||
- 后端进程还活着吗？`node cli.js status` / `ps aux | grep server`。
|
||
- 重启过吗？**改了 discovery_url / client 配置要重启**（discovery 有进程级缓存）。
|
||
|
||
### L2 依赖层
|
||
- `openid-client` 版本？v5→v6 是 breaking（§5.1）。
|
||
- Node 版本？openid-client v6 需要较新 Node（`require('esm')`），RainWeb 要求 Node ≥23 / 22+。
|
||
- 启动有没有 require 报错？`node -e "require('openid-client')"` 一把验证。
|
||
|
||
### L3 配置层
|
||
- 后端日志有没有 `RAINID_NOT_CONFIGURED` / "client_id 或 client_secret 未配置"？→ 检查 `.env.json` 的 `rainid_client_secret`、后台 `rainid_client_id`。
|
||
- `rainid_enabled='1'` 且三项齐全？**fail-closed 下任一缺失按钮都不会出现**，先看前端到底有没有按钮。
|
||
- **管理端 GET /api/settings 里能看到 `rainid_client_secret` 吗？** 能看到就是泄露（正常不该返回）。
|
||
- 前端读到的公开设置对不对？`curl /api/settings/public` 确认 `rainid_enabled`/`rainid_register_redirect` 在不在响应里（§5.4）。
|
||
|
||
### L4 网络层
|
||
- `curl -sI https://rainid.rainnya.asia/oauth/.well-known/openid-configuration` 通不通？
|
||
- `curl -s https://rainid.rainnya.asia/oauth/.well-known/openid-configuration | head` 看是不是 json？
|
||
- 本地 dev 端口有没有和 RainID 冲突（§5.7）？反代有没有把协议降级成 http（§5.2）？
|
||
|
||
### L5 协议层（最细，看 error code）
|
||
|
||
用 curl 直接打 token 端点，绕过前端看原始错误：
|
||
|
||
```bash
|
||
# ROPC 直测（秒杀"白名单还是密码错"之争，§5.6）
|
||
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
|
||
-d "grant_type=password&username=test&password=xxx&scope=openid%20profile%20email" \
|
||
https://rainid.rainnya.asia/oauth/token
|
||
```
|
||
|
||
| 返回 | 判定 | 处理 |
|
||
|---|---|---|
|
||
| `400 invalid_grant` | ①凭据错 ②账号锁 ③2FA ④**白名单缺** | 换已确认密码重试；看 error_description 是否含"二次验证"；查 Admin 白名单 |
|
||
| `401 invalid_client` | client_id/secret 错或非机密 client | 核对 Admin client 配置 |
|
||
| `400 invalid_scope` | scope 超白名单 | Admin 扩 scope 白名单 |
|
||
| `429 rate_limited` | 限流 | 退避；也检查自己有没有重复请求循环 |
|
||
| `400 redirect_uri not registered` | 回调未登记/拼接不一致 | 检查 `siteBase` 拼出的 redirect_uri 与登记是否逐字符一致 |
|
||
| `400 post_logout_redirect_uri not registered` | 登出回跳未登记（§5.5） | Admin 登记完整 URL |
|
||
| 502 / discovery 失败 | §5.1 / §5.2 | 查 URL 实例化与 https |
|
||
|
||
### 前端侧速查
|
||
- 白屏 + console "MIME type text/html" → 不是 OIDC 问题，是**构建产物缺失**（`npm run build` + 强刷）。
|
||
- 地址栏残留 `?oidc_ticket=...` → 前端没兑换成功，看 network 里 POST `/exchange` 的响应。
|
||
- `oidc_error=invalid_scope` → 前端按钮正常，后端 scope 配多了，回 L5。
|
||
|
||
---
|
||
|
||
## 附：RainWeb 关键文件索引（抄作业对照）
|
||
|
||
| 需求 | 文件 |
|
||
|---|---|
|
||
| discovery 缓存 / secret 双通道 / 影子账号 / ROPC | `lib/rainid.js` |
|
||
| 授权码三路由 + ticket + 登出联动 | `routes/oidc.js` |
|
||
| ROPC 接线 + admin 逃生通道 + 影子账号禁本地登入 | `routes/auth.js` |
|
||
| PUBLIC_KEYS / ALL_KEYS / ALLOWED_SET | `routes/settings.js` |
|
||
| 前端登录页（oidc_ticket/oidc_error 收尾） | `frontend/src/pages/Login.jsx` |
|
||
| 前端注册页（注册托管跳转） | `frontend/src/pages/Register.jsx` |
|
||
| 登出联动按钮 | `frontend/src/components/Layout.jsx` |
|
||
| 后台设置表单（secret 置空不回显） | `frontend/src/admin/pages/Settings.jsx` |
|
||
| 唯一索引迁移 | `db.js` migrations |
|
||
|
||
---
|
||
|
||
*本文基于 RainWeb × RainID 线上接入实践整理。协议细节以 RainID `docs/OIDC对接文档.md` 为准。*
|