Keycloak 客户端认证与 IAM 凭据轮换：client secret、private_key_jwt、mTLS | IDaaS Book

Mon, 21 Sep 2026 20:50:00 +0800

场景

服务间调用、定时任务、第三方系统对接——这类 confidential client 的凭据通常就是一个 client_secret，写在 Deployment 的环境变量或 ConfigMap 里，从上线那天起没换过。Keycloak 里可以用的客户端认证器有四种（另有由 IdP 代签断言的一种），它们对「谁能签发凭据、允许什么算法、断言多久有效、怎么轮换」的约束各不相同；配错之后报错几乎都是同一个 invalid_client，日志只有一句 Client authentication with signed JWT failed，看不出到底是密钥不对还是 aud 不对。

这篇文章解决三件事：四种认证器的硬边界、private_key_jwt 断言的完整校验链（哪些 invalid_client 其实与密钥无关）、以及 client secret 不停机轮换怎么做和它的前置条件。

只讨论 token endpoint 上的客户端认证，不涉及用户登录流程；用户侧的 MFA/Passkey 落地见 Passkey / WebAuthn / FIDO2 IAM 企业落地指南。下文源码结论取自 Keycloak 26.7.4 tag 的 services/src/main/java/org/keycloak/authentication/authenticators/client/，错误文案为该版本源码中的原文；文档与实现不一致时以实现为准。

四种认证器与它们的硬边界

Client Authenticator（控制台）	provider id	凭据形态	算法边界（源码强制）
Client Id and Secret	`client-secret`	共享密钥，`client_secret_basic` 或 `client_secret_post`	无签名
Signed JWT	`client-jwt`	客户端私钥签名断言（= `private_key_jwt`）	只接受非对称算法，否则 `Algorithm is not asymmetric`
Signed JWT with Client Secret	`client-secret-jwt`	用 secret 做 HMAC 签名断言（= `client_secret_jwt`）	只接受对称算法，否则 `Algorithm is not symmetric`
X.509 Certificate	`client-x509`	TLS 客户端证书	校验 Subject DN 与根 CA Subject DN

再加一种由 IdP 代签断言的 Signed JWT（SPIFFE JWT SVID、Kubernetes service account 这类跨信任域凭据），它的 iss 不等于 sub，处理逻辑独立，本文不展开——这类凭据属于工作负载身份，签发、轮换与校验方式见 SPIFFE/SPIRE 工作负载身份 IAM 落地。顺带说明一个常见误用：JWT-SVID 不能直接当 client assertion 用，它的 sub 是签发方标识的 SPIFFE ID，不是提出请求的客户端自己。

Keycloak 作为 MCP 授权服务器：IAM audience 绑定与 resource indicators 落地 | IDaaS Book

Mon, 21 Sep 2026 23:00:00 +0800

场景

MCP server 用 Keycloak 做授权服务器之后，接入方报的错几乎都是同一个：token 能签发、能验签、iss 也对，但 MCP server 返回 401 invalid_token，描述是「token 的 audience 不是给我的」。原因在 MCP 授权规范的一条 MUST——客户端必须在授权请求和 token 请求里带 resource 参数（ RFC 8707），MCP server 必须校验 token 是专门为它签发的；而 Keycloak 的官方文档在 26.7.4 明确写着「Keycloak cannot recognize resource parameter」，MCP 2025-06-18 / 2025-11-25 / 2026-07-28 三个版本都被标为 Partially Supported without Resource Indicators。

也就是说：客户端一定会带 resource，Keycloak 默认静默忽略它，既不报错也不按它设置 aud。这一篇文章讲清两件事——怎么在官方推荐路径下把 aud 绑对，以及 26.6.0 起已进入发布版、但仍属实验特性的 resource indicators，在源码层面到底做了什么、什么情况下会把已经能跑的客户端打断。

结论先说：Keycloak 的实验实现是「过滤」aud，不是「添加」aud。 如果 token 里本来没有目标资源的标识，resource 不会帮你补上，而是直接返回 invalid_target。理解这一点，能省掉一轮线上排错。

适用与不适用

场景	是否适用	说明
MCP server 放在 Keycloak 后面，客户端是 VS Code / Claude Code / MCP Inspector	✅	需要 CIMD（`client_id` 是 URL）或 DCR 注册客户端
一个 realm 里有多台 MCP server，同一个 agent 客户端要分别取 token	✅	aud 收敛为单值是这套机制的核心价值，跨 server 重放会被拒
只需要给单台 server 发 token，且不想开实验特性	✅（走官方 scope 路径）	见下节路径 A，稳定、无需实验特性
MCP 2025-03-26 及更早版本	❌	该版本不要求 `resource` 与 aud 绑定，Keycloak 文档写明 No special setup is required
本地 stdio 传输的 MCP server	❌	没有 HTTP 授权层，与本文无关
生产环境无法接受「实验特性可能破坏性变更」	⚠️	路径 A 即可满足 MCP 的 MUST/SHOULD 集合，路径 B 是增益不是前提

两条落地路径

	路径 A：scope 驱动（官方文档路径）	路径 B：resource 驱动（实验特性）
机制	用 `scope` 触发 Audience mapper，把 MCP server 的标识追加进 `aud`	解析 `resource` 参数，把 `aud` 替换成该参数对应的资源
前置配置	client scope + Audience mapper	在 A 的基础上，额外给 MCP server 的客户端配 `resource_url` 属性，并启用 `resource-indicators` 特性
特性开关	不需要	`--features=resource-indicators`（26.7.4 为 EXPERIMENTAL）
token 的 `aud`	取决于客户端请求了哪些 scope，可能是多个值	只剩 `resource` 对应的单值（多值会被覆盖）
失败模式	客户端没请求 scope → `aud` 缺失 → RS 401	`resource` 解析不到客户端 → `invalid_target`（token 根本不签发）
合规状态	官方文档认可，但 RFC 8707 那一行仍是 Not supported	实现已合入（ PR #46763），文档未发布（ #47127 仍 open）

官方文档给出的做法是路径 A：为 MCP server 声明的每个 scope 建一个 client scope，每个 scope 里放一个 Audience mapper，Included Custom Audience 填 MCP server 的 URL（例如 https://example.com/mcp）。客户端请求哪些 scope，aud 里就有对应值。这条路能跑通，因为 MCP 客户端会从 RFC 9728 Protected Resource Metadata 里读取 scopes_supported 并请求这些 scope——如果 MCP server 没在元数据里声明 scope，客户端就不会请求，mapper 也就不会触发，这是路径 A 最常见的哑火原因。

Oauth2 on IDaaS Book

Keycloak 客户端认证与 IAM 凭据轮换：client secret、private_key_jwt、mTLS | IDaaS Book

场景

四种认证器与它们的硬边界

Keycloak 作为 MCP 授权服务器：IAM audience 绑定与 resource indicators 落地 | IDaaS Book

场景

适用与不适用

两条落地路径