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 最常见的哑火原因。

Keycloak --optimized 启动失败：IAM 构建期选项与运行期选项的边界

Thu, 24 Sep 2026 22:00:00 +0800

容器里给 Keycloak 挂 KC_DB、KC_METRICS_ENABLED 却启动失败或选项不生效，多数是 build-time 与 runtime 选项混用。这篇把校验逻辑、报错原文、版本差异、正确镜像构建方式和回滚讲清楚。

Keycloak Kerberos/SPNEGO 对接 AD 域：IAM 内网免登配置与排错

Thu, 24 Sep 2026 23:00:00 +0800

内网免登不是打开一个开关：SPN 必须与浏览器访问的地址一致、keytab 必须与 AD 账号当前密钥一致、krbPrincipalAttribute 决定票据里的用户怎么落到目录里。这篇给出三段配置、验证命令、错误对照表与只回退一层的回滚顺序。

Keycloak 身份代理登出验签：CVE-2026-18569 与 26.8 升级准备

Fri, 25 Sep 2026 21:00:00 +0800

把 OIDC IdP 的「Validate Signatures」关掉，会连带放过身份代理方向的登出令牌：26.7.4 及更早接受 alg=none 的伪造登出令牌（CVE-2026-18569）。修复 PR #52171 尚未合入，登记在 26.8.0 升级说明里——升级前必须补上公钥或 JWKS，否则上游登出传播会在升级后失效。