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 公钥集),按 headerkid定位验签;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 侧义务)
- 注册
post_logout_redirect_uris白名单 +backchannel_logout_uri; - 实现 back-channel 端点:接收
logout_token(JWT,events/sub/sid)→ 校验签名 → 销毁本地会话; - 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(发现文档即权威端点清单)。