dsh-webui-oauth 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 本文件记录每个版本的**用户可见**变更。破坏性变更与升级动作单独标注。
 
+## 0.6.0
+
+新增 **OIDC 身份绑定**：配置 OIDC 不再等于谁都能登录，必须显式绑定一个 IdP 身份。
+
+### 新增：OIDC 绑定 / 解绑（访问控制）
+
+- **绑定前，OIDC 登录一律拒绝**。此前只要配置了 OIDC，任何能通过该 IdP 验证的人都能进入
+  WebUI——IdP 侧的任何账号都成为本 WebUI 的入口。现在未绑定时 `/oidc/login` 直接返回
+  `oidc-not-bound`，登录页也不显示 SSO 按钮。
+- **绑定**：本地账号登录后，在**设置 → 身份认证 → OIDC 身份绑定**点「绑定 OIDC 身份」，
+  走一次 IdP 授权，回调里校验通过的 `sub` 会存入凭据文件（`boundSub`）。此后**只有该
+  身份**能通过 SSO 登录。
+- **解绑**：点「解除绑定」（需当前密码），清空 `boundSub`，SSO 登录立即恢复为「一律拒绝」。
+- 绑定状态在设置页可见；服务端只回传**掩码后**的 sub（如 `su*****ce`），不把原始标识
+  发给浏览器。
+- 新增端点：`GET /dsh-webui-oauth/oidc/bind`（需已登录会话）、
+  `POST /dsh-webui-oauth/oidc/unbind`（需当前密码）。
+- 审计新增 `oidc_bind_success` / `oidc_unbind_success` / `oidc_unbind_failure`。
+
+### 兼容性
+
+- 旧凭据文件没有 `boundSub` 字段 → 视为**未绑定**，OIDC 登录被拒。这是安全方向：
+  升级不会因为"多出"一个 OIDC 入口而放开访问。需要 OIDC 登录的部署升级后请重新绑定一次。
+- 「禁用认证」会重置凭据文件，绑定关系一并清除；重新启用后需重新绑定。
+
+### 修复
+
+- 登录页 `GET /login` 在拼接 SSO 按钮状态时引用了未定义变量（写作 `creds` 而非
+  `credsNow`），导致登录页直接 500、整个 WebUI 无法登录。已修复并补回归测试
+  （该分支只在浏览器 GET 时走到，纯 JSON 用例覆盖不到）。
+
+### 测试
+
+- 新增 `test/oidc-bind.test.mjs`（25 项）：未绑定拒登、绑定端点鉴权、sub 不匹配拒登
+  （不发会话）、匹配 sub 可登录、解绑需密码、解绑后拒登、旧凭据兼容、登录页渲染。
+- 全量 314 项断言通过。
+
 ## 0.5.1
 
 修复 OIDC 密钥轮换后长时间无法登录的问题。**使用 OIDC/SSO 的部署建议升级。**

package/README.en.md

@@ -101,7 +101,8 @@ Authentication is enforced in four layers, all implemented by **wrapping the web
   - `trustBrowserOrigin` defaults to `true` when omitted (legacy behavior); an explicit `false` makes both sites **ignore** the browser-influenced origin and use `publicBaseUrl`. With no `publicBaseUrl` either, the token redirect falls back to the request Host / loopback, and OIDC fails closed with an error.
   - The old `oidc.trustBrowserOrigin` is still accepted: when the settings section does not set the switch explicitly, it is used as the fallback, so existing deployments migrate smoothly.
   - **Host-rewriting reverse proxies**: when the proxy rewrites `Host` to a loopback address (`127.0.0.1:3080`, `::1`, `localhost`, `0.0.0.0`) and sends nothing else, the plugin **cannot** recover the browser-side address from the request, so it treats the address as proxy-rewritten and uses the configured `publicBaseUrl` directly (the legacy "declare the public address in settings.yaml" advice was ineffective in that shape, because `publicBaseUrl` was only trusted on an exact Host match). If the proxy can send the original host, `X-Forwarded-Host` (or RFC 7239 `Forwarded: host=`) is preferred over the request Host for building the redirect.
-- **Optional OIDC SSO (0.4.0)**: standards-based authorization-code + PKCE with a **confidential client (client_secret required)**, security-benchmarked against Logto. Once configured, the login page shows an "SSO single sign-on" button; after IdP authentication the plugin creates a local session keyed by the IdP `sub` (reusing the session TTL and persistence). The **redirect_uri base is set by `oidc.redirectBase`**; by default the browser is trusted (it trusts the front-end `location.origin` — under a host-rewriting reverse proxy the browser's public address is correct), ****constrained by the unifed switch above****; when disabled only the configured `redirectBase` is used; if neither is available it fails closed with an error. id_token signatures support **RSA (RS256/384/512, PS256/384/512), EC (ES256/384/512) and EdDSA (Ed25519)**, with iss/aud/exp/iat/nbf/nonce and JWKS(kid) validation (see "Signature algorithm support" below). Logout is the simple variant: it clears the local session only.
+- **Optional OIDC SSO (0.4.0; identity binding required since 0.6.0)**: standards-based authorization-code + PKCE with a **confidential client (client_secret required)**, security-benchmarked against Logto. **Configuring OIDC does not mean anyone can log in**: you must first bind one IdP identity. Until then OIDC login is refused outright and the login page hides the SSO button (see the next bullet). Once bound, the login page shows an "SSO single sign-on" button; after IdP authentication the plugin creates a local session keyed by the IdP `sub` (reusing the session TTL and persistence).
+- **OIDC identity binding / unbinding (0.6.0)**: binding = log in with the local account, then click "绑定 OIDC 身份" under **Settings → Authentication → OIDC identity binding** and complete one IdP authorization; the verified `sub` is stored in the credentials file (`boundSub`), and **only that identity** can then log in via SSO. Unbinding = click "解除绑定" (current password required); once cleared, SSO login immediately reverts to "refuse everything". The settings page only ever shows a masked sub (e.g. `su*****ce`). A credentials file without `boundSub` counts as unbound, so upgrading never opens access. The **redirect_uri base is set by `oidc.redirectBase`**; by default the browser is trusted (it trusts the front-end `location.origin` — under a host-rewriting reverse proxy the browser's public address is correct), ****constrained by the unifed switch above****; when disabled only the configured `redirectBase` is used; if neither is available it fails closed with an error. id_token signatures support **RSA (RS256/384/512, PS256/384/512), EC (ES256/384/512) and EdDSA (Ed25519)**, with iss/aud/exp/iat/nbf/nonce and JWKS(kid) validation (see "Signature algorithm support" below). Logout is the simple variant: it clears the local session only.
 - **Scheme-adaptive post-login redirect (0.3.3, fixes #6 / #7)**: after a successful login the plugin sends the browser to the core's token-bearing root URL. Its **authority now comes from the request Host** (no longer hardcoded to `127.0.0.1`) and its **scheme follows the protocol the request actually used**, resolved in this order: ① the operator's explicit `remote-web-ui.publicBaseUrl` (**trusted only when its host/port matches the incoming Host** — otherwise a LAN direct hit would be redirected to the public address and lose the freshly issued session cookie to a cross-origin hop); ② the standard proxies headers `X-Forwarded-Proto` (leftmost value) or RFC 7239 `Forwarded: proto=`; ③ a TLS-terminating socket (`socket.encrypted`); ④ fallback `http`. It deliberately does **not** guess "non-IP hostname ⇒ https", which would turn plain-http intranet access (`http://nas.local:3080`) into a dead https link. The login page adds a one-way client-side fallback: an https page receiving a **same-origin** `http://` redirect upgrades it to `https://` (never downgrades, never rewrites another origin).
 
 Sessions are **server-side and persisted to disk** (`sessions.jsonl`, survive a DSH restart, expire server-side), carried by an `HttpOnly; SameSite=Lax` cookie (`dsh_wua_session`) that JS cannot read; changing the password **revokes every other session**.

package/README.md

@@ -118,7 +118,8 @@ DSH WebUI 身份认证插件（持久化插件）。在「设置 → 身份认
 
   **已知取舍**：本机浏览器直连 `http://127.0.0.1:3080` 也落进第 2 行，于是开关开着也会跳 `publicBaseUrl`。要同时支持本机直连，只能让反代下发 `X-Forwarded-Host`（走第 1 行）。
 - **登录后跳转的协议自适应（0.3.3，修 #6 / #7）**：插件登录成功后要把浏览器引导到核心的带 token 根地址，其 **authority 取自本次请求的 Host**（不再写死 `127.0.0.1`），**scheme 按请求实际协议解析**，优先级：① 操作者显式声明 `remote-web-ui.publicBaseUrl`（**仅当其 host/port 与本次请求 Host 一致时**采信——否则局域网直连会被重定向到公网地址、跨源丢掉刚下发的会话 Cookie）；② 标准代理头 `X-Forwarded-Proto`（取最左值）或 RFC 7239 `Forwarded: proto=`；③ socket 自身是 TLS（插件直接终结 TLS）；④ 兜底 `http`。**刻意不做「非 IP 域名即 https」的猜测**——那会把纯 http 的内网域名访问（`http://nas.local:3080`）打成 https 死链。前端登录页另有一层单向兜底：页面在 https 下收到**同源** `http://` 跳转时自动升级为 `https://`（反向不降级、异源不改写）。
-- **可选 OIDC 单点登录（0.4.0）**：标准 OIDC 授权码 + PKCE（机密客户端，须 `client_secret`），以 Logto 为安全基准。配置后登录页出现「SSO 单点登录」按钮，认证通过后以 IdP 的 `sub` 建立本地会话（沿用会话有效期与持久化）。**redirect_uri 的 base 由 `oidc.redirectBase` 决定；默认交由浏览器处理（采信前端 `location.origin`，反代重写 Host 时浏览器看到的公网地址即正确），受上面统一开关约束；关闭时仅用配置的 `redirectBase`；两者都不可用则 fail-closed 报错。** id_token 签名支持 **RSA（RS256/384/512、PS256/384/512）、EC（ES256/384/512）、EdDSA（Ed25519）**，配合 iss/aud/exp/iat/nbf/nonce 与 JWKS(kid) 校验（见下节「签名算法支持」）。登出为简单版：仅清本地会话。
+- **可选 OIDC 单点登录（0.4.0；0.6.0 起需绑定身份）**：标准 OIDC 授权码 + PKCE（机密客户端，须 `client_secret`），以 Logto 为安全基准。**配置 OIDC ≠ 谁都能登录**：必须先绑定一个 IdP 身份，绑定前 OIDC 登录一律拒绝、登录页也不显示 SSO 按钮（见下条）。绑定后登录页出现「SSO 单点登录」按钮，认证通过后以 IdP 的 `sub` 建立本地会话（沿用会话有效期与持久化）。
+- **OIDC 身份绑定 / 解绑（0.6.0）**：绑定 = 本地账号登录后在**设置 → 身份认证 → OIDC 身份绑定**点「绑定 OIDC 身份」，走一次 IdP 授权，校验通过的 `sub` 存入凭据文件（`boundSub`）；**此后只有该身份能通过 SSO 登录**。解绑 = 点「解除绑定」（需当前密码），清空后 SSO 登录立即恢复为「一律拒绝」。设置页只显示掩码后的 sub（如 `su*****ce`）。旧凭据文件无 `boundSub` 字段时视为未绑定（升级不会放开访问）。**redirect_uri 的 base 由 `oidc.redirectBase` 决定；默认交由浏览器处理（采信前端 `location.origin`，反代重写 Host 时浏览器看到的公网地址即正确），受上面统一开关约束；关闭时仅用配置的 `redirectBase`；两者都不可用则 fail-closed 报错。** id_token 签名支持 **RSA（RS256/384/512、PS256/384/512）、EC（ES256/384/512）、EdDSA（Ed25519）**，配合 iss/aud/exp/iat/nbf/nonce 与 JWKS(kid) 校验（见下节「签名算法支持」）。登出为简单版：仅清本地会话。
 
 会话为**服务端会话，持久化到磁盘**（`sessions.jsonl`，重启 DSH 不掉线，到期自动失效），由 `HttpOnly; SameSite=Lax` Cookie（`dsh_wua_session`）携带，JS 无法读取；修改密码会**吊销所有其他会话**。
 

package/index.js

@@ -387,6 +387,48 @@ async function writeCredentials(ctx, creds) {
   await ctx.fs.writeText(target, JSON.stringify(creds), undefined, undefined, { mode: 'danger-full-access' })
 }
 
+// ---------------- OIDC 身份绑定（sub 白名单） ----------------
+//
+// 语义（按部署者确认的验收标准）：
+//   - 绑定前：OIDC 登录【一律拒绝】。配置了 OIDC 只代表「允许发起授权」，
+//     不代表谁都能登录——否则任何能通过该 IdP 的人都能进 WebUI。
+//   - 绑定：本地账号登录后，在设置页点「绑定」，走一次 OIDC 授权，把回调里
+//     校验通过的 sub 存进凭据文件（boundSub）。此后只有这一个 sub 能登录。
+//   - 解绑：把 boundSub 清空，OIDC 登录立即恢复为「一律拒绝」。
+//
+// 存放位置：凭据文件 dsh-webui-auth.json 的 boundSub 字段。与 username/hash 同文件，
+// 因为它们同属「谁可以进这个 WebUI」这一件事，且该目录已是 0600。
+// 旧版凭据文件没有该字段 → 读出来是 undefined → 视为未绑定，行为即「拒绝 OIDC 登录」，
+// 这对既有部署是安全的方向（不会因为升级而放开访问）。
+
+/** 取已绑定的 sub；未绑定/非法时返回 null。 */
+function boundSubOf(creds) {
+  if (!creds || typeof creds.boundSub !== 'string') return null
+  const s = creds.boundSub
+  return s.length > 0 ? s : null
+}
+
+/** 当前是否已绑定 OIDC 身份。 */
+function isOidcBound(creds) {
+  return boundSubOf(creds) !== null
+}
+
+/**
+ * 给界面展示用的 sub 掩码。
+ *
+ * 为什么不直接用 sanitizeSub：那是「日志注入防护」——只把不安全字符换成下划线、
+ * 截断长度，内容本身照样完整可见。拿它回传前端等于把 sub 明文发给了浏览器。
+ * 界面只需要让操作者辨认「绑的是哪一个」，不需要拿到可用于构造 token 的原始标识，
+ * 因此这里保留首尾少量字符、中间打码。
+ *
+ * 极短的 sub（≤4）整串打码，避免"保留首尾"退化成几乎明文。
+ */
+function maskSubForDisplay(sub) {
+  if (typeof sub !== 'string' || !sub) return null
+  if (sub.length <= 4) return '*'.repeat(sub.length)
+  return sub.slice(0, 2) + '*'.repeat(Math.max(4, sub.length - 4)) + sub.slice(-2)
+}
+
 /**
  * 读取 OIDC 配置。优先独立文件 dsh-webui-oauth.json；不存在时回落到
  * dsh-webui-auth.json 的 oidc 段（旧版布局），实现无感升级。
@@ -2011,7 +2053,10 @@ export async function apply(ctx) {
           const oidcOn = await oidcEnabled(credsNow)
           const page = LOGIN_PAGE
             .replace('__MODE__', enabledFlag ? 'login' : 'setup')
-            .replace('__OIDC_ENABLED__', oidcOn ? 'true' : 'false')
+            // SSO 按钮的显示条件 = 已配置 OIDC **且**已绑定身份。
+            // 只判配置会让未绑定的部署显示一个点了必然被拒的按钮（oidc-not-bound），
+            // 用户会以为坏了。绑定是访问前提，按钮就该跟着绑定状态走。
+            .replace('__OIDC_ENABLED__', oidcOn && isOidcBound(credsNow) ? 'true' : 'false')
             .replace('__THEME_PREFERENCE__', themePreference(ctx))
           res.writeHead(200, {
             'content-type': 'text/html; charset=utf-8',
@@ -2179,7 +2224,21 @@ export async function apply(ctx) {
               return { trustBrowserOrigin: pol.trust, configuredOrigin: configuredOrigin(ctx) }
             } catch (e) { return null }
           })(),
-          oidc: oidcOn ? { enabled: true, issuer: oidcCfg.issuer, clientId: oidcCfg.clientId, scope: oidcCfg.scope, redirectBase: oidcCfg.redirectBase, trustBrowserOrigin: oidcCfg.trustBrowserOrigin !== false } : { enabled: false },
+          // bound/boundSubHint 供设置页展示绑定状态。
+          // 只回传 sub 的**脱敏短标识**：sub 是 IdP 侧的稳定标识符，全量回传给前端
+          // 没有功能需要（绑定只需显示"已绑定到谁"），却会把它暴露在浏览器里。
+          oidc: oidcOn
+            ? {
+                enabled: true,
+                issuer: oidcCfg.issuer,
+                clientId: oidcCfg.clientId,
+                scope: oidcCfg.scope,
+                redirectBase: oidcCfg.redirectBase,
+                trustBrowserOrigin: oidcCfg.trustBrowserOrigin !== false,
+                bound: isOidcBound(creds),
+                boundSubHint: isOidcBound(creds) ? maskSubForDisplay(boundSubOf(creds)) : null,
+              }
+            : { enabled: false, bound: isOidcBound(creds), boundSubHint: isOidcBound(creds) ? maskSubForDisplay(boundSubOf(creds)) : null },
         })
       } catch (e) {
         sendJson(res, 500, { error: e && e.message ? e.message : String(e) })
@@ -2381,7 +2440,68 @@ export async function apply(ctx) {
 
   // ---------------- OIDC SSO 端点 ----------------
 
-  // 发起 OIDC 授权：GET /dsh-webui-oauth/oidc/login?base=<前端origin>
+  /**
+   * 发起一次 OIDC 授权往返，302 到 IdP。登录与绑定共用（唯一区别是 purpose）。
+   *
+   * purpose 会随 state 一起暂存，回调据此决定这是"登录"还是"绑定"：
+   *   - 'login'：校验 sub 必须等于已绑定值，否则拒绝；
+   *   - 'bind' ：把校验通过的 sub 写入 boundSub。
+   * 把用途放在服务端 state 表里而不是 query 参数：query 由浏览器可控，
+   * 若能通过改 URL 把绑定流程变成登录流程，绑定就形同虚设。
+   *
+   * @returns {Promise<void>} 直接写响应，不返回内容
+   */
+  async function startOidcAuthorize(ctx2, req, res, purpose) {
+    const creds = await readCredentials(ctx2)
+    const o = await oidcOf(creds)
+    if (!(await oidcEnabled(creds))) {
+      sendJson(res, 200, { ok: false, error: 'oidc-not-configured' })
+      return
+    }
+    // 决定回调 base：与登录后 token 跳转共用 remote-web-ui 段的统一开关。
+    let frontendBase = null
+    if (typeof req.url === 'string') {
+      const m = /[?&]base=([^&]+)/.exec(req.url)
+      if (m) { try { frontendBase = decodeURIComponent(m[1]) } catch (e) { frontendBase = null } }
+    }
+    const base = resolveOidcBase(o, frontendBase, trustedOriginPolicy(ctx2, o))
+    if (!base) {
+      sendJson(res, 200, { ok: false, error: 'oidc-base-unresolvable', hint: '请在设置中配置 redirectBase（反代场景），或让浏览器从登录页发起 SSO 登录' })
+      return
+    }
+    const redirectUri = base.replace(/\/$/, '') + OIDC_CALLBACK_PATH
+    // 拉取 Discovery（缓存）；失败则引导检查 issuer 配置。
+    const disc = await oidcDiscovery.get(o.issuer)
+    if (!disc.ok || !disc.metadata) {
+      const meta = requestMeta(req)
+      await auditLog(ctx2, 'oidc_discovery_failure', { issuer: o.issuer, ip: meta.ip, ua: meta.ua, detail: disc.error })
+      sendJson(res, 200, { ok: false, error: 'oidc-discovery-failed', detail: disc.error })
+      return
+    }
+    // 生成 state / nonce / PKCE verifier，按 TTL 暂存（含容量上限，防灌爆）。
+    const state = oidcRandom(24)
+    const nonce = oidcRandom(24)
+    const verifier = oidcRandom(32)
+    oidcStateStore.put(state, { nonce, verifier, redirectUri, purpose })
+    const authUrl = new URL(disc.metadata.authorization_endpoint)
+    authUrl.searchParams.set('response_type', 'code')
+    authUrl.searchParams.set('client_id', o.clientId)
+    authUrl.searchParams.set('redirect_uri', redirectUri)
+    authUrl.searchParams.set('scope', typeof o.scope === 'string' && o.scope.trim() ? o.scope.trim() : 'openid profile email')
+    authUrl.searchParams.set('state', state)
+    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')
+    // 登录 CSRF 绑定：把 state 同时写进一个 HttpOnly 短时效 Cookie。回调时两者必须
+    // 同时匹配——否则攻击者可先在自己的浏览器发起授权拿到 state，再诱导受害者带着
+    // 该 state 完成回调，把受害者的浏览器登录进攻击者的账号（会话固定/登录 CSRF）。
+    res.setHeader('Set-Cookie', COOKIE_OIDC_STATE + '=' + state + '; HttpOnly; SameSite=Lax; Path=/; Max-Age=' + Math.floor(OIDC_STATE_TTL_MS / 1000))
+    res.writeHead(302, { location: authUrl.href })
+    res.end()
+  }
+
+  // 发起 OIDC 登录授权：GET /dsh-webui-oauth/oidc/login?base=<前端origin>
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-webui-oauth/oidc/login',
@@ -2391,58 +2511,88 @@ export async function apply(ctx) {
           sendJson(res, 405, { error: '仅支持 GET' })
           return
         }
-        const creds = await readCredentials(ctx)
-        const o = await oidcOf(creds)
-        if (!(await oidcEnabled(creds))) {
-          sendJson(res, 200, { ok: false, error: 'oidc-not-configured' })
+        // 未绑定任何 sub 时不允许发起登录：绑定是访问前提，先挡在最前面，
+        // 免得用户走完整个 IdP 往返才被拒（体验差且浪费一次授权）。
+        const creds0 = await readCredentials(ctx)
+        if (!isOidcBound(creds0)) {
+          sendJson(res, 200, { ok: false, error: 'oidc-not-bound', hint: '请先用本地账号登录，在设置页「身份认证」中绑定 OIDC 身份' })
           return
         }
-        // 决定回调 base：与登录后 token 跳转共用 remote-web-ui 段的统一开关。
-        let frontendBase = null
-        if (typeof req.url === 'string') {
-          const m = /[?&]base=([^&]+)/.exec(req.url)
-          if (m) { try { frontendBase = decodeURIComponent(m[1]) } catch (e) { frontendBase = null } }
+        await startOidcAuthorize(ctx, req, res, 'login')
+      } catch (e) {
+        sendJson(res, 500, { error: e && e.message ? e.message : String(e) })
+      }
+    },
+  }), 'dsh-webui-oauth: oidc login')
+
+  // 发起 OIDC 绑定授权：GET /dsh-webui-oauth/oidc/bind
+  //
+  // 必须先持有有效的本地会话（已登录）——绑定语义是"把我这个管理员账号
+  // 与某个 IdP 身份关联起来"，不能让未认证者触发。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-webui-oauth/oidc/bind',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          sendJson(res, 405, { error: '仅支持 GET' })
+          return
         }
-        const base = resolveOidcBase(o, frontendBase, trustedOriginPolicy(ctx, o))
-        if (!base) {
-          sendJson(res, 200, { ok: false, error: 'oidc-base-unresolvable', hint: '请在设置中配置 redirectBase（反代场景），或让浏览器从登录页发起 SSO 登录' })
+        if (!checkRequest(req)) {
+          sendJson(res, 401, { error: 'unauthorized' })
           return
         }
-        const redirectUri = base.replace(/\/$/, '') + OIDC_CALLBACK_PATH
-        // 拉取 Discovery（缓存）；失败则引导检查 issuer 配置。
-        const disc = await oidcDiscovery.get(o.issuer)
-        if (!disc.ok || !disc.metadata) {
-          const meta = requestMeta(req)
-          await auditLog(ctx, 'oidc_discovery_failure', { issuer: o.issuer, ip: meta.ip, ua: meta.ua, detail: disc.error })
-          sendJson(res, 200, { ok: false, error: 'oidc-discovery-failed', detail: disc.error })
+        await startOidcAuthorize(ctx, req, res, 'bind')
+      } catch (e) {
+        sendJson(res, 500, { error: e && e.message ? e.message : String(e) })
+      }
+    },
+  }), 'dsh-webui-oauth: oidc bind')
+
+  // 解除 OIDC 绑定：POST /dsh-webui-oauth/oidc/unbind
+  //
+  // 清空 boundSub 后，OIDC 登录立即回到"一律拒绝"（见回调里的 bound 判空）。
+  // 需要当前密码，避免会话被盗后攻击者悄悄解绑（解绑本身是安全降级操作，
+  // 但仍属于"改认证配置"，与 disable/configure 保持一致的验证强度）。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-webui-oauth/oidc/unbind',
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: '仅支持 POST' })
           return
         }
-        // 生成 state / nonce / PKCE verifier，按 TTL 暂存（含容量上限，防灌爆）。
-        const state = oidcRandom(24)
-        const nonce = oidcRandom(24)
-        const verifier = oidcRandom(32)
-        oidcStateStore.put(state, { nonce, verifier, redirectUri })
-        const authUrl = new URL(disc.metadata.authorization_endpoint)
-        authUrl.searchParams.set('response_type', 'code')
-        authUrl.searchParams.set('client_id', o.clientId)
-        authUrl.searchParams.set('redirect_uri', redirectUri)
-        authUrl.searchParams.set('scope', typeof o.scope === 'string' && o.scope.trim() ? o.scope.trim() : 'openid profile email')
-        authUrl.searchParams.set('state', state)
-        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')
-        // 登录 CSRF 绑定：把 state 同时写进一个 HttpOnly 短时效 Cookie。回调时两者必须
-        // 同时匹配——否则攻击者可先在自己的浏览器发起授权拿到 state，再诱导受害者带着
-        // 该 state 完成回调，把受害者的浏览器登录进攻击者的账号（会话固定/登录 CSRF）。
-        res.setHeader('Set-Cookie', COOKIE_OIDC_STATE + '=' + state + '; HttpOnly; SameSite=Lax; Path=/; Max-Age=' + Math.floor(OIDC_STATE_TTL_MS / 1000))
-        res.writeHead(302, { location: authUrl.href })
-        res.end()
+        if (!checkRequest(req)) {
+          sendJson(res, 401, { error: 'unauthorized' })
+          return
+        }
+        const body = await readJsonBody(req, res)
+        if (body === null) return
+        const creds = await readCredentials(ctx)
+        const meta = requestMeta(req)
+        const current = String(body.current || '')
+        const curValid = current && creds && typeof creds.hash === 'string' && await verifyPassword(current, creds.hash)
+        if (!curValid) {
+          await auditLog(ctx, 'oidc_unbind_failure', { username: creds && creds.username ? creds.username : null, ip: meta.ip, ua: meta.ua, detail: '当前密码不正确' })
+          sendJson(res, 200, { ok: false, error: 'current-invalid' })
+          return
+        }
+        if (!isOidcBound(creds)) {
+          sendJson(res, 200, { ok: true, bound: false, alreadyUnbound: true })
+          return
+        }
+        // 只删 boundSub，其余字段原样保留。
+        const next = { ...creds }
+        delete next.boundSub
+        await writeCredentials(ctx, next)
+        await auditLog(ctx, 'oidc_unbind_success', { username: creds.username, ip: meta.ip, ua: meta.ua })
+        sendJson(res, 200, { ok: true, bound: false })
       } catch (e) {
         sendJson(res, 500, { error: e && e.message ? e.message : String(e) })
       }
     },
-  }), 'dsh-webui-oauth: oidc login')
+  }), 'dsh-webui-oauth: oidc unbind')
 
   // OIDC 回调：GET /dsh-webui-oauth/oidc/callback?code&state
   ctx.effect(() => ctx.webServer.register({
@@ -2550,10 +2700,37 @@ export async function apply(ctx) {
           sendJson(res, 200, { ok: false, error: 'oidc-invalid-id-token', detail: vres.error })
           return
         }
-        // 建本地会话。身份用**原始 sub**（sanitize 是有损的：'a/b' 与 'a_b' 会塌成同一个
-        // 本地用户名，拿它当身份会张冠李戴）；审计里才用 sanitizeSub 过滤后的短标识。
         const rawSub = vres.payload.sub
         const auditName = sanitizeSub(rawSub)
+
+        // 用途分支：绑定 vs 登录。purpose 来自服务端 state 表（见 startOidcAuthorize），
+        // 浏览器无法通过改 URL 把绑定流程降级成登录流程。
+        if (st.purpose === 'bind') {
+          // 绑定：把本次校验通过的 sub 记进凭据文件。
+          // 保留原有 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)
+          return
+        }
+
+        // 登录：sub 必须与已绑定值完全一致，否则拒绝。
+        // 这一步是访问控制的核心——没有它，任何能通过该 IdP 的人都能进 WebUI。
+        // 用恒定时间比较，避免通过响应时间侧信道逐字节猜出 boundSub。
+        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)
+          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)
+          return
+        }
+
+        // 建本地会话。身份用**原始 sub**（sanitize 是有损的：'a/b' 与 'a_b' 会塌成同一个
+        // 本地用户名，拿它当身份会张冠李戴）；审计里才用 sanitizeSub 过滤后的短标识。
         const s = createSession(rawSub, ttlOf(creds))
         await auditLog(ctx, 'oidc_login_success', { username: auditName, ip: meta.ip, ua: meta.ua })
         // 授权往返结束：同时下发会话 Cookie 并清除一次性的 state 绑定 Cookie。

package/lib/client.js

@@ -80,6 +80,12 @@ window.__ModuleLoader__.load({
 				const [oidcScope, setOidcScope] = react.useState('openid profile email');
 				const [oidcRedirectBase, setOidcRedirectBase] = react.useState('');
 				const [oidcTrustBrowser, setOidcTrustBrowser] = react.useState(true);
+				// 绑定状态：bound 表示已绑定某个 IdP 身份；boundSubHint 是掩码后的展示值
+				// （服务端只回传掩码，前端拿不到 sub 明文，也不应该拿）。
+				const [oidcBound, setOidcBound] = react.useState(false);
+				const [oidcBoundHint, setOidcBoundHint] = react.useState('');
+				const [unbindPw, setUnbindPw] = react.useState('');
+				const [bindMsg, setBindMsg] = react.useState(null);
 
 				react.useEffect(() => {
 					let alive = true;
@@ -99,6 +105,8 @@ window.__ModuleLoader__.load({
 							setOidcClientId((o && o.clientId) || '');
 							if (o && o.scope) setOidcScope(o.scope);
 							if (o && o.redirectBase) setOidcRedirectBase(o.redirectBase);
+							setOidcBound(!!(o && o.bound));
+							setOidcBoundHint((o && o.boundSubHint) || '');
 						}
 					});
 					load();
@@ -215,6 +223,45 @@ window.__ModuleLoader__.load({
 					});
 				};
 
+				// 绑定：先发起服务端授权往返，IdP 校验通过后由回调把 sub 落库。
+				// 这里不直接调 API 拿 sub——那样等于让浏览器自报身份，毫无安全意义。
+				const onBind = () => {
+					if (busy) return;
+					setBindMsg(null);
+					// base 用当前页面的 origin：反代部署下浏览器看到的才是对外地址。
+					const base = location.origin || '';
+					location.href = '/dsh-webui-oauth/oidc/bind' + (base ? '?base=' + encodeURIComponent(base) : '');
+				};
+
+				const onUnbind = () => {
+					if (busy) return;
+					if (!unbindPw) {
+						setBindMsg({ kind: 'err', text: '请输入当前密码以解除绑定' });
+						return;
+					}
+					setBusy(true);
+					setBindMsg(null);
+					api('/dsh-webui-oauth/oidc/unbind', { current: unbindPw }).then((r) => {
+						setBusy(false);
+						if (r && r.ok) {
+							setUnbindPw('');
+							setOidcBound(false);
+							setOidcBoundHint('');
+							setBindMsg({ kind: 'ok', text: '已解除绑定。此后 OIDC 登录将被拒绝，直到重新绑定。' });
+							api('/dsh-webui-oauth/status').then((s) => {
+								if (s && !s.error) setStatus(s);
+							}).catch(() => {});
+						} else if (r && r.error === 'current-invalid') {
+							setBindMsg({ kind: 'err', text: '当前密码不正确' });
+						} else {
+							setBindMsg({ kind: 'err', text: '解绑失败：' + ((r && r.error) || '未知错误') });
+						}
+					}).catch(() => {
+						setBusy(false);
+						setBindMsg({ kind: 'err', text: '解绑失败：无法连接认证服务' });
+					});
+				};
+
 				const onLogout = () => {
 					if (busy) return;
 					setBusy(true);
@@ -360,6 +407,34 @@ window.__ModuleLoader__.load({
 								' 信任浏览器 origin（默认开启；关闭时仅用上方 Redirect Base）'),
 						),
 					) : null,
+					// ---- OIDC 身份绑定 ----
+					// 绑定是访问控制前提：未绑定时任何能通过该 IdP 的人都会被拒，
+					// 登录页也不会显示 SSO 按钮。因此这块独立于"是否勾选启用"，
+					// 只要 OIDC 已配置就展示当前绑定状态。
+					oidcEnabled ? react.createElement('div', { className: 'wua-section' },
+						react.createElement('label', { className: 'wua-label' }, 'OIDC 身份绑定'),
+						oidcBound
+							? react.createElement('p', { className: 'wua-intro' },
+								'当前已绑定身份：', react.createElement('code', null, oidcBoundHint || '（已绑定）'),
+								'。只有该身份可通过 SSO 登录。')
+							: react.createElement('p', { className: 'wua-warn' },
+								'尚未绑定任何 OIDC 身份。此时 OIDC 登录一律被拒绝，登录页也不会显示 SSO 按钮。请先保存上方配置，再点击「绑定 OIDC 身份」并完成一次 IdP 登录。'),
+						oidcBound
+							? react.createElement('div', { className: 'wua-row' },
+								react.createElement('label', { className: 'wua-label' }, '当前密码（解除绑定需验证）'),
+								react.createElement('input', { className: 'wua-input', type: 'password', value: unbindPw, autoComplete: 'current-password', onChange: (e) => setUnbindPw(e.target.value) }),
+							)
+							: null,
+						react.createElement('div', { className: 'wua-btnrow' },
+							oidcBound
+								? react.createElement('button', { className: 'wua-btn ghost', disabled: busy || status === null, onClick: onUnbind }, '解除绑定')
+								: react.createElement('button', { className: 'wua-btn', disabled: busy || status === null, onClick: onBind }, '绑定 OIDC 身份'),
+							oidcBound
+								? react.createElement('button', { className: 'wua-btn ghost', disabled: busy || status === null, onClick: onBind }, '重新绑定其他身份')
+								: null,
+						),
+						bindMsg ? react.createElement('p', { className: bindMsg.kind === 'ok' ? 'wua-msg' : 'wua-err' }, bindMsg.text) : null,
+					) : null,
 					react.createElement('div', { className: 'wua-btnrow' },
 						react.createElement('button', { className: 'wua-btn', disabled: busy || status === null, onClick: onSave },
 							busy ? '保存中…' : '保存账号密码'),

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-webui-oauth",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/client-bundle-id.test.mjs && node test/displace-original.test.mjs"
+    "test": "node test/redirect-scheme.test.mjs && node test/proxy-host.test.mjs && node test/trusted-origin.test.mjs && node test/oidc.test.mjs && node test/oidc-state-ttl.test.mjs && node test/set-cookie-multi.test.mjs && node test/oidc-integration.test.mjs && node test/oidc-config-store.test.mjs && node test/adopt-data-dir.test.mjs && node test/oidc-ec.test.mjs && node test/jwks-refresh.test.mjs && node test/oidc-bind.test.mjs && node test/client-bundle-id.test.mjs && node test/displace-original.test.mjs"
   },
   "exports": {
     ".": "./index.js",