dsh-webui-oauth 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.6.4
+
+修复 OIDC 回调结束后浏览器**停在 JSON 页面上**、需要手动回退的问题。
+
+### 修复：绑定/登录结束后自动回到应用并给出提示
+
+- **现象**：点「绑定 OIDC 身份」完成 IdP 往返后，浏览器停在一段 JSON 上
+  （如 `{"ok":true,"bound":true,"sub":"..."}`），必须手动按后退键回到设置页；
+  失败时同样如此（例如 `{"ok":false,"error":"oidc-authorize-failed",...}`）。
+- **原因**：回调端点直接 `sendJson` 渲染结果。但 OIDC 回调是**浏览器主导的顶层导航**
+  （用户点按钮 → 302 到 IdP → 302 回回调），渲染 JSON 等于把用户丢在一个死页面上，
+  而且看不出操作到底成没成功。
+- **修复**：成功与失败都 **302 回应用**，并带一个回执参数由前端提示：
+  - 成功：`?oidcbound=1` → 设置页提示「OIDC 身份绑定成功」；
+  - 失败：`?oidcerr=<原因>` → 按原因给出可读提示（授权失效 / 未绑定 / 身份不匹配）。
+  回跳复用 `postLoginRedirect()`，顺带完成核心的 launch-token → cookie 交换，
+  否则回到首页仍会被核心 401 拦住。前端读取回执后会用 `history.replaceState`
+  清掉 query，避免刷新时重复提示。
+
+### 安全
+
+- 回执里**不含** sub 等敏感值（只有 `oidcbound=1` / `oidcerr=原因码`），
+  避免把身份标识写进浏览器历史与访问日志。
+
+### 测试
+
+- `test/oidc-bind.test.mjs` 新增「绑定成功后必须回到应用」用例，并把失败路径断言
+  改为校验 302 + 回执；`test/oidc-integration.test.mjs` 的状态校验用例同步更新。
+- 已确认能抓出修复前的行为（回退成 sendJson 时 2 项 FAIL）。
+- 全量 342 项断言通过。
+
+## 0.6.3
+
+修复部分 IdP 下**绑定 OIDC 立即失败**的问题（点「绑定 OIDC 身份」后立刻收到
+`oidc-authorize-failed / invalid_request`）。
+
+### 修复：授权请求携带了 IdP 不支持的 prompt 参数
+
+- **现象**：点绑定后浏览器被 IdP 打回，回调形如
+  `.../oidc/callback?error=invalid_request&error_description=unsupported+prompt+value+requested`，
+  界面显示 `{"ok":false,"error":"oidc-authorize-failed","detail":"invalid_request"}`。
+- **原因**：插件在授权请求里**硬编码**了 `prompt=select_account`。该参数是 OIDC 的
+  可选扩展，不同 IdP 支持度差异极大；不支持的 IdP 会直接拒绝整个授权请求，
+  于是授权根本发不出去。
+- **修复**：默认**不发送** `prompt`。需要"强制选择账号"行为的部署可在设置页
+  **Prompt（可选）** 里显式填写（如 `select_account`），留空即不携带该参数。
+
+### 建议
+
+- 若你此前被此问题挡住，升级后**重新点一次绑定**即可，无需改动其它配置。
+- 多数 IdP 的登录页本来就会让用户选择账号，因此该参数通常不必填。
+
+### 测试
+
+- `test/oidc-integration.test.mjs` 增加两条断言：默认不携带 `prompt`、
+  显式配置时如实携带。已确认能抓出修复前的行为（回退硬编码时 2 项 FAIL）。
+- 另在隔离实例上用**会拒绝 prompt 的 IdP**（复刻同类行为）做了端到端对照：
+  带 `prompt` 复现出完全相同的错误；去掉后绑定成功、随后 SSO 登录成功。
+- 全量 337 项断言通过。
+
 ## 0.6.2
 
 修复设置页在**切走再切回**时不回显已有配置的问题。

package/index.js

@@ -2267,6 +2267,8 @@ export async function apply(ctx) {
                 trustBrowserOrigin: oidcCfg.trustBrowserOrigin !== false,
                 bound: isOidcBound(creds),
                 boundSubHint: isOidcBound(creds) ? maskSubForDisplay(boundSubOf(creds)) : null,
+                // prompt 是可选参数，回传当前值供设置页回显（缺省为空 = 不发送）。
+                prompt: typeof oidcCfg.prompt === 'string' ? oidcCfg.prompt : '',
                 // 提供给 IdP 登记用的确切回调地址。原生 OIDC 要求 redirect_uri 精确匹配，
                 // 部署者必须把它抄进 IdP 的允许列表，因此这里直接算好给他。
                 // 不能只给路径：IdP 侧需要完整的 scheme + host + port。
@@ -2415,6 +2417,9 @@ export async function apply(ctx) {
             scope: typeof oidcIn.scope === 'string' ? oidcIn.scope : undefined,
             redirectBase: typeof oidcIn.redirectBase === 'string' && oidcIn.redirectBase.trim() ? oidcIn.redirectBase.trim() : undefined,
             trustBrowserOrigin: oidcIn.trustBrowserOrigin !== undefined ? oidcIn.trustBrowserOrigin : true,
+            // prompt 默认不发（留空即 undefined）。仅在部署者显式填写时才带给 IdP，
+            // 因为不少 IdP 会因不认识的 prompt 值直接拒绝授权。
+            prompt: typeof oidcIn.prompt === 'string' && oidcIn.prompt.trim() ? oidcIn.prompt.trim() : undefined,
           }
         } else if (oidcIn && oidcIn.enabled === false) {
           oidcOut = { enabled: false }
@@ -2502,6 +2507,29 @@ export async function apply(ctx) {
    *
    * @returns {Promise<void>} 直接写响应，不返回内容
    */
+  /**
+   * 把浏览器送回应用，并带上一个回执码。
+   *
+   * 为什么需要它：OIDC 回调是**浏览器主导的顶层导航**——用户点「绑定」/「SSO 登录」，
+   * 浏览器 302 到 IdP，IdP 再 302 回本回调。如果这里渲染 JSON，用户就停在一个
+   * 死页面上，只能手动按后退键，而且不知道操作到底成没成功。
+   * 因此成功与失败都应 302 回应用，用 query 参数带上结果，由前端提示。
+   *
+   * 与登录路径一致地复用 postLoginRedirect()：既回到应用根，又能顺带完成
+   * 核心的 launch-token → cookie 交换（否则回到首页仍会被核心 401 拦住）。
+   *
+   * @param res 响应对象
+   * @param code 回执码，前端据此展示提示（如 oidcbound=1 / oidcerr=...）
+   * @param extraHeaders 额外的响应头（如清除一次性 state Cookie）
+   */
+  function redirectBackToApp(ctx2, req, res, code, extraHeaders) {
+    let target = '/'
+    try { target = postLoginRedirect(ctx2, req) || '/' } catch (e) { target = '/' }
+    const sep = target.includes('?') ? '&' : '?'
+    res.writeHead(302, { location: target + sep + code, ...(extraHeaders || {}) })
+    res.end()
+  }
+
   async function startOidcAuthorize(ctx2, req, res, purpose) {
     const creds = await readCredentials(ctx2)
     const o = await oidcOf(creds)
@@ -2543,7 +2571,15 @@ export async function apply(ctx) {
     authUrl.searchParams.set('nonce', nonce)
     authUrl.searchParams.set('code_challenge', oidcChallenge(verifier))
     authUrl.searchParams.set('code_challenge_method', 'S256')
-    authUrl.searchParams.set('prompt', 'select_account')
+    // prompt 是 OIDC 的【可选】参数，且不同 IdP 支持度差异极大：
+    // 部分 IdP（如某些企业 SSO）对不认识的 prompt 值直接回
+    // error=invalid_request&error_description=unsupported prompt value requested，
+    // 导致授权根本发不出去——表现就是"点绑定立刻失败"。
+    // 因此这里【默认不发送】：多数 IdP 的登录页本来就会让用户选账号，
+    // 显式 select_account 只对"已登录且想强制切换账号"的场景有意义。
+    // 需要该行为的部署可通过 oidc.prompt 显式声明（见 README）。
+    const promptValue = typeof o.prompt === 'string' ? o.prompt.trim() : ''
+    if (promptValue) authUrl.searchParams.set('prompt', promptValue)
     // 登录 CSRF 绑定：把 state 同时写进一个 HttpOnly 短时效 Cookie。回调时两者必须
     // 同时匹配——否则攻击者可先在自己的浏览器发起授权拿到 state，再诱导受害者带着
     // 该 state 完成回调，把受害者的浏览器登录进攻击者的账号（会话固定/登录 CSRF）。
@@ -2675,20 +2711,20 @@ export async function apply(ctx) {
         if (!st) {
           const why = known ? 'state 已过期（TTL ' + Math.round(OIDC_STATE_TTL_MS / 60000) + ' 分钟）' : 'state 无效、已使用或不存在'
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: why })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-state' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=invalid-state', clearStateCookie)
           return
         }
         // 登录 CSRF 绑定：回调必须由发起授权的同一浏览器完成（携带同值 Cookie）。
         // 只校验 state 存在于服务端集合不足以阻止“攻击者取 state、受害者完成回调”。
         if (cookieOf(req, COOKIE_OIDC_STATE) !== state) {
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: 'state Cookie 不匹配（疑似登录 CSRF）' })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-state' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=invalid-state', clearStateCookie)
           return
         }
         if (!code) {
           const err = params.get('error') || 'missing-code'
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: '授权被拒或缺少 code: ' + sanitizeSub(err) })
-          sendJson(res, 200, { ok: false, error: 'oidc-authorize-failed', detail: err })
+          redirectBackToApp(ctx, req, res, 'oidcerr=' + encodeURIComponent(err), clearStateCookie)
           return
         }
         // 换 token（authorization_code + PKCE verifier + client_secret）
@@ -2748,7 +2784,7 @@ export async function apply(ctx) {
         }
         if (!vres.ok) {
           await auditLog(ctx, 'oidc_login_failure', { ip: meta.ip, ua: meta.ua, detail: 'id_token 验证失败: ' + vres.error })
-          sendJson(res, 200, { ok: false, error: 'oidc-invalid-id-token', detail: vres.error })
+          redirectBackToApp(ctx, req, res, 'oidcerr=' + encodeURIComponent(vres.error), clearStateCookie)
           return
         }
         const rawSub = vres.payload.sub
@@ -2761,7 +2797,8 @@ export async function apply(ctx) {
           // 保留原有 username/hash/ttl，只加 boundSub —— 用 spread 以免漏字段。
           await writeCredentials(ctx, { ...creds, boundSub: rawSub })
           await auditLog(ctx, 'oidc_bind_success', { username: auditName, ip: meta.ip, ua: meta.ua })
-          sendJson(res, 200, { ok: true, bound: true, sub: auditName }, clearStateCookie)
+          // 成功必须【把浏览器送回应用】，而不是停在 JSON 上（见 redirectBackToApp 说明）。
+          redirectBackToApp(ctx, req, res, 'oidcbound=1', clearStateCookie)
           return
         }
 
@@ -2771,12 +2808,12 @@ export async function apply(ctx) {
         const bound = boundSubOf(creds)
         if (!bound) {
           await auditLog(ctx, 'oidc_login_failure', { username: auditName, ip: meta.ip, ua: meta.ua, detail: '尚未绑定 OIDC 身份，拒绝登录' })
-          sendJson(res, 200, { ok: false, error: 'oidc-not-bound' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=not-bound', clearStateCookie)
           return
         }
         if (!safeTokenEquals(String(rawSub), bound)) {
           await auditLog(ctx, 'oidc_login_failure', { username: auditName, ip: meta.ip, ua: meta.ua, detail: 'sub 与已绑定身份不匹配，拒绝登录' })
-          sendJson(res, 200, { ok: false, error: 'oidc-sub-mismatch', detail: '该 IdP 身份未被绑定到本 WebUI' }, clearStateCookie)
+          redirectBackToApp(ctx, req, res, 'oidcerr=sub-mismatch', clearStateCookie)
           return
         }
 

package/lib/client.js

@@ -91,6 +91,9 @@ window.__ModuleLoader__.load({
 				const [oidcScope, setOidcScope] = react.useState('openid profile email');
 				const [oidcRedirectBase, setOidcRedirectBase] = react.useState('');
 				const [oidcTrustBrowser, setOidcTrustBrowser] = react.useState(true);
+				// prompt（可选）。默认留空 = 不发送该参数——不少 IdP 会对不认识的
+				// prompt 值直接回 unsupported prompt value requested，导致授权发不出去。
+				const [oidcPrompt, setOidcPrompt] = react.useState('');
 				// 绑定状态：bound 表示已绑定某个 IdP 身份；boundSubHint 是掩码后的展示值
 				// （服务端只回传掩码，前端拿不到 sub 明文，也不应该拿）。
 				const [oidcBound, setOidcBound] = react.useState(false);
@@ -127,6 +130,7 @@ window.__ModuleLoader__.load({
 							setOidcClientId((o && o.clientId) || '');
 							if (o && o.scope) setOidcScope(o.scope);
 							if (o && o.redirectBase) setOidcRedirectBase(o.redirectBase);
+							if (o && typeof o.prompt === 'string') setOidcPrompt(o.prompt);
 							setOidcBound(!!(o && o.bound));
 							setOidcBoundHint((o && o.boundSubHint) || '');
 							setOidcRedirectUri((o && o.redirectUri) || '');
@@ -142,6 +146,34 @@ window.__ModuleLoader__.load({
 					};
 				}, []);
 
+				// 读取 OIDC 回调带回来的回执。绑定/登录结束后浏览器会被 302 回应用，
+				// 结果通过 query 传递（oidcbound=1 / oidcerr=...）：因为是整页跳转，
+				// 组件重新挂载时才知道刚才发生了什么。
+				react.useEffect(() => {
+					let qs = ''
+					try { qs = String((location && location.search) || '') } catch (e) { qs = '' }
+					if (!qs) return
+					const p = new URLSearchParams(qs)
+					const bound = p.get('oidcbound')
+					const err = p.get('oidcerr')
+					if (bound === null && err === null) return
+					if (bound !== null) {
+						setBindMsg({ kind: 'ok', text: 'OIDC 身份绑定成功。此后只有该身份可通过 SSO 登录。' })
+					} else {
+						const LABELS = {
+							'invalid-state': '授权会话已失效或被中断，请重新发起绑定',
+							'not-bound': '尚未绑定任何 OIDC 身份，SSO 登录已被拒绝',
+							'sub-mismatch': '该 IdP 身份未被绑定到本 WebUI，登录已被拒绝',
+						}
+						setBindMsg({ kind: 'err', text: 'OIDC 操作失败：' + (LABELS[err] || err) })
+					}
+					// 清掉 query：否则用户刷新页面会重复看到这条提示。
+					try {
+						const clean = location.pathname + location.hash
+						history.replaceState(null, '', clean)
+					} catch (e) { /* 无 history 时忽略 */ }
+				}, []);
+
 				// 与服务端 passwordStrength 一致的同步校验
 				const SPECIAL_CHARS = /[!@#$%^&*()_+\-=\[\]{}|;:,.<>?/~]/;
 				function checkPassword(p) {
@@ -186,6 +218,8 @@ window.__ModuleLoader__.load({
 					scope: oidcScope.trim(),
 					redirectBase: oidcRedirectBase.trim() || null,
 					trustBrowserOrigin: oidcTrustBrowser,
+					// 留空即不发送 prompt（服务端会存成 undefined）
+					prompt: oidcPrompt.trim(),
 				};
 				api('/dsh-webui-oauth/configure', { username: name, password, current, ttl: Number(ttl), oidc: oidcPayload }).then((r) => {
 						setBusy(false);
@@ -439,6 +473,12 @@ window.__ModuleLoader__.load({
 								react.createElement('input', { type: 'checkbox', checked: oidcTrustBrowser, onChange: (e) => setOidcTrustBrowser(e.target.checked) }),
 								' 信任浏览器 origin（默认开启；关闭时仅用上方 Redirect Base）'),
 						),
+						react.createElement('div', { className: 'wua-row' },
+							react.createElement('label', { className: 'wua-label' }, 'Prompt（可选，建议留空）'),
+							react.createElement('input', { className: 'wua-input', type: 'text', value: oidcPrompt, spellCheck: false, placeholder: '留空则不发送该参数', onChange: (e) => setOidcPrompt(e.target.value) }),
+							react.createElement('p', { className: 'wua-hint', style: { borderTop: 'none', paddingTop: 0 } },
+								'多数 IdP 无需该参数。部分 IdP 会对不认识的值直接拒绝授权（提示 unsupported prompt value requested），此时请保持留空。'),
+						),
 					) : null,
 					// ---- OIDC 身份绑定 ----
 					// 绑定是访问控制前提：未绑定时任何能通过该 IdP 的人都会被拒，

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "type": "module",
   "main": "index.js",
   "scripts": {