Table of Contents

KernLab.Claim RP 接入指南

读者:要把登录/鉴权切到 KernLab.Claim 的应用(RP——依赖方:控制台、业务服务、节点)。 本指南是任何应用接入 Claim 的标准基准(与具体技术栈、业务无关)。

1. 定位

KernLab.Claim 是统一认证中心:验证身份、签发身份声明(JWT),供全平台消费。RP 接入只做三件事—— 把用户导向 Claim 登录、用 code 换 token、本地验签后消费。协议端点是标准 OAuth2/OIDC 核心子集—— 任意技术栈裸 HTTP 即可接入(任意标准 OIDC 客户端库同样兼容);.NET 技术栈推荐 KernLab.Claim.Client SDK(HTTP 薄封装 + 验签/轮换纪律单点,见 §2)。本指南两形态都覆盖:SDK 路径(§2)与 HTTP API 直连(§5.1,任意语言)。

2. 快速上手(.NET SDK——HTTP 直连见 §5.1)

// ① 取 token(服务链路——client_credentials)
var tokens = new TokenClient(new HttpClient());
var issued = await tokens.ClientCredentialsAsync(
    "https://claim.example/connect/token", clientId, clientSecret, scope: "kernlab.cohort.config.read");

// ② 本地验签(零网络依赖;aud 必填——编译期强制)
var verifier = new JwtVerifier(new JwksFetcher(httpClient, "https://claim.example/.well-known/jwks.json"));
var verified = await verifier.VerifyAsync(issued.AccessToken,
    expectedAudience: clientId, expectedIssuer: "https://claim.example");

3. 概念与术语

术语 含义
aud 受众 token 的目标消费方,恒等于签发时的 client_id——验签必带,缺/不符即拒(隔离失效点)
scp 能力集 token 授权 scope = 客户端授权集 × 用户白名单交集(用户空集 = 跟随客户端上限)
PKCE 授权码流的防截获机制(S256 强制——plain 降级被服务端拒绝)
会话(SSO) Claim 侧浏览器会话——命中未过期会话的 authorize 免登录直接发码(单点登录本体)
back-channel 登出 会话销毁时 Claim 向各 RP 注册地址 POST logout_token(JWT)——RP 销毁本地会话

4. 怎么选(接入形态)

形态 适用 流
HTTP API 直连(§5.1) 非 .NET 技术栈 / 不引 SDK——任意语言,标准 OAuth2/OIDC 客户端库或裸 HTTP 同右各流(端点是跨技术栈契约)
服务链路 服务到服务调用(无用户) client_credentials + 内省(高敏面)或本地验签
RP 控制台 有用户界面的应用 授权码 + PKCE → userinfo;refresh 轮换续期
集群节点 长驻节点(重启风暴容忍) client_credentials(typ=node,长寿缺省 30d + 内省撤销)
代唤(下游) RP 调下游服务(aud 映射) token-exchange:subject_token 换发下游 aud + act 串联

5. 怎么用

5.1 端点(discovery 为准:/.well-known/openid-configuration)

端点 语义
GET /connect/authorize 授权码流入口(PKCE S256 强制;plain 拒)
POST /connect/token 四流:authorization_code / client_credentials / refresh_token / token-exchange
GET /connect/userinfo 身份声明(Bearer)
POST /connect/introspect 内省(客户端凭证;C4 强制面——admin 族每个请求判定)
POST /connect/revocation 撤销(RFC 7009;恒 200)
GET /connect/logout RP-Initiated 单点登出(post_logout_redirect_uri 白名单 + back-channel 通知)
GET /.well-known/jwks.json 验签公钥(kid 未命中自动刷新)

5.1.1 HTTP API 直连(任意技术栈——全流程)

端点即契约:以下每一步都是标准 HTTP(表单/GET),任何语言照抄。示例 CLAIM=https://claim.example。

① 发现(可选——端点自描述)

curl $CLAIM/.well-known/openid-configuration
# token_endpoint / authorization_endpoint / jwks_uri / introspection_endpoint ...

② 授权码流(用户登录——浏览器 302 到 authorize)

authorize 查询参数(全部必填,无缺省):

response_type=code
client_id=<注册的 client_id>
redirect_uri=<白名单逐字匹配>
scope=<空格分隔,如 "openid offline_access">
state=<原样回传的随机串>
code_challenge=<BASE64URL(SHA256(ASCII(code_verifier)))>   # PKCE:先生成 verifier(43-128 字符随机串)
code_challenge_method=S256                                  # 仅接受 S256(plain 拒)
nonce=<随机串>                                              # 可选——id_token 回填防重放

用户在 Claim 登录页完成认证后,浏览器 302 回 redirect_uri?code=…&state=…。

③ 换 token(POST 表单——client 凭证支持 Basic 或 post 二选一)

curl -X POST $CLAIM/connect/token   -d grant_type=authorization_code   -d code=<②的 code>   -d redirect_uri=<与②逐字一致>   -d client_id=acc-web   -d client_secret=***   -d code_verifier=<②的 verifier 原文>
# 200 {"access_token","token_type":"Bearer","expires_in","scope","refresh_token","id_token"}

④ 服务链路(无用户——client_credentials)

curl -X POST $CLAIM/connect/token   -d grant_type=client_credentials -d client_id=acc-svc -d client_secret=*** -d scope=kernlab.cohort.config.read

⑤ 调用受保护 API(Bearer)

curl -H "Authorization: Bearer <access_token>" $CLAIM/connect/userinfo
# 200 {"sub","ten","env","scp"} —— 授权 profile/email scope 后另含标准 claims(见下)

标准身份 claims(WP8):authorize 请求带 profile / email scope(须在客户端授权与用户白名单 交集内),userinfo 按令牌 scp 投影——profile → name(显示名,有值才发)+ preferred_username; email → email + email_verified(布尔)。id_token 维持最小集(身份详情以 userinfo 为准, OIDC 标准形态)。

⑥ 刷新(轮换——旧 refresh_token 立即作废,只保留最新值)

curl -X POST $CLAIM/connect/token   -d grant_type=refresh_token -d refresh_token=<最新值> -d client_id=acc-web -d client_secret=***

⑦ 内省与撤销(高敏面——每个请求判定活性)

curl -X POST $CLAIM/connect/introspect -d token=<access_token> -d client_id=acc-svc -d client_secret=***
# {"active":true,"sub","aud","exp","scope",...}   撤销后 active:false(RFC 7662)
curl -X POST $CLAIM/connect/revocation -d token=<token> -d client_id=acc-svc -d client_secret=***

⑧ 设备授权流(TV / CLI / IoT——WP9)

# ① 发起(public 客户端免 client_secret——仅 client_id)
curl -X POST $CLAIM/connect/deviceauthorize -d client_id=tv-app -d scope="openid offline_access"
# ② 浏览器打开 verification_uri(用户输码 → 登录 → 确认/拒绝)
# ③ 轮询(≥ interval 秒一次;authorization_pending=继续、slow_down=退避 +5s、
#     access_denied/expired_token=终止、200=交付 access+refresh——device_code 单次取走)
curl -X POST $CLAIM/connect/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
     -d device_code=<device_code> -d client_id=tv-app

SDK 形态:TokenClient.DeviceAuthorizeAsync + TokenClient.DeviceTokenAsync(轮询错误不抛—— 按 DevicePollResult.Error 分支续询/退避)。

⑨ DPoP 绑定令牌消费(资源侧——WP11)

token 请求携 DPoP proof 即得绑定 access token(cnf.jkt)——资源侧消费义务:

Authorization: DPoP <access_token>
DPoP: <proof——htm=GET、htu=本请求 URL(剥 query)、iat、jti(每次新鲜)、ath=base64url(SHA256(access_token))>
  • proof 公钥必须匹配令牌 cnf.jkt(DpopProofValidator 在 KernLab.Claim 核心包,资源方按需引用; 或按 RFC 9449 §4.2 自实现同矩阵——typ/alg 白名单/jwk 无私钥/htm/htu/iat ±60s/jti 单次/ath)。
  • Bearer scheme 携绑定令牌 = 401(WWW-Authenticate: DPoP algs="ES256"——降级即拒绝面)。
  • SDK 形态:new TokenClient(httpClient, ecdsaKey) 全请求自动携 proof;VerifiedToken.CnfJkt 透出绑定拇印(非空 = sender-constrained 令牌)。

⑩ 登出(RP-Initiated)

302 → $CLAIM/connect/logout?post_logout_redirect_uri=<白名单>&state=<原样回传>

⑨ 本地验签(安全面——任何 JOSE 库;两条红线不可绕)

  • 拉取 $CLAIM/.well-known/jwks.json(ES256 公钥集),按 header kid 定位验签;kid 未命中重拉一次;
  • alg 白名单只认 ES256(none/HS256 恒拒);aud 必须校验且等于本方 client_id(缺 aud 即拒);
  • 校验 exp/nbf(含时钟偏移容忍)。

⑩ 错误形态

token/introspect 端点错误 = JSON {"error","error_description"}(invalid_client / invalid_grant / unsupported_grant_type / kernlab_invalid_token ...);authorize 校验失败 = 400 文本;内省对无效 token 恒 {"active":false} 而非报错(RFC 7662 语义)。

5.2 管理面(客户端/用户注册)

  • CLI:kernlab-claim client add <id> --scopes ... --redirects ...;
  • HTTP 桥:POST /claim/client/add/...(Bearer + kernlab.claim.admin);
  • 控制台:/ui/(浏览器会话 + admin 角色)。

5.3 登出接入(RP 侧义务)

  1. 注册 post_logout_redirect_uris 白名单 + backchannel_logout_uri;
  2. 实现 back-channel 端点:接收 logout_token(JWT,events/sub/sid)→ 校验签名 → 销毁本地会话;
  3. RP 自己的登出按钮 → 302 到 /connect/logout?post_logout_redirect_uri=...。

6. 反模式

症状 为什么错 正确形态
验签不传 audience 只验签不验受众 = 隔离失效点(契约 §4) SDK expectedAudience 必填,错 aud/缺 aud 即拒
手拼 authorize URL 不走 SDK PKCE 形态自拼易降级/漏 state TokenClient.BuildAuthorizeUrl
复用旧 refresh token 轮换后旧令牌二次使用 = 泄露信号,触发链式撤销 只用最新 refresh_token,旧值即弃
宿主运行中跑 CLI 写数据 FS 卷锁单写者——并发第二开卷显式失败 管理写走运行中宿主 HTTP 桥(/claim/**)
信任未校验的 logout_token 伪造通知可销任意会话 RP 侧对 logout_token 验签(同 JWKS)

7. 想深入

  • API 参考(TokenClient / JwtVerifier / JwksFetcher 完整签名);
  • 端点实时契约:GET /.well-known/openid-configuration(发现文档即权威端点清单)。