KernLab.Claim 宿主使用指南(kernlab-claim)
1. 定位
kernlab-claim 是 KernLab.Claim 的独立部署宿主——统一认证中心的产品形态(对标 IdentityServer4 /
Keycloak 的生态位):验证身份、签发身份声明(JWT)、供全平台消费。单进程内嵌 OIDC 端点、管理 CLI、
管理控制台(/ui/)、审计与指标;存储挂 TierKv 单机档。
配套包:引擎 KernLab.Claim(嵌入式复用)、
SDK KernLab.Claim.Client(消费方接入,
见 RP 接入指南)。
2. 快速上手
# 开发形态:无 data-dir = 内存卷 + 无种子 = 自动生成 dev-admin(secret 打控制台,kernlab.claim.admin 全量)
dotnet run --project src/KernLab.Claim.Server
# 生产形态:虚拟卷(缺省介质)+ 种子客户端文件
dotnet run --project src/KernLab.Claim.Server -- --data-dir /data/claim --urls http://+:8080
- 打开
http://<host>:<port>/ui/进管理控制台(首次用 dev-admin secret 取管理令牌走 CLI 建管理员, 见 §5.2); - RP(应用)接入见 Client 包内《RP 接入指南》(docs/rp-integration.md)。
3. 概念与术语
| 术语 | 含义 |
|---|---|
| FS 根域 | 一个程序(进程)一个 FS 根域:TierFs 单实例,全部存储引擎(KV/审计时序)皆挂根域内部、各占目录域。磁盘卷 Exclusive 挂载/虚拟卷排他内建——卷锁守单写者 |
| 介质 = spec | memory:(内存卷)/ virtual:///…/claim.tier(单工件虚拟卷——缺省推荐:自持一致性+内建跨进程锁)/ local:///dir(可视化目录卷)——切介质不改代码(--fs 配置化) |
| 单机档 / 集群档 | --store tier(缺省,TierKv 内嵌)/ --store synod(Raft 多副本——多写者/无状态形态) |
| 会话(SSO) | Claim 侧浏览器会话(claim_sid cookie):命中未过期会话的 authorize 免登录发码;登出链式通知全部已发码 RP |
| 恢复码 | MFA enrol 随发 8 枚一次性码(TOTP 不可用时替代动态码,消费即删) |
| passkey | WebAuthn 第二因子(WP12——指纹/安全钥匙;登录三选一序 passkey > TOTP > 恢复码;signCount 克隆检测自动禁用) |
| 外部 IdP 联邦 | 外部 OIDC 上游登录(WP13——单上游;admin 预绑定起步,联邦后默认仍过本域第二因子) |
| 卷锁单写者 | 宿主进程 = 卷唯一写者;第二进程开卷(含 CLI)显式失败——管理写走运行中宿主 HTTP 桥 |
4. 怎么选
| 场景 | 选择 |
|---|---|
| 本地开发/测试 | 不带 --data-dir(内存卷,重启即清) |
| 单机生产 | --data-dir <绝对路径>(缺省 --fs virtual——单工件 claim.tier,自持一致性+跨进程锁) |
| 运维需要直接翻目录 | --fs local(可视化目录卷;Exclusive 卷锁同效) |
| 多写者 / 无状态多副本 / 集群 | 集群档(Synod)暂离本发布——待 KernLab.Synod.Client alpha.3 回归(kernlab-synod#6 相关) |
5. 怎么用
5.1 启动参数(全局选项,宿主与 CLI 通用)
| 参数 | 缺省 | 说明 |
|---|---|---|
--data-dir <dir> |
空 | 数据根(绝对路径——相对路径解析分叉禁用);空 = 内存形态 |
--fs virtual\|local\|memory |
virtual | FS 介质(§4) |
--urls <u> |
ephemeral 回环 | 监听地址(容器传 http://+:8080) |
--store tier\|synod |
tier | 存储档 |
--issuer <u> |
http://localhost:7630 | 签发者(discovery iss 与 JWT iss 同源;启动后回填绑定地址) |
--access-ttl <s> / --node-ttl <d> |
900 / 30 | access 寿命(契约 ≤15min)/ 节点 token 寿命(C3) |
--password-min-length <n> / --lockout-minutes <n> / --login-failure-threshold <n> |
10 / 30 / 5 | 口令策略与防爆破 |
--audit-retention-days <n> |
365 | 审计留存(TierTimeSeries 留存轮) |
--memory |
— | 等价「去 data-dir」 |
--synod-target/--synod-peer/--synod-token/--synod-prefix |
— | 集群档装配 |
种子客户端:<data-dir>/clients.json(JSON 数组——ClientId/Secret/Scopes/RedirectUris/GrantTypes/
Kind/Tenant/Environment;secret 明文仅启动期存在,入库即 PBKDF2)。
5.2 管理面三入口(同一命令模型,零漂移)
- CLI(宿主停机时——卷锁单写者):
kernlab-claim <组> <命令>; - HTTP 桥(宿主运行时——
/claim/{**path},Bearer + kernlab.claim.admin):读 GET、写 POST, 位置参数走路由段、选项走 query; - 控制台
/ui/(浏览器会话 + admin 角色)。
命令树:
claim status 客户端/用户/会话/撤销计数
claim client add|list|show|update|disable|enable|rotate-secret|remove
(add/rotate 的 secret 一次性明文返回;list 支持 --ten/--env;禁用=签发即拒;
--public true = 公共客户端——免 secret,仅限设备授权流准入)
claim user add|list|show|disable|enable|reset-password|set-roles|set-scopes|set-email|enrol-totp
(set-email = 绑定/变更邮箱——唯一索引 NX 抢占,撞占用即拒;变更即清 EmailVerified)
claim user webauthn-list|webauthn-revoke passkey 凭证清单/撤销(WP12 admin 兜底;--cred 哈希 或 --all)
claim user idp-link|idp-unlink 联邦身份绑定/解绑(WP13——--issuer --sub;索引 NX 恰一撞绑拒)
claim session list|logout 会话列表 + 强制下线(链式撤销)
claim token revoke-jti|revoke-refresh|list-revoked 撤销管理
claim audit query 审计查询(--from/--to/--limit/--subject/--action)
claim keyset rotate|list 签名密钥轮换(双 key 宽限)
claim settings get|set 运行期旋钮(口令/防爆破/会话 + mail.*/account.* + ratelimit.* + webauthn.rp-id + idp.* + otel.*/metrics.* 组,保存即生效)
claim mail test --to <addr> SMTP 配置自检(真发一封测试邮件)
kernlab-claim migrate export|import 单机档 ↔ 集群档快照迁移(JSON 中间格式)
管理员引导(生产):宿主停机时 kernlab-claim user add admin --password <pw> --roles admin;
宿主运行时走 HTTP 桥(dev-admin secret 或既有 admin 会话)。协议与 SDK 面全链联验:
ConsumerAcceptance 验收工具随仓交付(四场景 × 消费方角色,一键自验)。
5.3 协议端点(RP 消费面——完整指南见 Client 包《RP 接入指南》)
authorize / token(四流)/ userinfo / introspect / revocation / logout / discovery / jwks。 管理面强制内省(C4);消费方验签必带 aud(SDK 编译期强制)。
5.4 账户自助与邮件面(WP7)
账户自助三件套 = 注册 / 邮箱验证 / 找回口令,UI 公开区四屏(/ui/register、/ui/verify、
/ui/forgot、/ui/reset)+ 端点面 /ui/account/*(bootstrap 透出旋钮并发放 CSRF;verify/reset
以邮件令牌为凭证免 CSRF)。
- 开关:
settings set account.self-register true|false(缺省关——admin 建户模式不变);settings set mail.enabled true|false(缺省关——关闭时找回/注册呈 503 统一文案,不假发送)。 - SMTP 配置(settings 运行期旋钮,改完即生效):
mail.host / mail.port / mail.tls(none|starttls|implicit) / mail.from / mail.user / mail.pass / mail.public-base-url。mail.pass落库即 KEK 密文 (CLAIM_KEK,同私钥加密),查询面只答(configured);mail.public-base-url空则邮件链接用--issuer(反代终止 TLS 时显式配置)。配置自检:claim mail test --to <addr>。 - 流程语义:注册即建户但禁登(
Activated=false,登录呈"邮箱未验证")——验证链接(24h) 激活并置email_verified;找回链接(30min)重置口令并连坐撤销全部会话与 refresh(同 admin reset-password)。防枚举:注册撞邮箱占用与成功同文案静默不发信;找回恒统一响应。 自研最小 SMTP 客户端(EHLO/STARTTLS/AUTH LOGIN/DATA;正文 base64;地址/主题含换行即拒发—— 头注入 fail-closed 红线)。 - 存量用户语义:WP7 前建档无邮箱索引——
user set-email(或自助注册)首次落邮箱时才建users-by-email唯一索引;此前的档仍可按用户名走找回。
5.5 设备授权流(RFC 8622,WP9)
面向 TV / CLI / IoT 等无浏览器输入形态:
# 设备端:发起(confidential 凭证或 public client_id——--public true 客户端免 secret)
curl -X POST $CLAIM/connect/deviceauthorize -d client_id=dev-cli -d client_secret=*** -d scope="openid offline_access"
# → {"device_code","user_code","verification_uri":"$CLAIM/ui/device","verification_uri_complete","expires_in":600,"interval":5}
# 设备端轮询 /connect/token(grant_type=urn:ietf:params:oauth:grant-type:device_code):
# authorization_pending → 继续轮询;slow_down → interval 步进 +5s;
# access_denied → 用户拒绝;expired_token → 重新发起;200 → 交付(单次取走)
# 用户端:浏览器打开 verification_uri → 输设备码 → 登录(SSO 命中免登)→ 确认/拒绝(scope 透明展示)
- 公共客户端(public client):
claim client add ... --grants urn:ietf:params:oauth:grant-type:device_code --public true—— 免 secret 但仅限设备授权流准入(其余 grant 仍强制凭证,★26)。 - 设备码 600s 寿命、轮询节拍 5s 起步(服务端按节拍回 slow_down 并步进);user_code 8 字符无歧义表
(输码限速
ratelimit.device-usercode维——爆破防线)。
5.6 令牌面限流(WP10)
固定窗计数(TierKv 限流域——CAS 递增,争用降级放行,限流器故障不化为全拒);client_id 与来源 IP
双维独立计数,任一超限即 429 + Retry-After;与登录路径防爆破锁定并行不互替。
settings 旋钮(ratelimit.<dim>.per-minute,0 = 维度关闭;保存即生效):
| dim | 缺省 | 说明 |
|---|---|---|
token |
60/min | /connect/token 各 grant(client 维 + IP 维) |
introspect / revocation |
120/min | 内省 / 撤销 |
deviceauthorize |
30/min | 设备流发起 |
device-poll |
30/min | 设备轮询洪泛——超限回 slow_down(非 429,RFC 8628 §3.5 形态) |
device-usercode |
10/min/IP | 确认页输码(user_code 爆破防线) |
forgot / resend / register |
3/min/IP | 账户自助面 |
反代场景:ratelimit.trusted-proxy-count(0–8——X-Forwarded-For 从右取第 N 跳;0 = 直连 RemoteIp)。
5.7 DPoP(RFC 9449——sender-constrained,WP11)
proof 携带即绑定(可选升级);client add|update --require-dpop true = 强制档(无 proof 拒发
401 + WWW-Authenticate: DPoP algs="ES256")。四 grant(client_credentials / authorization_code /
refresh / device)全支持:
- 绑定语义:access token 签发嵌
cnf.jkt(proof 公钥 RFC 7638 拇印);refresh 轮换强制同 jkt (不符 = invalid_grant——绑定跟随 refresh 全生命周期);userinfo 以Authorization: DPoPscheme + 同键 proof(携ath)消费——Bearer 携绑定令牌即拒。 - proof 矩阵(宿主与资源方共用核心包
DpopProofValidator):typ=dpop+jwt / alg=ES256 白名单 / jwk 含私钥材料即拒(对抗锁定)/ htm-htu(剥 query·fragment)/ iat ±60s / jti 单次(NX 域 TTL 120s)/ ath 绑 access token。错误恒invalid_dpop_proof;服务端 nonce 不作起步档(★22——jti 窗口兜底)。 - discovery 广告
dpop_signing_alg_values_supported: ["ES256"];审计dpop.fail+ 指标claim_dpop_failures_total。
5.8 MFA 与第二因子(TOTP + passkey)
TOTP:claim user enrol-totp <user> → 响应一次性返回 Base32 密钥(authenticator 扫码/手录)+
8 枚一次性恢复码;该用户此后登录强制第二因子,动态码不可用时以恢复码替代(每枚一次,消费即删)。
passkey(WebAuthn 第二因子,WP12):用户自助在 /ui/security(控制台用户菜单「安全设置」)
注册;登录三选一缺省序 passkey > TOTP > 恢复码(密码通过后无 otp 则发 passkey 挑战,
otp 在位 = 显式选择 TOTP/恢复码路径)。admin 兜底:claim user webauthn-list <user> /
webauthn-revoke <user> --all|--cred <哈希>。
- 零依赖自研:CBOR 解码器(RFC 8949 子集)+ COSE key(ES256/RS256)+ authenticatorData 解析 + attestation none/packed 自证(x5c 信任链不收——★23);challenge 单次 CAS(3min)。
- 克隆检测:signCount CAS 递增;回退(count ≤ 存值且非恒 0)= 凭证自动禁用 +
审计
webauthn.clone-suspect(TOTP/恢复码仍可用——第二因子不至全锁)。 - origin/rpId:origin =
mail.public-base-url缺省--issuer(★29 单点取值);rpId 缺省取 origin host,反代多域名可用settings set webauthn.rp-id <域>显式锚定。 - 对抗面:challenge 重放 / origin / rpId 混淆 / signCount 回退全拒(E2E 锁定)。
5.9 密钥与加密
- 签名密钥环持久化于根域(keys/signing 目录域),
claim keyset rotate双 key 宽限轮换,JWKS 自动可见; - 私钥静态加密:env
CLAIM_KEK(AES-GCM;未配置 = 明文形态——仅限开发)。
5.10 集群档(暂离发布面)
Synod 集群档(--store synod,Raft 多副本共享逻辑地址空间)自 1.0.0-alpha.2 暂离发布面——
待 KernLab.Synod.Client alpha.3 nuget 修复后回归(迁移工具 migrate export|import 保留,
单机档数据可先行导出)。节点 token(typ=node,长寿 30d + 内省撤销)不受影响。
5.11 Docker
docker run -p 8080:8080 -v /data/claim:/data ghcr.io/kernlab-dev/kernlab-claim:v1.0.0-alpha.2 \
--data-dir /data --urls http://+:8080
镜像 tag = 版本(正式线另浮 latest);更新日志见仓 CHANGELOG 对应版本段。
5.12 健康与指标
/healthz(存活,免鉴权)、/readyz(store 可读)、/metrics(Prometheus 文本,claim_* 家族计数)。
抓取形态三档(★27):settings set metrics.expose admin|readonly|public(缺省 admin = Bearer +
kernlab.claim.admin 现状);readonly = 独立抓取凭据(settings set metrics.readonly-token <值>,
Bearer 逐字对照恒时比较,落库 KEK 密文);public = 免鉴权(内网抓取网关自担边界)。
5.13 外部 IdP 联邦(WP13)
单上游 OIDC 联邦(登录页「使用 {name} 登录」按钮 + /connect/idp-login → 上游 authorize →
/connect/idp-callback 回调链)。账户解析纪律(R2 受管模型延续):admin 预绑定起步——
claim user idp-link <user> --issuer <上游iss> --sub <上游sub> [--email <快照>];
未绑定 = 拒登页明示(审计 idp.reject)。
# 配置(settings 白名单组——保存即生效;四要素齐 = 端点生效 + 登录页按钮渲染)
claim settings set idp.name "公司 SSO"
claim settings set idp.issuer https://sso.corp.example # 上游 iss(discovery 基址)
claim settings set idp.client-id claim-rp
claim settings set idp.client-secret *** # 落库 KEK 密文(同 mail.pass)
# 选配:idp.scopes(缺省 "openid profile email")/ idp.allowed-algs(缺省 ES256,RS256)
# idp.redirect-base(空 = iss)/ idp.auto-provision / idp.mfa-bypass(均缺省关,★24)
- 三防:state(5min 单次 CAS,重放拒)+ nonce(ID token 回填校验)+ PKCE S256;上游 discovery 自发现端点(5min 缓存)+ JWKS 拉取缓存(kid 未命中刷新重验一次)。
- 验签白名单独立于本域:本域签发恒 ES256 红线不动;上游 ID token 验签 alg 按上游配置 (缺省 ES256,RS256——上游生态 RS256 为主,约束对象不同非红线破例)。
- MFA 叠加(★24 缺省关):已 enrol 本域第二因子的用户联邦后仍要求本域 TOTP/恢复码
(
/ui/idp-mfa服务端页);idp.auto-provision true= 未绑定按 email 承袭建户 (EmailVerified 承袭上游)。解绑:claim user idp-unlink <user> --issuer <iss> [--sub <sub>]。 - 审计
idp.login/idp.reject/idp.link/idp.unlink;指标claim_idp_logins_total{result}。
5.14 可观测(OpenTelemetry,WP14)
- trace:
settings set otel.endpoint <OTLP/HTTP 收集器基址>(空 = 关,缺省关)开启—— span 面 = 端点层(claim.http <method> <path>,协议面 + /ui/* + 管理桥统一一层)+ store 端口装饰器(claim.store.<op>,零业务代码侵入)+claim.mail.send+claim.idp.exchange; W3C traceparent 透传 back-channel logout 与上游 IdP 出站请求。 导出 = 自研 OTLP/HTTP JSON(POST{endpoint}/v1/traces);批量 5s / 256 条触发; 有界队列 1024 满即丢(指标claim_otlp_dropped_total)——观测出站不反压主链。otel.headers("k=v,k2=v2",collector 鉴权)/otel.sample-ratio(0–1,缺省 1 恒采样)。 - 指标扩充:
claim_webauthn_enrols_total/claim_webauthn_failures_total/claim_webauthn_clone_suspects_total/claim_idp_logins_total{result}/claim_otlp_dropped_total。
6. 反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 宿主运行中跑 CLI/migrate 写数据 | FS 卷锁单写者——第二开卷显式失败;绕锁并发曾损坏审计时序 | 管理写走 HTTP 桥;CLI/migrate 限停机 |
--data-dir 用相对路径 |
路径解析随进程 cwd 分叉(种子与宿主各开一卷的实证) | 一律绝对路径 |
| 直接杀进程当停机手段 | checkpoint 间隔(30s)之外的尾部未落盘 | 优雅停机(SIGTERM/Ctrl+C——Dispose 全量落盘);硬杀丢尾巴 ≤30s 属契约 |
| 修改已发布包的元数据预期 | nuget.org 元数据已发布版本不可改 | 迁移赶在下版前(RELEASE.md) |
| 密钥明文进聊天/附件 | 视同泄露,立即轮换 | env / GitHub Secrets(§凭据纪律) |
邮件面开而 CLAIM_KEK 未注入 |
mail.pass 以明文落 settings 键域(v1kek: 密文形态失效) |
先注入 KEK 再配 mail.pass |
| 自助注册开而不配邮件面 | 用户建户即卡死在"邮箱未验证"(激活链路不可达) | 先 mail.* 配齐并 claim mail test 自检,再开 account.self-register |
| 反代后不限流先配 trusted-proxy-count | X-Forwarded-For 未信任 = 全部计到反代 IP——一损俱损 | ratelimit.trusted-proxy-count 按真实代理层数配置 |
IdP 联邦开了 idp.issuer 但 RP 侧回调基址反代终止 TLS |
上游 redirect_uri 与外露基址不符 = 上游 authorize 直接拒 | idp.redirect-base 显式配外露基址(空 = --issuer,★29 同源) |
otel.endpoint 指向不可达收集器还开恒采样 |
队列满即丢 + claim_otlp_dropped_total 持涨——观测空转 |
先验收集器可达(/v1/traces 连通),再开采样 |