<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:fh="http://purl.org/syndication/history/1.0"><channel><title>IDaaS Book | 博客</title><description>面向架构师与平台工程师的中文 IDaaS / IAM 系统手册，覆盖 OAuth 2.0、OIDC、SAML、Keycloak 部署与零信任治理</description><link>https://idaas.xlabs.club/</link><language>zh-CN</language><fh:complete/><atom:link rel="self" href="https://idaas.xlabs.club/blog/rss.xml"/><item><title>IAM 会话超时排错：Keycloak SSO/Client Session 约束</title><link>https://idaas.xlabs.club/blog/keycloak-session-timeouts/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-session-timeouts/</guid><description>IAM 会话超时排错实战：Keycloak SSO Session Idle/Max 与 Client Session 的取值优先级、Refresh Token 实际有效期为什么被 SSO Session Max 夹住、26.5 起的超时校验报错、最小配置与验证命令。</description><pubDate>Sat, 12 Sep 2026 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;场景&quot;&gt;场景&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;三个症状，配置界面里都能找到「看起来对」的字段，但改完没效果：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;SSO Session Idle 明明设了 30 分钟，用户却抱怨几分钟就被要求重新登录。&lt;/li&gt;
&lt;li&gt;为了让移动端的 Refresh Token 活得更久，把某个客户端 Advanced 里的 &lt;strong&gt;Client Session Max&lt;/strong&gt; 调到比 &lt;strong&gt;SSO Session Max&lt;/strong&gt; 还大——不生效；升级到 26.5 之后保存直接报错。&lt;/li&gt;
&lt;li&gt;客户端每次刷新都能拿到新的 &lt;code dir=&quot;auto&quot;&gt;refresh_expires_in&lt;/code&gt;，但某一次刷新突然返回 400 &lt;code dir=&quot;auto&quot;&gt;invalid_token&lt;/code&gt;，而用户在 IdP 的 SSO 会话其实还活着。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;本文只讲一件事：&lt;strong&gt;这些超时字段之间谁覆盖谁、谁夹住谁，以及改动的生效时机&lt;/strong&gt;。参数语义以 Keycloak 26.7.x 官方 &lt;em&gt;Server Administration Guide&lt;/em&gt; 的 Sessions / Tokens 说明为准，行为以源码与官方测试用例为证；三层会话（用户会话 / 客户端会话 / Token）的概念与吊销机制不在本文重复，见 &lt;a href=&quot;https://idaas.xlabs.club/docs/advanced-topics/iam-session-management/&quot;&gt;IAM 会话管理与 Token 生命周期&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;适用：Keycloak 26.x（本文基线 26.7.x），尤其是刚从 26.0 之前升上来、或准备升到 26.5+ 的部署。&lt;/p&gt;
&lt;p&gt;不适用：17.x 及更早版本（Admin Console 字段划分与本文不同，且没有持久化用户会话）；其他 IdP 的字段名完全不一样，但「外层会话夹住内层 Token」的约束思路是通用的。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;参数地图哪个字段在哪个-tab&quot;&gt;参数地图：哪个字段在哪个 Tab&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;先把「Realm Settings → Sessions」和「Realm Settings → Tokens」两个 Tab 分开记。把 SSO Session Idle 说成「在 Tokens 里配」是中文资料里最常见的错位，它会让你在错误的页面反复改一个不存在的字段。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Sessions Tab（用户会话与客户端会话）&lt;/strong&gt;&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;Realm 级 JSON 属性&lt;/th&gt;
&lt;th&gt;作用对象&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SSO Session Idle&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionIdleTimeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用户会话（父），空闲超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSO Session Max&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionMaxLifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用户会话（父），绝对超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSO Session Idle Remember Me&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionIdleTimeoutRememberMe&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;勾选 Remember Me 时的空闲超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SSO Session Max Remember Me&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionMaxLifespanRememberMe&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;勾选 Remember Me 时的绝对超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client Session Idle&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;clientSessionIdleTimeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端会话（子），空闲超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client Session Max&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;clientSessionMaxLifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端会话（子），绝对超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Offline Session Idle&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;offlineSessionIdleTimeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;离线会话空闲超时&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Offline Session Max Limited&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;offlineSessionMaxLifespanEnabled&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;是否给离线会话加绝对上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Offline Session Max&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;offlineSessionMaxLifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;离线会话绝对上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client Offline Session Max&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;clientOfflineSessionMaxLifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;单个客户端的离线绝对上限&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Tokens Tab（Token 与动作有效期）&lt;/strong&gt;&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;Realm 级 JSON 属性&lt;/th&gt;
&lt;th&gt;说明&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Access Token Lifespan&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;accessTokenLifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Access Token 的 &lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access Token Lifespan For Implicit Flow&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;accessTokenLifespanForImplicitFlow&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;仅 Implicit Flow&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Revoke Refresh Token&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;revokeRefreshToken&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;刷新即轮换并撤销旧 Refresh Token&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Refresh Token Max Reuse&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;refreshTokenMaxReuse&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;与轮换配合的重用次数上限&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client login timeout&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;clientLoginTimeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;授权码流程完成时限&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;客户端级可以覆盖的是四个属性（Admin Console → 客户端 → Advanced settings，JSON 里表现为 &lt;code dir=&quot;auto&quot;&gt;attributes&lt;/code&gt;）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;client.session.idle.timeout&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;client.session.max.lifespan&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;client.offline.session.idle.timeout&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;client.offline.session.max.lifespan&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;字段名来自 Keycloak 源码常量 &lt;code dir=&quot;auto&quot;&gt;OIDCConfigAttributes&lt;/code&gt;，不是杜撰的别名——用 Admin REST API 或 partial import 写配置时必须用这四个字符串，界面上则显示为 Client Session Idle / Client Session Max / Client Offline Session Idle / Client Offline Session Max。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;取值优先级0-表示继承min-表示夹住&quot;&gt;取值优先级：0 表示继承，min() 表示夹住&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;优先级顺序&quot;&gt;优先级顺序&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;SessionExpirationUtils&lt;/code&gt; 是 Keycloak 计算会话到期时刻的地方，客户端会话的最大生命周期按下面的顺序取值：&lt;/p&gt;
&lt;pre&gt;flowchart TD
    A[&quot;客户端属性 client.session.max.lifespan&amp;#x3C;br/&gt;（Advanced settings）&quot;] --&gt;|&quot;&gt; 0 时生效&quot;| E
    A --&gt;|&quot;未设置 / 0&quot;| B[&quot;Realm 的 Client Session Max&amp;#x3C;br/&gt;（clientSessionMaxLifespan）&quot;]
    B --&gt;|&quot;&gt; 0 时生效&quot;| E
    B --&gt;|&quot;未设置 / 0&quot;| C[&quot;SSO Session Max&amp;#x3C;br/&gt;（ssoSessionMaxLifespan）&quot;]
    C --&gt;|&quot;粒度 1&quot;| E
    D[&quot;用户会话到期时刻 = 创建时间 + SSO Session Max&quot;] --&gt;|&quot;粒度 2&quot;| E
    E[&quot;客户端会话到期 = min(粒度 1, 粒度 2)&quot;] --&gt; F[&quot;Refresh Token 在该时刻失效&quot;]&lt;/pre&gt;
&lt;p&gt;图的重点是右侧那个 &lt;code dir=&quot;auto&quot;&gt;min()&lt;/code&gt;：&lt;strong&gt;无论你把 Client Session Max 调多大，客户端会话（也就是挂在它上面的 Refresh Token）都不会活得比用户会话更久&lt;/strong&gt;。源码中先算出 &lt;code dir=&quot;auto&quot;&gt;clientSessionCreated + clientSessionMaxLifespan&lt;/code&gt;，再与 &lt;code dir=&quot;auto&quot;&gt;userSessionExpires&lt;/code&gt; 取最小值，没有例外分支。所以「把 Client Session Max 设得比 SSO Session Max 大来延长 Refresh Token」这条路从来就不存在——26.5 之前它只是静默地取小值，让你以为配置生效了。&lt;/p&gt;
&lt;p&gt;空闲超时同理按「客户端属性 → Realm 的 Client Session Idle → SSO Session Idle」取值，Remember Me 场景下会先用 &lt;code dir=&quot;auto&quot;&gt;max(SSO Session Idle, SSO Session Idle Remember Me)&lt;/code&gt; 作为基准；客户端会话空闲时间从「最后一次刷新」起算。注意客户端会话空闲判定与用户会话空闲判定是两条独立检查，&lt;strong&gt;谁先到期谁生效&lt;/strong&gt;，所以最终有效空闲时间仍然是两者中较短的那个。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;一段实测路径：Keycloak 官方测试 &lt;code dir=&quot;auto&quot;&gt;RefreshTokenTimeoutsTest#refreshTokenUserSessionMaxLifespan&lt;/code&gt; 把 &lt;code dir=&quot;auto&quot;&gt;ssoSessionMaxLifespan&lt;/code&gt; 设为 3600、&lt;code dir=&quot;auto&quot;&gt;ssoSessionIdleTimeout&lt;/code&gt; 设为 7200，然后在 1800 秒时刷新，断言 &lt;code dir=&quot;auto&quot;&gt;refresh_expires_in &amp;#x3C;= 1800&lt;/code&gt;。空闲值比最大生命周期大，Refresh Token 依然被 SSO Session Max 夹住——这就是上面那张图在代码里的样子。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;div&gt;&lt;h3 id=&quot;265-起越界配置不再静默&quot;&gt;26.5 起：越界配置不再静默&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;从 26.5 开始，Keycloak 在创建/更新 Realm 和客户端时会校验这些关系（官方升级说明 &lt;em&gt;Validation of client session timeouts&lt;/em&gt;）。三处结果：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;改 Realm：Realm 级的 Client Session Idle/Max 不得超过 SSO Session 对应值，否则抛错，报错文本形如 &lt;code dir=&quot;auto&quot;&gt;Client Session Idle Timeout cannot be greater than Realm SSO Idle Timeout.&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;Client session max lifespan cannot exceed realm SSO session max lifespan.&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;改客户端：客户端级属性超过 Realm 值时，表单直接给出校验错误，文本形如 &lt;code dir=&quot;auto&quot;&gt;Client session idle timeout cannot exceed realm SSO session idle timeout.&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Realm 开启了 Remember Me：允许的上限变为 &lt;code dir=&quot;auto&quot;&gt;max(SSO 值, Remember Me 值)&lt;/code&gt;，相应报错文本末尾会带上 &lt;code dir=&quot;auto&quot;&gt;and RememberMe idle timeout.&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;and RememberMe Max span.&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;有两个容易踩的边界：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;改 Realm 的 SSO 设置不会回头校验存量客户端&lt;/strong&gt;。官方明确说明当前只校验被更新/导入的那个对象，所以你可能在「动 Realm」的瞬间才第一次撞到报错。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;JSON 里写 &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; 或省略 ≠ 更宽松&lt;/strong&gt;，而是「继承上层值」。想让某个客户端比 Realm 更早掉会话（例如管理面应用要求 15 分钟绝对上限），填小于 Realm 的值是合法且推荐的；想比 Realm 更晚，26.5 开始直接拒绝。&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;为什么空闲时间不是正好-30-分钟&quot;&gt;为什么空闲时间不是「正好 30 分钟」&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;官方文档在 Sessions 说明下有一条 NOTE：&lt;strong&gt;两分钟的空闲宽限窗口只在未启用持久化用户会话时生效&lt;/strong&gt;——即 30 分钟设置实际在 32 分钟失效，目的是避免集群/多数据中心里刷新消息尚未同步时误判会话过期。&lt;/p&gt;
&lt;p&gt;而自 Keycloak 26.0 起，&lt;code dir=&quot;auto&quot;&gt;persistent-user-sessions&lt;/code&gt; &lt;strong&gt;默认启用&lt;/strong&gt;（26 之前只持久化离线会话）。两件事叠起来意味着：默认部署里没有那 2 分钟宽限，到期时间就是配置值本身。如果你在网上看到「Keycloak 会自动多给 2 分钟」的结论，它描述的是易失会话（volatile sessions）的行为，不是你手上这套 26.x 默认配置。反过来说，为了排查问题显式禁用持久化会话后，观察到的到期时间会变，别把它当成 Keycloak 行为不稳定。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;改配置什么时候生效&quot;&gt;改配置什么时候生效&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;会话到期时刻是&lt;strong&gt;按存储的时间戳与当前配置计算&lt;/strong&gt;的，不是签发 Token 时写死的绝对时间。官方测试直接覆盖了这个行为：&lt;code dir=&quot;auto&quot;&gt;refreshTokenUserSessionMaxLifespanModifiedAfterTokenRefresh&lt;/code&gt; 先以 7200 秒签发 Token，再把 SSO Session Max 与 Client Session Max 都改成 3600，然后把时钟推到 3700 秒刷新——返回 400 &lt;code dir=&quot;auto&quot;&gt;invalid_token&lt;/code&gt;，用户会话与客户端会话一并消失。&lt;/p&gt;
&lt;p&gt;实践含义：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;调小&lt;/strong&gt;超时会对&lt;strong&gt;已经在线&lt;/strong&gt;的会话立即生效。上线前先在测试 Realm 用同一套数值验证一遍，不要在生产上「先调小观察」。&lt;/li&gt;
&lt;li&gt;调大之后，已存在的会话是否立刻延长，取决于该会话是否还会走刷新；判定用的是当前配置，所以刷新生效是确定路径，不要假设所有客户端的既有会话都会马上变长。&lt;/li&gt;
&lt;li&gt;用 &lt;code dir=&quot;auto&quot;&gt;Refresh Token Max Reuse&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;Revoke Refresh Token&lt;/code&gt; 做轮换时，旧 Refresh Token 的重用窗口同样受这层约束限制：外层会话一到期，轮换链整体失效，而不是「活到轮换次数用完」。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;症状--先看什么&quot;&gt;症状 → 先看什么&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;先检查&lt;/th&gt;
&lt;th&gt;常见根因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;几分钟就要求重新登录&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;accessTokenLifespan&lt;/code&gt;、网关侧 Cookie 有效期（如 oauth2-proxy &lt;code dir=&quot;auto&quot;&gt;--cookie-expire&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--cookie-refresh&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;把 Access Token 生命周期当成用户登录有效期；网关 Cookie 比 IdP 会话短，前端不断重定向&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;空闲 30 分钟必掉线，即便期间一直在操作&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionIdleTimeout&lt;/code&gt; 与客户端 &lt;code dir=&quot;auto&quot;&gt;client.session.idle.timeout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;客户端级空闲值比 Realm 小（或反过来）；刷新请求会 bump 空闲时间，纯后台任务不会&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;移动端/CLI 隔夜掉线&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ssoSessionMaxLifespan&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;client.session.max.lifespan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无浏览器交互的客户端只能靠 Refresh Token，而它被 SSO Session Max 夹住&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;勾了 Remember Me 也没变长&lt;/td&gt;
&lt;td&gt;Realm 是否启用 Remember Me、&lt;code dir=&quot;auto&quot;&gt;ssoSessionIdleTimeoutRememberMe&lt;/code&gt; 是否为 0&lt;/td&gt;
&lt;td&gt;值为 0 时回落成普通 SSO Session Idle，等于没配&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;离线 Token 似乎永不过期&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;offlineSessionMaxLifespanEnabled&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;该开关关闭时离线会话不按绝对时长失效，只按 &lt;code dir=&quot;auto&quot;&gt;offlineSessionIdleTimeout&lt;/code&gt; 空闲失效&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;刷新返回 400 &lt;code dir=&quot;auto&quot;&gt;invalid_token&lt;/code&gt;，但 IdP 会话还在&lt;/td&gt;
&lt;td&gt;客户端会话是否已到期&lt;/td&gt;
&lt;td&gt;客户端会话先于用户会话到期：浏览器流程会静默重新认证（用户无感），纯 bearer 客户端只能报错重登&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;26.5 升级后 Realm/客户端保存报超时校验错误&lt;/td&gt;
&lt;td&gt;存量客户端 Advanced settings&lt;/td&gt;
&lt;td&gt;越界配置被新校验拦下，需要先改回合法范围&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h2 id=&quot;最小配置&quot;&gt;最小配置&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;下面两种写法等价，属性名以 Realm 级 JSON 为正：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;realm&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;corp&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;ssoSessionIdleTimeout&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;1800&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;ssoSessionMaxLifespan&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;28800&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;clientSessionIdleTimeout&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;1800&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;clientSessionMaxLifespan&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;28800&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;accessTokenLifespan&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;300&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;revokeRefreshToken&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;true&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;refreshTokenMaxReuse&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 用 kcadm 改现有 Realm（值均为秒）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kcadm.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;update&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;realms/corp&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ssoSessionIdleTimeout=&lt;/span&gt;&lt;span&gt;1800&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ssoSessionMaxLifespan=&lt;/span&gt;&lt;span&gt;28800&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;clientSessionIdleTimeout=&lt;/span&gt;&lt;span&gt;1800&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;clientSessionMaxLifespan=&lt;/span&gt;&lt;span&gt;28800&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 只收紧某个客户端的会话（不得超过 Realm 值）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kcadm.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;update&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;clients/&amp;#x3C;client-uuid&gt;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;corp&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;attributes.&quot;client.session.max.lifespan&quot;=900&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;数值取舍不在这里给「标准答案」：SSO Session Max 是有上限的信任窗口，办公后台 8-12 小时、管理面 1-2 小时都是常见区间，前提是你按自己的合规要求和登出体验验证过，而不是抄一个数字。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;验证&quot;&gt;验证&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 看 Realm 生效值（对比你刚写入的配置）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kcadm.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;realms/corp&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;SessionIdle|SessionMax|AccessTokenLifespan|RevokeRefresh&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 观察真实签发结果：refresh_expires_in 就是被夹住之后的值&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#    （占位符按实际环境替换；不要在生产上打印完整 Token）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;grant_type=password&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;client_id=&amp;#x3C;client&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;     &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;username=&amp;#x3C;user&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;password=&amp;#x3C;password&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;     &lt;/span&gt;&lt;span&gt;https://&amp;#x3C;idp-host&gt;/realms/&amp;#x3C;realm&gt;/protocol/openid-connect/token&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;python3&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-c&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;import json,sys; r=json.load(sys.stdin); print(&quot;expires_in&quot;,r[&quot;expires_in&quot;],&quot;refresh_expires_in&quot;,r[&quot;refresh_expires_in&quot;])&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 查在线会话（Admin REST API，路径取自官方 OpenAPI）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#    GET /admin/realms/{realm}/users/{user-id}/sessions&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#    GET /admin/realms/{realm}/client-session-stats&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-H&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;Authorization: Bearer &lt;/span&gt;&lt;span&gt;$TOKEN&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;     &lt;/span&gt;&lt;span&gt;&quot;https://&amp;#x3C;idp-host&gt;/admin/realms/&amp;#x3C;realm&gt;/users/&amp;#x3C;user-id&gt;/sessions&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;python3&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-m&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;json.tool&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 4. 需要立刻让某人下线时的两个端点（作用范围不同）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#    POST /admin/realms/{realm}/users/{user-id}/logout   —— 该用户全部会话&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#    DELETE /admin/realms/{realm}/sessions/{session-id}  —— 单个会话&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;另外，26.5 起 Account Console 的 &lt;strong&gt;Device Activity&lt;/strong&gt; 会把离线会话和普通会话一起列出，用户自己就能签出，运维排查时可以直接让用户截图核对，比翻数据库快。Token 吊销后的行为边界（Access Token 在 &lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 前仍可用）见 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-single-logout/&quot;&gt;IAM 单点登出排错&lt;/a&gt;。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;回滚&quot;&gt;回滚&lt;/h2&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;改之前先记录原值：&lt;code dir=&quot;auto&quot;&gt;kcadm.sh get realms/&amp;#x3C;realm&gt; &gt; realm-before.json&lt;/code&gt;，或者用 Realm 的 partial export 留档。&lt;/li&gt;
&lt;li&gt;这些参数是配置项而非 Schema 变更，改回原值即可恢复，不需要重启节点，也没有数据迁移。但注意上面讲的生效时机：&lt;strong&gt;调小过的时间段已经让部分在线会话失效&lt;/strong&gt;，回滚配置不能复活它们，用户需要重新登录一次。&lt;/li&gt;
&lt;li&gt;如果因为 26.5 校验而无法保存，优先把越界的客户端属性清空（回到继承 Realm），而不是先把 Realm 的 SSO Session 值放大——后者等于把整个 Realm 的信任窗口一次性放宽。&lt;/li&gt;
&lt;li&gt;排查期间若临时禁用了持久化用户会话（&lt;code dir=&quot;auto&quot;&gt;--features-disabled=persistent-user-sessions&lt;/code&gt;），务必恢复：禁用该特性在开发分支的升级说明中已被标记为弃用（&lt;code dir=&quot;auto&quot;&gt;changes-26_8_0.adoc&lt;/code&gt;，截至 26.7.3 尚未发布，正式结论以发布后的 release notes 为准）。&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;常见问题iam-会话超时&quot;&gt;常见问题（IAM 会话超时）&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;iam-里-sso-session-idle-和-client-session-idle-有什么区别&quot;&gt;IAM 里 SSO Session Idle 和 Client Session Idle 有什么区别？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;SSO Session Idle 管的是用户在 IdP 的用户会话（父会话，一个用户一个），Client Session Idle 管的是每个客户端各自的子会话。父会话失效会带走全部子会话；子会话失效只影响该客户端，浏览器里如果父会话还在，用户点一下就会被静默重新认证。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;为什么把-client-session-max-调大不能让-refresh-token-更长久&quot;&gt;为什么把 Client Session Max 调大不能让 Refresh Token 更长久？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;因为客户端会话到期时刻与用户会话到期时刻取了 &lt;code dir=&quot;auto&quot;&gt;min()&lt;/code&gt;。客户端会话最多活得和 SSO Session Max 一样久，26.5 起这种越界配置会在保存时直接报错。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;升级-keycloak-265-后保存-realm-报-client-session-idle-timeout-cannot-be-greater-than-realm-sso-idle-timeout-怎么办&quot;&gt;升级 Keycloak 26.5 后保存 Realm 报 “Client Session Idle Timeout cannot be greater than Realm SSO Idle Timeout” 怎么办？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;这是新加的校验在拦截历史配置。先确认目标语义：如果希望这些客户端会话更短，就把 Realm 级或客户端级的值改到不超过 SSO Session 对应值；如果确实需要更长的窗口，应该调大 SSO Session Idle/Max（并重新评估信任窗口），而不是绕开校验。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;改了会话超时已经登录的用户会立刻被踢下线吗&quot;&gt;改了会话超时，已经登录的用户会立刻被踢下线吗？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;调小会立即影响在线会话——到期时刻按时间戳与当前配置计算，官方测试覆盖了「签发 Token 后修改上限，随后刷新即失败」的场景。调大不会让所有既有会话统一延长，实际以刷新时的判定为准。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;access-token-该设多短&quot;&gt;Access Token 该设多短？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Access Token 是无状态 JWT，撤销不会立即生效，所以它应该短（分钟级），长期登录状态交给会话和 Refresh Token 维持。真正的排查顺序是：先看 IdP 的会话上限，再看网关 Cookie 生命周期，最后才调 Access Token Lifespan。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;关键来源&quot;&gt;关键来源&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;Keycloak Server Administration Guide — Session and token timeouts（Sessions/Tokens 字段语义与 2 分钟宽限 NOTE）：&lt;a href=&quot;https://www.keycloak.org/docs/latest/server_admin/index.html#_timeouts&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/docs/latest/server_admin/index.html#_timeouts&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;文档源文件（main 分支）：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/docs/documentation/server_admin/topics/sessions/timeouts.adoc&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/docs/documentation/server_admin/topics/sessions/timeouts.adoc&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;26.5 升级说明 — Validation of client session timeouts：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/docs/documentation/upgrading/topics/changes/changes-26_5_0.adoc&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/docs/documentation/upgrading/topics/changes/changes-26_5_0.adoc&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;26.0 发布说明 — User sessions persisted by default：&lt;a href=&quot;https://www.keycloak.org/docs/latest/release_notes/index.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/docs/latest/release_notes/index.html&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;到期计算源码：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/server-spi-private/src/main/java/org/keycloak/models/utils/SessionExpirationUtils.java&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/server-spi-private/src/main/java/org/keycloak/models/utils/SessionExpirationUtils.java&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;客户端级校验源码：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/validation/DefaultClientValidationProvider.java&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/services/src/main/java/org/keycloak/validation/DefaultClientValidationProvider.java&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Realm 级校验源码：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/model/storage-private/src/main/java/org/keycloak/storage/datastore/DefaultExportImportManager.java&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/model/storage-private/src/main/java/org/keycloak/storage/datastore/DefaultExportImportManager.java&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;官方测试用例：&lt;a href=&quot;https://github.com/keycloak/keycloak/blob/main/tests/base/src/test/java/org/keycloak/tests/oauth/RefreshTokenTimeoutsTest.java&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/keycloak/keycloak/blob/main/tests/base/src/test/java/org/keycloak/tests/oauth/RefreshTokenTimeoutsTest.java&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Admin REST API（会话相关端点）：&lt;a href=&quot;https://www.keycloak.org/docs-api/latest/rest-api/index.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/docs-api/latest/rest-api/index.html&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>auth</category></item><item><title>IAM 单点登出排错：Keycloak 登出不彻底的原因与修复</title><link>https://idaas.xlabs.club/blog/keycloak-single-logout/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-single-logout/</guid><description>IAM 单点登出排错实战：Keycloak RP-Initiated Logout 与 Back-Channel Logout 令牌配置、front/back channel 互斥开关、oauth2-proxy sign_out 只清自身 Cookie、400 报错与确认页卡住的根因。</description><pubDate>Fri, 11 Sep 2026 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;场景&quot;&gt;场景&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;三个高频症状，看起来都像「登出没生效」，实际断在不同环节：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;用户在应用 A 点退出，随后访问应用 B，仍然是登录状态。&lt;/li&gt;
&lt;li&gt;用户从应用点退出后被带回 Keycloak，却停在 “You are logged out” 页面，没有跳回 &lt;code dir=&quot;auto&quot;&gt;post_logout_redirect_uri&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;走 oauth2-proxy 的应用里，访问 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 后再打开应用，直接免登又进去了。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;适用&lt;/strong&gt;：Keycloak 26.x 的 OIDC 客户端，浏览器应用或 oauth2-proxy 之类的认证网关；想弄清 RP-Initiated Logout 与 Back-Channel / Front-Channel Logout 各自负责哪一层会话。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;不适用&lt;/strong&gt;：SAML 客户端（SAML Single Logout 用 Redirect/POST binding，参数语义与 OIDC 完全不同，见 &lt;a href=&quot;https://idaas.xlabs.club/docs/protocols/saml2/&quot;&gt;SAML 2.0 协议详解&lt;/a&gt;）；仍在用 &lt;code dir=&quot;auto&quot;&gt;Admin URL&lt;/code&gt; 回调格式的旧 Keycloak Java adapter——Keycloak 文档明确这种回调格式不是 OIDC 标准，只被 legacy adapter 或 Elytron WildFly OIDC adapter 支持。&lt;/p&gt;
&lt;p&gt;会话分层、Token 刷新与吊销的整体模型见 &lt;a href=&quot;https://idaas.xlabs.club/docs/advanced-topics/iam-session-management/&quot;&gt;IAM 会话管理&lt;/a&gt;；本文只解决「为什么这个客户端没被通知」和「怎么验证通知到了」。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;四种登出机制覆盖的范围不同&quot;&gt;四种登出机制覆盖的范围不同&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;机制&lt;/th&gt;
&lt;th&gt;入口/规范&lt;/th&gt;
&lt;th&gt;由谁发起&lt;/th&gt;
&lt;th&gt;能覆盖什么&lt;/th&gt;
&lt;th&gt;覆盖不到什么&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Session Management&lt;/td&gt;
&lt;td&gt;前端 JS 会话检测（OP iframe）&lt;/td&gt;
&lt;td&gt;浏览器轮询&lt;/td&gt;
&lt;td&gt;依赖该机制的前端应用会话&lt;/td&gt;
&lt;td&gt;服务端会话、非 JS 客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RP-Initiated Logout&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;end_session_endpoint&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用户点应用里的退出&lt;/td&gt;
&lt;td&gt;当前浏览器 SSO 会话，并向挂在该会话上的客户端传播登出&lt;/td&gt;
&lt;td&gt;其他浏览器/设备的会话&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Back-Channel Logout&lt;/td&gt;
&lt;td&gt;客户端 &lt;code dir=&quot;auto&quot;&gt;backchannel.logout.url&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Keycloak 服务端直连&lt;/td&gt;
&lt;td&gt;不依赖浏览器，可覆盖非当前浏览器的会话（管理员吊销场景）&lt;/td&gt;
&lt;td&gt;未配置 URL 的客户端；未真正实现端点的客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Front-Channel Logout&lt;/td&gt;
&lt;td&gt;客户端 &lt;code dir=&quot;auto&quot;&gt;frontchannel.logout.url&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;浏览器 iframe&lt;/td&gt;
&lt;td&gt;同一个正在被登出的浏览器会话&lt;/td&gt;
&lt;td&gt;管理员发起的吊销（没有对应浏览器会话）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;第一条判断规则：&lt;strong&gt;会话残留通常不是 Keycloak 没登出，而是那个客户端根本没有被通知。&lt;/strong&gt; Keycloak 客户端帮助文本写得很直白：如果既没有配置 Backchannel logout URL，也没有配置 &lt;code dir=&quot;auto&quot;&gt;Admin URL&lt;/code&gt;，登出请求不会发给这个客户端；此时应用侧会话会保留到 access token 过期，之后客户端尝试刷新 Token 会失败，因为 Keycloak 的 SSO 会话已经结束。&lt;/p&gt;
&lt;p&gt;第二条规则来自 Keycloak 文档：管理员从 Admin Console 或 admin REST API 登出某用户时，可以传播 back-channel logout；&lt;strong&gt;front-channel 做不到&lt;/strong&gt;，因为 front-channel 只能在「正在被登出的那个浏览器会话」里触发。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;最容易踩的坑front--back-channel-是互斥开关&quot;&gt;最容易踩的坑：front / back channel 是互斥开关&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 客户端的 “Front channel logout” 是一个开关，它决定下面显示哪一组字段：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;开关 &lt;strong&gt;ON&lt;/strong&gt;：只显示 Front-Channel Logout URL（不填则回落到客户端的 base/home URL）与 Front-channel logout session required。&lt;/li&gt;
&lt;li&gt;开关 &lt;strong&gt;OFF&lt;/strong&gt;：才显示 Backchannel logout URL、Backchannel logout session required、Backchannel logout revoke offline sessions。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;所以「Backchannel logout URL 明明填了，客户端却收不到 POST」的最常见原因，就是开关还停在 ON——配置面板把你引导到了 front-channel 分支。Admin UI 里两种 URL 不会同时出现，这是设计行为，不是界面残缺。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;界面字段&lt;/th&gt;
&lt;th&gt;客户端属性&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Front channel logout（开关）&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;frontchannelLogout&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;决定用浏览器 iframe 还是服务端后台调用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Front-Channel Logout URL&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;frontchannel.logout.url&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;iframe 请求目标；不填回落到 base URL&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Front-channel logout session required&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;frontchannel.logout.session.required&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;iframe 请求是否携带 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt; 参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backchannel logout URL&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;backchannel.logout.url&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Logout Token 的 POST 目标&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backchannel logout session required&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;backchannel.logout.session.required&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Logout Token 是否包含 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backchannel logout revoke offline sessions&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;backchannel.logout.revoke.offline.tokens&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Logout Token 是否带 &lt;code dir=&quot;auto&quot;&gt;revoke_offline_access&lt;/code&gt; 事件&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Logout confirmation&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;logout.confirmation.enabled&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登出后是否插入 “You are logged out” 确认页（默认关闭）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Valid post logout redirect URIs&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;post.logout.redirect.uris&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;允许的登出回跳地址白名单&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;选型建议：能接收 POST 的服务端应用和认证网关用 back-channel（Keycloak 文档也认为它比 front-channel 更可靠，不依赖浏览器）；纯前端 SPA 若已依赖 Session Management，可以不配专用登出 URL。规范层面的硬约束是：&lt;strong&gt;RP 的 back-channel logout URI 必须能被 OP 直接访问&lt;/strong&gt;，藏在只有浏览器可达的 NAT/防火墙后面就无法工作（Back-Channel Logout 1.0 明确列为该机制的局限）。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;最小配置&quot;&gt;最小配置&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;keycloak-端&quot;&gt;Keycloak 端&lt;/h3&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;需要立刻登出的客户端：客户端 → Logout settings → 关闭 Front channel logout → 填 Backchannel logout URL，例如 &lt;code dir=&quot;auto&quot;&gt;https://app.example.com/oidc/backchannel-logout&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;需要精确到单一会话：Backchannel logout session required = ON（Logout Token 带 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt;）。&lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt; 存在时客户端只登出对应会话；无 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt; 时按 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;sub&lt;/code&gt; 登出该用户在这个 RP 上的所有会话。&lt;/li&gt;
&lt;li&gt;需要离线会话一并失效：Backchannel logout revoke offline sessions = ON。&lt;/li&gt;
&lt;li&gt;发起登出的客户端要登记回跳地址：&lt;code dir=&quot;auto&quot;&gt;post.logout.redirect.uris&lt;/code&gt;。取值语义为——&lt;code dir=&quot;auto&quot;&gt;+&lt;/code&gt; 或留空表示复用 Valid redirect URIs；&lt;code dir=&quot;auto&quot;&gt;-&lt;/code&gt; 表示不允许任何登出回跳；支持 &lt;code dir=&quot;auto&quot;&gt;http://example.com/*&lt;/code&gt; 这类简单通配，也支持相对路径（相对 client root URL；未设 root URL 时相对 Keycloak 根地址）。&lt;/li&gt;
&lt;li&gt;不要往登出回跳地址里塞 OIDC 保留参数。Keycloak 默认对 &lt;code dir=&quot;auto&quot;&gt;post_logout_redirect_uri&lt;/code&gt; 也执行 forbidden params 检查，&lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;code&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;error&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;session_state&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt; 等都会导致校验失败；需要传递状态请用登出请求自身的 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 参数，Keycloak 会原样带回。仅在明确需要兼容旧行为时才通过客户端属性 &lt;code dir=&quot;auto&quot;&gt;allow.oidc.params.in.redirect.uris&lt;/code&gt; 放开。&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h3 id=&quot;客户端应用端logout-token-的校验要点&quot;&gt;客户端应用端：Logout Token 的校验要点&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Back-Channel Logout 1.0 对 Logout Token 的要求是可以直接当验收清单用的：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;必须验签（与 ID Token 同一套密钥），可选加密；&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;iat&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;jti&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;events&lt;/code&gt; 均为 REQUIRED；&lt;code dir=&quot;auto&quot;&gt;events&lt;/code&gt; 必须包含成员 &lt;code dir=&quot;auto&quot;&gt;http://schemas.openid.net/event/backchannel-logout&lt;/code&gt;，这是「这是一张登出令牌」的唯一声明方式；&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;sub&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt; 至少存在一个，可以同时存在；&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;nonce&lt;/code&gt; 被规范明令禁止（PROHIBITED）&lt;/strong&gt;，目的是让 Logout Token 无法在伪造的认证响应里被当作 ID Token 使用（cross-JWT confusion）。校验时把它当作「出现即拒」的字段，而不是可选字段。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h3 id=&quot;oauth2-proxy-端sign_out-不等于-idp-登出&quot;&gt;oauth2-proxy 端：&lt;code dir=&quot;auto&quot;&gt;sign_out&lt;/code&gt; 不等于 IdP 登出&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;官方 Endpoints 文档写得很清楚：&lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; &lt;strong&gt;只清除 oauth2-proxy 自己的 Cookie&lt;/strong&gt;，用户仍登录在认证提供方，再次访问应用可能自动免登。要连 IdP 会话一起结束，必须把浏览器也送到 &lt;code dir=&quot;auto&quot;&gt;end_session_endpoint&lt;/code&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1) rd 参数，必须 URL 编码，指向 IdP 的 end_session_endpoint&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;https://app.example.com/oauth2/sign_out?rd&lt;/span&gt;&lt;span&gt;=https%3A%2F%2Fidp.example.com%2Frealms%2Fcorp%2Fprotocol%2Fopenid-connect%2Flogout%3Fpost_logout_redirect_uri%3Dhttps%253A%252F%252Fapp.example.com%252Flogged-out&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2) 或使用响应头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;GET&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/oauth2/sign_out&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;HTTP/1.1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;X-Auth-Request-Redirect:&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://idp.example.com/realms/corp/protocol/openid-connect/logout?post_logout_redirect_uri=https://app.example.com/logged-out&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;两个配套参数缺一不可：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--whitelist-domain&lt;/code&gt;：目标域名必须加进白名单，且要写「域名[:端口]」，不要带 scheme。官方文档特别提示「写 &lt;code dir=&quot;auto&quot;&gt;localhost:8081&lt;/code&gt; 而不是 &lt;code dir=&quot;auto&quot;&gt;http://localhost:8081&lt;/code&gt;」，写错时跳转会被静默忽略——这正是「配置看起来对，但就是没跳」的常见原因。&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;{id_token}&lt;/code&gt; 占位符：可把当前会话的 ID Token 注入跳转 URL，用来携带 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;：
&lt;code dir=&quot;auto&quot;&gt;.../logout?id_token_hint={id_token}&amp;#x26;post_logout_redirect_uri=https://app.example.com/logged-out&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果登出由服务端触发、不需要浏览器参与，可用 &lt;code dir=&quot;auto&quot;&gt;--backend-logout-url&lt;/code&gt;（同样支持 &lt;code dir=&quot;auto&quot;&gt;{id_token}&lt;/code&gt;）在清理本地会话时直接请求登出端点。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;为什么-keycloak-会返回-400-或停在确认页&quot;&gt;为什么 Keycloak 会返回 400 或停在确认页&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;下面是 Keycloak &lt;code dir=&quot;auto&quot;&gt;LogoutEndpoint&lt;/code&gt; 的实际判定，症状可以直接对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;现象&lt;/th&gt;
&lt;th&gt;触发条件&lt;/th&gt;
&lt;th&gt;处理&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;400，日志 &lt;code dir=&quot;auto&quot;&gt;Either the parameter &apos;client_id&apos; or the parameter &apos;id_token_hint&apos; is required when &apos;post_logout_redirect_uri&apos; is used.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;带了 &lt;code dir=&quot;auto&quot;&gt;post_logout_redirect_uri&lt;/code&gt;，但既没有 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt; 也没有 &lt;code dir=&quot;auto&quot;&gt;client_id&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;两者至少补一个，优先补 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;400，日志 &lt;code dir=&quot;auto&quot;&gt;Parameter client_id is different than the client for which ID Token was issued.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;client_id&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt; 指向不同客户端&lt;/td&gt;
&lt;td&gt;统一为同一客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;400 &lt;code dir=&quot;auto&quot;&gt;Invalid redirect uri&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;post_logout_redirect_uri&lt;/code&gt; 不在该客户端的 Valid post logout redirect URIs 内，或含被禁止的参数&lt;/td&gt;
&lt;td&gt;登记回跳地址；去掉 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 等保留参数&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;被强制要求确认登出&lt;/td&gt;
&lt;td&gt;未带 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;；或 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt; 所属客户端在 Realm 中查不到；或浏览器当前会话与 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt; 的会话状态不一致&lt;/td&gt;
&lt;td&gt;带上当前会话的 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;停在 “You are logged out” 不自动跳转&lt;/td&gt;
&lt;td&gt;客户端开启了 &lt;code dir=&quot;auto&quot;&gt;logout.confirmation.enabled&lt;/code&gt;（Keycloak 26.5 引入）：确认页给的是继续跳转的链接/按钮，而不是自动 302&lt;/td&gt;
&lt;td&gt;关闭该开关；或接受用户多点一次&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;无提示直接跳回，跳过了确认&lt;/td&gt;
&lt;td&gt;浏览器无会话、无 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;，但有 &lt;code dir=&quot;auto&quot;&gt;client_id&lt;/code&gt; 且回跳地址有效&lt;/td&gt;
&lt;td&gt;属预期行为，无需处理&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;规范层面的两点补充，能解释不少「行为不一致」的抱怨：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt; 在 RP-Initiated Logout 中是 RECOMMENDED，不是可有可无。OP 在 ID Token 已过期时&lt;strong&gt;仍应&lt;/strong&gt;接受它，只要其 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt; 表明存在当前或近期会话；反之，若 &lt;code dir=&quot;auto&quot;&gt;sid&lt;/code&gt; 与当前及近期会话都不匹配，OP 应视为可疑请求并可以拒绝执行。&lt;/li&gt;
&lt;li&gt;未提供 &lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;，或 ID Token 不属于当前会话时，OP &lt;strong&gt;必须&lt;/strong&gt;询问用户是否同时登出 OP。因此「不带任何参数的 &lt;code dir=&quot;auto&quot;&gt;/logout&lt;/code&gt; 静默登出所有应用」在规范预期里并不成立。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;管理员吊销会话时谁会收到通知&quot;&gt;管理员吊销会话时，谁会收到通知&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Admin Console 的 “Sign out all active sessions” 对应 admin REST 的 &lt;code dir=&quot;auto&quot;&gt;POST /admin/realms/{realm}/users/{id}/logout&lt;/code&gt;。它的实际行为是：逐个用户会话触发 back-channel 登出，并把该用户的 not-before 设为当前时间，使已签发 Token 失效。&lt;/p&gt;
&lt;p&gt;两个前提条件容易漏：目标客户端必须配了 backchannel logout URL（或旧的 &lt;code dir=&quot;auto&quot;&gt;Admin URL&lt;/code&gt;）；只配 front-channel 的客户端不会收到任何通知。改完之后要在两处对账——Keycloak 的 LOGOUT 事件，以及客户端侧的 &lt;code dir=&quot;auto&quot;&gt;logout_token&lt;/code&gt; POST 记录；只看到其中一处，说明链路没走完。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;验证清单&quot;&gt;验证清单&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 确认登出端点存在（以实际 Discovery 返回为准，不要凭版本猜路径）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://idp.example.com/realms/corp/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;.end_session_endpoint&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 触发登出，观察状态码与 Location，以及会话 Cookie 是否被清除&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-sS&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-D-&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;&quot;https://idp.example.com/realms/corp/protocol/openid-connect/logout?client_id=app-a&amp;#x26;post_logout_redirect_uri=https://app.example.com/logged-out&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;head&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-20&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 确认客户端侧真的收到 Logout Token（按实际日志路径调整）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/app-a&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;backchannel\|logout_token&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 4. 只看字段、不做验签：确认 events 存在、sid 是否存在、nonce 不存在&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;echo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$LOGOUT_TOKEN&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cut&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d.&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-f2&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;base64&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;{iss,aud,sub,sid,jti,events,nonce}&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;第 4 步只用于核对字段，不能替代验签与 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;/时间窗口校验。逐项确认顺序建议：Discovery 端点 → 回跳白名单 → 客户端 URL 与 channel 开关 → 客户端端点可达性与校验逻辑。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;常见错误对照表&quot;&gt;常见错误对照表&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;证据&lt;/th&gt;
&lt;th&gt;根因&lt;/th&gt;
&lt;th&gt;修复&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;应用 B 会话残留&lt;/td&gt;
&lt;td&gt;客户端无任何登出请求记录&lt;/td&gt;
&lt;td&gt;该客户端没配 backchannel logout URL，也没有 &lt;code dir=&quot;auto&quot;&gt;Admin URL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;配置 URL（并确保从 Keycloak 可达）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配了 Backchannel URL 仍不发请求&lt;/td&gt;
&lt;td&gt;Keycloak 侧无出站请求&lt;/td&gt;
&lt;td&gt;Front channel logout 开关仍为 ON&lt;/td&gt;
&lt;td&gt;关闭开关，切到 back-channel 分支&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;管理员吊销后应用仍可访问&lt;/td&gt;
&lt;td&gt;无 &lt;code dir=&quot;auto&quot;&gt;logout_token&lt;/code&gt;，仅令牌过期后失效&lt;/td&gt;
&lt;td&gt;校验只覆盖了 front-channel 客户端&lt;/td&gt;
&lt;td&gt;关键应用改用 back-channel，或依赖短 access token 作为兜底&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 后又自动免登&lt;/td&gt;
&lt;td&gt;只见 &lt;code dir=&quot;auto&quot;&gt;_oauth2_proxy&lt;/code&gt; 被清，没有到 IdP 的跳转&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sign_out&lt;/code&gt; 不清 IdP 会话&lt;/td&gt;
&lt;td&gt;补 &lt;code dir=&quot;auto&quot;&gt;rd&lt;/code&gt; 参数或 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Redirect&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配了 &lt;code dir=&quot;auto&quot;&gt;rd&lt;/code&gt; 但仍不跳转&lt;/td&gt;
&lt;td&gt;浏览器无到 IdP 的请求&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--whitelist-domain&lt;/code&gt; 缺目标域名，或写成了带 scheme 的 URL&lt;/td&gt;
&lt;td&gt;改为 &lt;code dir=&quot;auto&quot;&gt;idp.example.com&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;idp.example.com:8443&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登出后停在 “You are logged out”&lt;/td&gt;
&lt;td&gt;页面含继续跳转按钮&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;logout.confirmation.enabled&lt;/code&gt; 已开启&lt;/td&gt;
&lt;td&gt;按产品预期关闭或保留&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登出请求稳定 400&lt;/td&gt;
&lt;td&gt;日志含上述三条错误文本之一&lt;/td&gt;
&lt;td&gt;参数组合非法或回跳地址未登记&lt;/td&gt;
&lt;td&gt;对照上一节逐条修正&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;如果登出链路改动后登录也开始失败，先检查是否误删了共用配置：Keycloak 的 client 与 redirect URI 校验同时服务登录与登出，&lt;code dir=&quot;auto&quot;&gt;Valid Redirect URIs&lt;/code&gt;、Audience mapper 被一并清空时，症状会表现为登录报错而非登出报错。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;回滚&quot;&gt;回滚&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;登出链路涉及三层独立开关，回滚时&lt;strong&gt;一次只回退一层&lt;/strong&gt;，每步后重跑上面的验证清单：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Keycloak 客户端配置：把 Front channel logout 开关恢复原值，清空新增的 logout URL，移除 &lt;code dir=&quot;auto&quot;&gt;post.logout.redirect.uris&lt;/code&gt; 中新增条目。&lt;/li&gt;
&lt;li&gt;网关参数：移除 &lt;code dir=&quot;auto&quot;&gt;rd&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Redirect&lt;/code&gt; 的改动与 &lt;code dir=&quot;auto&quot;&gt;--whitelist-domain&lt;/code&gt; 新增项，必要时回退到上一个 Deployment 版本（保留一份改动前的 ConfigMap 便于对照）。&lt;/li&gt;
&lt;li&gt;应用端点：先保留 backchannel logout 端点但改为记录日志不执行登出，确认没有误登出与错误告警后再决定是否下线。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;回滚判据是「登录恢复 + 登出行为回到改动前」，不是「没有报错」。仅把配置改回去而不验证，等于不知道是否真的恢复了。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;常见问题iam-单点登出&quot;&gt;常见问题（IAM 单点登出）&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;iam-单点登出slo和普通登出有什么区别&quot;&gt;IAM 单点登出（SLO）和普通登出有什么区别？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;普通登出只清应用自己的会话；SLO 要求把登出传播到同一 SSO 会话上的其他应用与 IdP 会话本身。在 OIDC 里，RP-Initiated Logout 负责「用户主动退出」这条路径，Back-Channel / Front-Channel Logout 负责「IdP 主动通知各应用」。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;keycloak-能同时对同一个客户端启用-front-channel-和-back-channel-吗&quot;&gt;Keycloak 能同时对同一个客户端启用 Front-Channel 和 Back-Channel 吗？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;不能。客户端上的 Front channel logout 开关决定使用哪一组配置，两种 URL 字段在同一客户端上互斥显示；同时需要两种行为时应拆分客户端，或让应用自行处理其中一种。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;oauth2-proxy-的-oauth2sign_out-为什么登不出-keycloak&quot;&gt;oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 为什么登不出 Keycloak？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;因为它只清 oauth2-proxy 自己的 Cookie。必须把浏览器继续导向 &lt;code dir=&quot;auto&quot;&gt;end_session_endpoint&lt;/code&gt;（&lt;code dir=&quot;auto&quot;&gt;rd&lt;/code&gt; 参数或 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Redirect&lt;/code&gt;），并确保 IdP 域名在 &lt;code dir=&quot;auto&quot;&gt;--whitelist-domain&lt;/code&gt; 中。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;登出后-access-token--refresh-token-会立即失效吗&quot;&gt;登出后 Access Token / Refresh Token 会立即失效吗？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;RP-Initiated Logout 结束的是 IdP 的 SSO 会话；已签发的 access token 在其 &lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 之前仍是自包含 JWT，是否立即失效取决于资源服务是否做 introspection、是否校验 not-before，或客户端是否撤销 Token。管理员吊销会话会同时设置用户级 not-before，覆盖范围更大。因此不能把「用户点了退出」当成「所有 Token 立刻作废」，高风险接口仍需后端独立校验。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;管理员如何强制某个用户下线&quot;&gt;管理员如何强制某个用户下线？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Admin Console 的 “Sign out all active sessions”（admin REST：&lt;code dir=&quot;auto&quot;&gt;POST /admin/realms/{realm}/users/{id}/logout&lt;/code&gt;），它会逐会话触发 back-channel 登出并设置 not-before。前提是目标客户端配置了 backchannel logout URL，否则应用侧只能等 Token 过期——而「过期」的确切时限由 SSO Session Max、Client Session Max 与 Access Token Lifespan 共同决定，见 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-session-timeouts/&quot;&gt;IAM 会话超时排错&lt;/a&gt;。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;关键来源&quot;&gt;关键来源&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://openid.net/specs/openid-connect-rpinitiated-1_0.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;OpenID Connect RP-Initiated Logout 1.0（Final）&lt;/a&gt;：&lt;code dir=&quot;auto&quot;&gt;end_session_endpoint&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;id_token_hint&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;post_logout_redirect_uri&lt;/code&gt; 与参数校验规则&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://openid.net/specs/openid-connect-backchannel-1_0.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;OpenID Connect Back-Channel Logout 1.0（incorporating errata set 1）&lt;/a&gt;：Logout Token 字段、&lt;code dir=&quot;auto&quot;&gt;nonce&lt;/code&gt; 禁令、&lt;code dir=&quot;auto&quot;&gt;backchannel_logout_uri&lt;/code&gt; 可达性限制&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.keycloak.org/docs/latest/server_admin/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak Server Administration Guide：OIDC Logout&lt;/a&gt;：四种登出机制、客户端 Logout settings 行为、&lt;code dir=&quot;auto&quot;&gt;Admin URL&lt;/code&gt; 的适用范围&lt;/li&gt;
&lt;li&gt;Keycloak 源码 &lt;code dir=&quot;auto&quot;&gt;LogoutEndpoint&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;UserResource&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;OIDCConfigAttributes&lt;/code&gt;（main 分支）：错误文本、确认页判定、客户端属性名与管理员登出实现&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy Endpoints 文档&lt;/a&gt;：&lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 语义、&lt;code dir=&quot;auto&quot;&gt;rd&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Redirect&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;--whitelist-domain&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;{id_token}&lt;/code&gt; 占位符&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>oauth2-proxy</category><category>auth</category></item><item><title>Keycloak + PgBouncer 排错：prepared statement does not exist 与通过环境变量配 JDBC URL 参数</title><link>https://idaas.xlabs.club/blog/keycloak-pgbouncer-prepared-statement/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-pgbouncer-prepared-statement/</guid><description>Keycloak 接 PgBouncer 事务池后报 prepared statement S_1 does not exist 的根因，以及用 KC_DB_URL_PROPERTIES 注入 prepareThreshold=0 的通用解法</description><pubDate>Thu, 16 Jul 2026 16:00:00 GMT</pubDate><content:encoded>&lt;p&gt;把 Keycloak 挂到 PgBouncer 后面几乎是标配。Keycloak 自己就维护着一个 Agroal 连接池，副本一扩，到 PostgreSQL 的连接数很容易爆。中间挡一层 PgBouncer，用事务级复用把上百条应用连接收敛到少量后端连接，连接数立刻就老实了。&lt;/p&gt;
&lt;p&gt;换上之后日志里多半会冒出这样一段：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;2026-07-15 03:43:59,266 WARN  [com.arjuna.ats.jta] (executor-thread-2) ARJUNA016039:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;onePhaseCommit on &amp;#x3C; ... &gt; (io.agroal.narayana.LocalXAResource@47a4c16f)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;failed with exception XAException.XA_RBROLLBACK:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;javax.transaction.xa.XAException: Error trying to transactionCommit local transaction:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;ERROR: prepared statement &quot;S_1&quot; does not exist&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at io.agroal.narayana.XAExceptionUtils.xaException(XAExceptionUtils.java:21)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at io.agroal.narayana.XAExceptionUtils.xaException(XAExceptionUtils.java:9)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at io.agroal.narayana.LocalXAResource.commit(LocalXAResource.java:73)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;Caused by: org.postgresql.util.PSQLException: ERROR: prepared statement &quot;S_1&quot; does not exist&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryExecutorImpl.java:2904)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.core.v3.QueryExecutorImpl.processResults(QueryExecutorImpl.java:2589)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.core.v3.QueryExecutorImpl.execute(QueryExecutorImpl.java:431)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.core.v3.QueryExecutorImpl.execute(QueryExecutorImpl.java:389)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.jdbc.PgConnection.executeTransactionCommand(PgConnection.java:998)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at org.postgresql.jdbc.PgConnection.commit(PgConnection.java:1020)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at io.agroal.pool.ConnectionHandler.transactionCommit(ConnectionHandler.java:367)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;at io.agroal.narayana.LocalXAResource.commit(LocalXAResource.java:70)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;... 53 more&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;真正要看的是最后那行 &lt;code dir=&quot;auto&quot;&gt;Caused by: ... ERROR: prepared statement &quot;S_1&quot; does not exist&lt;/code&gt;。上面那一长串 Narayana / Quarkus / Keycloak 的栈只是这行数据库错误的外包装——事务在提交阶段崩了，被 JTA 回滚。&lt;/p&gt;
&lt;p&gt;下面记一下这次怎么查的，以及一个比 &lt;code dir=&quot;auto&quot;&gt;prepareThreshold=0&lt;/code&gt; 本身更值得记住的套路：通过环境变量往 JDBC URL 上塞参数。这套做法跟 Keycloak 没绑死，任何用 pgjdbc、又允许通过环境变量拼 URL 的组件都能这么干。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;这报错到底怎么来的&quot;&gt;这报错到底怎么来的&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;把三件事摆到一起就清楚了。&lt;/p&gt;
&lt;p&gt;第一件，pgjdbc 默认会用服务端 prepared statement。同一条 SQL 被执行到第 5 次（&lt;code dir=&quot;auto&quot;&gt;prepareThreshold&lt;/code&gt; 默认值）之后，驱动会在 PostgreSQL 那边创建一个 prepared statement，名字就是 &lt;code dir=&quot;auto&quot;&gt;S_1&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;S_2&lt;/code&gt; 这种，之后直接复用，省掉解析和规划。这个 statement 是挂在某一条后端连接上的，属于那条连接的 session 级状态。&lt;/p&gt;
&lt;p&gt;第二件，PgBouncer 的事务池模式会换后端连接。&lt;code dir=&quot;auto&quot;&gt;pool_mode = transaction&lt;/code&gt; 下，一个事务跑完就把客户端连接还回池里，下一个事务可能被分到另一条到 PostgreSQL 的后端连接。这就是它能高复用的根本，但也意味着客户端看到的「同一条连接」，在不同事务背后其实是不同的 server connection。&lt;/p&gt;
&lt;p&gt;第三件自然就来了。客户端在连接 A 上建了 &lt;code dir=&quot;auto&quot;&gt;S_1&lt;/code&gt;，下一个事务被 PgBouncer 路由到连接 B，客户端以为自己还拿着 &lt;code dir=&quot;auto&quot;&gt;S_1&lt;/code&gt;，发了个 &lt;code dir=&quot;auto&quot;&gt;EXECUTE S_1&lt;/code&gt; 过去，但连接 B 上根本没这东西，PostgreSQL 直接回 &lt;code dir=&quot;auto&quot;&gt;prepared statement &quot;S_1&quot; does not exist&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;Keycloak 这里踩得特别准：它用 JPA + Narayana 管事务，提交时驱动要执行 &lt;code dir=&quot;auto&quot;&gt;COMMIT&lt;/code&gt;，而 &lt;code dir=&quot;auto&quot;&gt;COMMIT&lt;/code&gt; 这条语句在 pgjdbc 里也会走 prepared statement 路径——&lt;code dir=&quot;auto&quot;&gt;S_1&lt;/code&gt; 经常就是它。所以你会看到一个特别唬人的现象：报错的不是哪条业务 SQL，而是提交事务的 &lt;code dir=&quot;auto&quot;&gt;COMMIT&lt;/code&gt; 本身，外层就变成 &lt;code dir=&quot;auto&quot;&gt;onePhaseCommit ... failed&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;XA_RBROLLBACK&lt;/code&gt;。盯着业务 SQL 排查能浪费一下午。&lt;/p&gt;
&lt;p&gt;这事不是 Keycloak 的 bug，也不是 PgBouncer 配错了，是事务池型中间件和驱动端优化天生打架。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;修把-preparethreshold-关成-0&quot;&gt;修：把 prepareThreshold 关成 0&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;最省事的修法是让 pgjdbc 别在服务端建 prepared statement。&lt;code dir=&quot;auto&quot;&gt;prepareThreshold=0&lt;/code&gt; 就是干这个的，驱动退回每次发完整 SQL，没有任何跨事务的服务端状态，PgBouncer 随便换后端连接都不影响。&lt;/p&gt;
&lt;p&gt;Keycloak 这边对应一个环境变量：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;env&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_DB_URL_PROPERTIES&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;?prepareThreshold=0&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 拼装 JDBC URL 时会把 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL&lt;/code&gt; 和它接在一起，最终给驱动的是：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;jdbc:postgresql://pgbouncer.internal:6432/keycloak?prepareThreshold=0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;有个坑要注意。如果 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL&lt;/code&gt; 里已经带了别的查询参数，比如 &lt;code dir=&quot;auto&quot;&gt;?sslmode=require&lt;/code&gt;，那 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL_PROPERTIES&lt;/code&gt; 得用 &lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt; 接，不然拼出来 &lt;code dir=&quot;auto&quot;&gt;?sslmode=require?prepareThreshold=0&lt;/code&gt; 是个非法 URL：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;env&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_DB_URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;jdbc:postgresql://pgbouncer.internal:6432/keycloak?sslmode=require&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_DB_URL_PROPERTIES&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;&amp;#x26;prepareThreshold=0&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;重启 Pod，确认日志里不再刷 &lt;code dir=&quot;auto&quot;&gt;prepared statement &quot;S_*&quot; does not exist&lt;/code&gt;，事务提交就回来了。&lt;/p&gt;
&lt;p&gt;关掉服务端 prepared statement 不是没代价。每条 SQL 多一次 Parse，PostgreSQL 多做一次解析和规划。但 Keycloak 基本是短事务、固定 SQL，这点开销跟「连接数爆炸」和「事务提交失败」比，可以认。真要心疼 CPU，再去看后面那条升级 PgBouncer 1.21+ 的路。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;真正该记下来的往-jdbc-url-塞参数的套路&quot;&gt;真正该记下来的：往 JDBC URL 塞参数的套路&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;比 &lt;code dir=&quot;auto&quot;&gt;prepareThreshold=0&lt;/code&gt; 这个具体值更值得记的是「通过环境变量往 JDBC URL 上追加参数」这件事本身。这次 Keycloak 的解法就是个现成例子：不碰 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL&lt;/code&gt;、不改 &lt;code dir=&quot;auto&quot;&gt;keycloak.conf&lt;/code&gt;，单靠 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL_PROPERTIES&lt;/code&gt; 给 URL 尾巴接一个 &lt;code dir=&quot;auto&quot;&gt;prepareThreshold=0&lt;/code&gt;，问题就解了。任何用 JDBC、又允许用环境变量拼连接 URL 的组件，都是同一个套路——找到那个「数据库 URL 之外、专门用来追加查询参数」的开关，把参数塞进去。Keycloak 是 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL_PROPERTIES&lt;/code&gt;；Spring Boot 一般直接拼到 &lt;code dir=&quot;auto&quot;&gt;spring.datasource.url&lt;/code&gt;；Quarkus 是 &lt;code dir=&quot;auto&quot;&gt;quarkus.datasource.jdbc.url&lt;/code&gt;；纯 Hibernate 在 &lt;code dir=&quot;auto&quot;&gt;hibernate.connection.url&lt;/code&gt; 后面加；非 Java 的 libpq 走 &lt;code dir=&quot;auto&quot;&gt;PGOPTIONS&lt;/code&gt; 或连接串里的 &lt;code dir=&quot;auto&quot;&gt;options&lt;/code&gt;。位置不同，思路一致：找到能往连接字符串里塞参数的那个口子。&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt; 还是 &lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt;，规则就一条——看最终拼出来的 URL 里有没有 &lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt;。没有就用 &lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt;，有了就用 &lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt;。拼错了是连接异常，不会静默生效，错了也容易看出来。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;验证&quot;&gt;验证&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;按这个顺序看一眼：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Pod 真的带上新环境变量了&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-A1&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;KC_DB_URL_PROPERTIES&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 重启后还刷不刷 prepared statement&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=200&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;prepared statement&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 事务提交有没有恢复，ARJUNA016039 / XA_RBROLLBACK 应该消失&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=200&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;ARJUNA016039|XA_RBROLLBACK&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 压一波登录，确认登录、token 签发、会话落库都正常&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;报错不再刷、回滚也不再见，就算修好了。最好观察过一个扩缩容周期，PgBouncer 复用最狠的时段也稳，再收工。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;不想关-prepared-statement-的两条路&quot;&gt;不想关 prepared statement 的两条路&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;prepareThreshold=0&lt;/code&gt; 是改动最小的解。如果就是舍不得服务端 prepared statement，还有别的办法。&lt;/p&gt;
&lt;p&gt;一是升级 PgBouncer 到 1.21+，开 &lt;code dir=&quot;auto&quot;&gt;max_prepared_statements&lt;/code&gt;。新版本在事务池模式下会自己在客户端和后端连接之间维护 prepared statement 的映射，驱动还能继续享受那点收益。代价是要升 PgBouncer、搞懂新参数、确认版本配套，比加一个环境变量重得多。&lt;/p&gt;
&lt;p&gt;二是换成 session 池（&lt;code dir=&quot;auto&quot;&gt;pool_mode = session&lt;/code&gt;），一个客户端连接独占一条后端连接，prepared statement 自然不会丢。但这么一来 PgBouncer 基本退化成「最大连接数上限管理」，事务级复用这个主要价值没了，连接数收敛效果大打折扣。除非你本来的诉求就是卡上限而不是高复用，不然不划算。&lt;/p&gt;
&lt;p&gt;顺带一提，如果你压根没上 PgBouncer，是应用内连接池直连 PostgreSQL，这个 prepared statement 失效的问题不会出现——这事就是「事务池型中间件后面跑 pgjdbc」这一类组合特有的。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;排错判断&quot;&gt;排错判断&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;日志里是 &lt;code dir=&quot;auto&quot;&gt;prepared statement &quot;S_N&quot; does not exist&lt;/code&gt; 配 &lt;code dir=&quot;auto&quot;&gt;XA_RBROLLBACK&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;onePhaseCommit failed&lt;/code&gt; → 命中本问题，设 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL_PROPERTIES=?prepareThreshold=0&lt;/code&gt; 重启。&lt;/li&gt;
&lt;li&gt;同样报错，但 Keycloak 是直连 PostgreSQL、中间没 PgBouncer → 多半不是这个，查有没有别的复用/代理层，或 PostgreSQL 端连接被异常回收。&lt;/li&gt;
&lt;li&gt;报错没了但 SQL 解析变慢 → 修复生效的副作用，要么认了，要么走 PgBouncer 1.21+ 那条路。&lt;/li&gt;
&lt;li&gt;拼完 URL 之后建连阶段就报 &lt;code dir=&quot;auto&quot;&gt;SQLException&lt;/code&gt; → 八成是 &lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt; 接错了，看 &lt;code dir=&quot;auto&quot;&gt;KC_DB_URL&lt;/code&gt; 里是不是已经有 &lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;相关章节&quot;&gt;相关章节&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-postgresql-config/&quot;&gt;Keycloak 生产数据库配置指南&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/keycloak/troubleshooting/&quot;&gt;Keycloak 常见问题排查&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/implementation/kubernetes-production/&quot;&gt;Keycloak Kubernetes 生产部署&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;参考资料&quot;&gt;参考资料&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;PostgreSQL JDBC 驱动 prepared statement 文档：&lt;a href=&quot;https://jdbc.postgresql.org/documentation/use/#server-prepared-statements&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://jdbc.postgresql.org/documentation/use/#server-prepared-statements&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PgBouncer 1.21 prepared statement 支持说明：&lt;a href=&quot;https://github.com/pgbouncer/pgbouncer/blob/master/doc/config.md#max_prepared_statements&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://github.com/pgbouncer/pgbouncer/blob/master/doc/config.md#max_prepared_statements&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Keycloak 数据库配置环境变量：&lt;a href=&quot;https://www.keycloak.org/server/db&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/server/db&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PgBouncer pool mode 文档：&lt;a href=&quot;https://www.pgbouncer.org/config.html#pool_mode&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.pgbouncer.org/config.html#pool_mode&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>database</category></item><item><title>IAM 网关 oauth2-proxy 常见错误排错</title><link>https://idaas.xlabs.club/blog/oauth2-proxy-common-errors/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/oauth2-proxy-common-errors/</guid><description>IAM 网关 oauth2-proxy 集成 Keycloak 的 12 个高频错误排错：CSRF Cookie、expected audience、redirect loop、invalid_token 与 Nginx 401。</description><pubDate>Sun, 12 Jul 2026 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;场景&quot;&gt;场景&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;你按照文档配好了 oauth2-proxy + Keycloak，部署到 Kubernetes，打开浏览器——白屏、401、无限跳转、或者 “csrf cookie not found”。这些错误 oauth2-proxy 的日志里写得很直白，但&lt;strong&gt;为什么发生、怎么修&lt;/strong&gt;才是真正的卡点。&lt;/p&gt;
&lt;p&gt;这篇文章把 oauth2-proxy 的公开 Issue 与可复现的配置逻辑整理成速查表：每条有诊断命令、根因分析和修复步骤。Issue 只能说明问题曾被报告，不能替代当前版本的验证。需要先理解 auth-url、Header 复制和后端信任边界的整体链路，可先看 &lt;a href=&quot;https://idaas.xlabs.club/docs/implementation/oauth2-proxy-deep-dive/&quot;&gt;oauth2-proxy 深度介绍&lt;/a&gt; 的架构说明。&lt;/p&gt;
&lt;p&gt;适用：oauth2-proxy 7.15.x 文档所述配置 + Keycloak，auth-url 或 ForwardAuth 模式。参数行为仍以实际部署版本为准；不要把本文的版本范围当成兼容性承诺。&lt;/p&gt;
&lt;p&gt;不适用：oauth2-proxy 旧版（v6 及以下，部分参数名不同）、非 Keycloak Provider（GitHub/Google 等 Provider 有各自特有的错误）。Keycloak 使用旧版 &lt;code dir=&quot;auto&quot;&gt;/auth/realms/&lt;/code&gt; 上下文路径时，应以该实例 Discovery 返回的 &lt;code dir=&quot;auto&quot;&gt;issuer&lt;/code&gt; 为准；新部署常见的公开路径是 &lt;code dir=&quot;auto&quot;&gt;/realms/&lt;/code&gt;，不能只凭产品版本猜 URL。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;参数边界&lt;/strong&gt;：反向代理场景应同时设置 &lt;code dir=&quot;auto&quot;&gt;--reverse-proxy=true&lt;/code&gt; 和受控的 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt;。不要把“信任转发头”理解成“信任所有客户端发送的转发头”。oauth2-proxy 官方配置说明指出，未设置 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt; 时会为兼容旧行为而信任所有来源；能直连 oauth2-proxy 的客户端因此可能伪造 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;。本文参数以&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;官方配置文档&lt;/a&gt;为准。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;先验证网络边界，再看 Cookie 或 &lt;code dir=&quot;auto&quot;&gt;redirect_uri&lt;/code&gt;：oauth2-proxy Service 应使用 ClusterIP，网络策略只允许入口代理访问；不要把“能从 Pod 内 curl 通”误当成“公网路径和转发头可信”。如果入口代理的地址来自节点、云负载均衡或多个网段，应以实际连接来源和部署文档为准逐项收敛，不能直接填整个 VPC。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 示例：网段必须替换为实际 ingress-nginx/Traefik 的来源地址&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--reverse-proxy=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--trusted-proxy-ip=10.42.0.0/16&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;这条检查适用于 &lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-oauth2-proxy/&quot;&gt;Keycloak + oauth2-proxy 集成&lt;/a&gt;、&lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/traefik-forwardauth-keycloak/&quot;&gt;Traefik ForwardAuth&lt;/a&gt; 和 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/&quot;&gt;Keycloak 重定向循环排错&lt;/a&gt;；三者的入口组件不同，但转发头的信任边界相同。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;错误速查导航&quot;&gt;错误速查导航&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;错误关键词&lt;/th&gt;
&lt;th&gt;出现阶段&lt;/th&gt;
&lt;th&gt;严重程度&lt;/th&gt;
&lt;th&gt;跳转&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;csrf cookie not found&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录回调&lt;/td&gt;
&lt;td&gt;🔴 阻断&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#1-csrf-cookie-not-found&quot;&gt;错误 1&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;expected audience&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Token 校验&lt;/td&gt;
&lt;td&gt;🔴 阻断&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#2-expected-audience-got-account&quot;&gt;错误 2&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;redirect loop&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录后&lt;/td&gt;
&lt;td&gt;🔴 阻断&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#3-%E7%99%BB%E5%BD%95%E5%90%8E%E6%97%A0%E9%99%90%E9%87%8D%E5%AE%9A%E5%90%91-redirect-loop&quot;&gt;错误 3&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invalid_token&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Token 校验&lt;/td&gt;
&lt;td&gt;🔴 阻断&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#4-invalid_token&quot;&gt;错误 4&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;missing state parameter&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录回调&lt;/td&gt;
&lt;td&gt;🔴 阻断&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#5-missing-state-parameter&quot;&gt;错误 5&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;cookie too large&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;登录回调&lt;/td&gt;
&lt;td&gt;🟡 部分用户&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#6-cookie-too-large&quot;&gt;错误 6&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;401&lt;/code&gt; 已登录却被拒&lt;/td&gt;
&lt;td&gt;请求阶段&lt;/td&gt;
&lt;td&gt;🟡 间歇性&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#7-401-%E5%B7%B2%E7%99%BB%E5%BD%95%E4%BD%86%E8%AE%A4%E8%AF%81%E8%A2%AB%E6%8B%92&quot;&gt;错误 7&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;could not get claim: missing claim &quot;email&quot;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Token 校验&lt;/td&gt;
&lt;td&gt;🟡 特定用户&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#8-missing-claim-email&quot;&gt;错误 8&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;error=access_denied&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Keycloak 端&lt;/td&gt;
&lt;td&gt;🟡 配置&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#9-erroraccess_denied&quot;&gt;错误 9&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Nginx 503&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;no live upstreams&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;请求阶段&lt;/td&gt;
&lt;td&gt;🟡 基础设施&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#10-nginx-ingress-%E8%BF%94%E5%9B%9E-503&quot;&gt;错误 10&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cookie 只在主域名生效，子域名不行&lt;/td&gt;
&lt;td&gt;跨子域&lt;/td&gt;
&lt;td&gt;🟡 配置&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#11-cookie-%E8%B7%A8%E5%AD%90%E5%9F%9F%E4%B8%8D%E7%94%9F%E6%95%88&quot;&gt;错误 11&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登出一个应用导致全部退出&lt;/td&gt;
&lt;td&gt;共享 session&lt;/td&gt;
&lt;td&gt;🟢 体验&lt;/td&gt;
&lt;td&gt;&lt;a href=&quot;#12-%E7%99%BB%E5%87%BA%E4%B8%80%E4%B8%AA%E5%BA%94%E7%94%A8%E5%85%A8%E9%83%A8%E9%80%80%E5%87%BA&quot;&gt;错误 12&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;1-csrf-cookie-not-found&quot;&gt;1. csrf cookie not found&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志典型输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oauth2-proxy[1] &amp;#x3C;timestamp&gt; &amp;#x3C;request&gt; 403 csrf cookie not found&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：oauth2-proxy 在发起 OAuth 授权请求前，会生成一个 &lt;code dir=&quot;auto&quot;&gt;_oauth2_proxy_csrf&lt;/code&gt; Cookie，用于把回调与此前的授权请求关联起来。OAuth Provider（Keycloak）回调时，浏览器必须把这个 Cookie 带回 &lt;code dir=&quot;auto&quot;&gt;/oauth2/callback&lt;/code&gt;。以下任何一环断了都会触发这个错误：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Cookie 被浏览器拒绝&lt;/strong&gt;：SameSite 过严 / Secure 标记与 HTTP 不匹配 / Domain 不匹配&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cookie 路径不匹配&lt;/strong&gt;：CSRF Cookie 默认 path 为 &lt;code dir=&quot;auto&quot;&gt;/&lt;/code&gt;，但如果被反向代理改写可能出现不一致&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;HTTPS 前端 → HTTP 后端的转发头错误&lt;/strong&gt;：浏览器访问的是 HTTPS，但入口没有把 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto: https&lt;/code&gt; 传给 oauth2-proxy；不要仅因 Pod 内部监听 HTTP 就关闭 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cookie Domain 不覆盖回调主机&lt;/strong&gt;：例如应用在 &lt;code dir=&quot;auto&quot;&gt;a.example.com&lt;/code&gt;，认证入口在 &lt;code dir=&quot;auto&quot;&gt;auth.example.com&lt;/code&gt;，但 Cookie 没有显式设置共享父域&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;还有一个容易被误判成“Cookie 随机丢失”的分支：同一个浏览器同时发起多个未认证请求。默认情况下，oauth2-proxy 不为每个请求创建独立的 CSRF Cookie；多个标签页、前端并行加载资源，或用户连续点击登录，都可能让较早的 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 与回调不再对应。若日志同时出现 &lt;code dir=&quot;auto&quot;&gt;csrf cookie not found&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;state mismatch&lt;/code&gt;，并且响应头已经成功写入 CSRF Cookie，优先检查这个并发场景，而不是先扩大 Cookie Domain。&lt;/p&gt;
&lt;p&gt;先区分三个经常混用的词：&lt;strong&gt;跨域（origin）不等于跨站（site），也不等于跨子域 Cookie&lt;/strong&gt;。&lt;code dir=&quot;auto&quot;&gt;app.example.com&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;auth.example.com&lt;/code&gt; 是不同 origin，但在同一注册域和同一 scheme 下通常属于同一 site；&lt;code dir=&quot;auto&quot;&gt;SameSite&lt;/code&gt; 主要控制 Cookie 是否随跨 site 请求发送，不能代替 CORS 配置。反过来，如果登录入口和应用使用不同注册域，或 scheme 不同，不能因为两者“都是 HTTPS”就假设 &lt;code dir=&quot;auto&quot;&gt;SameSite=Lax&lt;/code&gt; 会放行。判断时同时记录浏览器实际的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt;、请求的 &lt;code dir=&quot;auto&quot;&gt;Origin/Referer&lt;/code&gt;、Cookie 的 &lt;code dir=&quot;auto&quot;&gt;Domain/Path/SameSite/Secure&lt;/code&gt;，不要只看地址栏上的主机名。可参阅 &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN：Set-Cookie 的 SameSite 语义&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;这里的 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 不是“登录成功标记”，而是把授权请求和回调绑定起来的不透明值。RFC 6749 §4.1.1 要求客户端在授权请求中携带它，§4.1.2 要求授权服务器在回调中原样返回；§10.12 建议用它防御 CSRF。因此，回调找不到对应 Cookie 时不能靠关闭校验解决。oauth2-proxy 的 &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3258&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Issue #3258&lt;/a&gt; 记录了多标签页复现；另一个 Traefik &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; 中间件案例 &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3463&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Issue #3463&lt;/a&gt; 已关闭，但它只说明该具体版本和拓扑的行为，不能替代对当前部署的验证。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;多标签页或并行请求启用按请求创建-csrf-cookie&quot;&gt;多标签页或并行请求：启用按请求创建 CSRF Cookie&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果确认浏览器确实收到 CSRF Cookie，且问题只在多个标签页或并行跳转时出现，可以让每次未认证请求使用独立的 CSRF Cookie：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-csrf-per-request=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 只在确实出现 431 或请求头过大时设置；数值按并行登录场景压测后确定&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-csrf-per-request-limit=10&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;这是针对并发授权请求的配置，不是 Cookie Domain、SameSite 或多副本会话问题的通用修复。官方配置说明中该开关默认为 &lt;code dir=&quot;auto&quot;&gt;false&lt;/code&gt;；设置上限后，最旧的 CSRF Cookie 会被移除，以避免浏览器请求头无限增长。验证时打开两个标签页，分别让登录流程完成，并确认每个回调都带有对应的 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt;；随后检查 oauth2-proxy 日志不再出现 &lt;code dir=&quot;auto&quot;&gt;state mismatch&lt;/code&gt;。如果开启后出现 &lt;code dir=&quot;auto&quot;&gt;431 Request Header Fields Too Large&lt;/code&gt;，先降低并发上限或恢复默认值，再处理真正的并行登录需求。回滚只需移除这两个参数并滚动更新，但未完成的登录流程需要重新发起。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 看 oauth2-proxy 日志确认错误来源&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=20&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;csrf&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 用浏览器 DevTools 看 Cookie 是否被写入&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Application → Cookies → 检查以 oauth2-proxy 为前缀的 CSRF Cookie 是否存在&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 默认名称会带 state 相关的后缀；启用 --cookie-csrf-per-request=true 后每次请求的名称也不同&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果 CSRF Cookie 缺失，再看 Console 是否有 SameSite/Secure 警告&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 检查 oauth2-proxy 启动参数中的 Cookie 配置&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;cookie-secure|cookie-samesite|cookie-domain|ssl-upstream-insecure-skip-verify&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 4. 从入口代理所在位置检查转发头；不要只看 oauth2-proxy Pod 内的请求&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress-nginx&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/ingress-nginx-controller&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;oauth2|X-Forwarded-Proto&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 5. 检查 oauth2-proxy 是否限制了可信代理来源&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;reverse-proxy|trusted-proxy-ip&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;先保持浏览器访问、Keycloak 回调和 &lt;code dir=&quot;auto&quot;&gt;redirect_uri&lt;/code&gt; 全部使用 HTTPS。TLS 在 Ingress/LB 终结并不意味着要关闭 Cookie 的 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt; 属性；应让入口代理正确传递 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto: https&lt;/code&gt;，并只信任入口代理的地址段。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy 启动参数调整&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak 回调通常需要 Lax；只有明确需要跨站 Cookie 时才考虑 None（且必须 Secure）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-samesite=lax&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-secure=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 确保 Cookie Domain 覆盖回调域名；单域名部署可省略此项&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-domain=.example.com&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--reverse-proxy=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 换成实际 Ingress/LB 的 Pod 网段或固定出口 CIDR，不要照抄示例&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--trusted-proxy-ip=10.42.0.0/16&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--reverse-proxy=true&lt;/code&gt; 只表示按反向代理场景处理请求；它不应被当成“任意客户端都可以提交可信转发头”。oauth2-proxy 当前配置文档说明，未设置 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt; 时出于兼容性会信任所有来源，这允许能够直连 oauth2-proxy 的客户端伪造 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;。这不只是 redirect_uri 显示错误：公开 issue &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3506&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;#3506&lt;/a&gt; 描述了在 v7.15.3 及更早版本中，伪造 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Uri&lt;/code&gt; 可能影响 &lt;code dir=&quot;auto&quot;&gt;skip_auth_routes&lt;/code&gt; 的匹配；相关修复 PR &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/pull/3509&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;#3509&lt;/a&gt; 截至本页更新仍未合入。因此，升级版本不能替代收紧信任边界。&lt;/p&gt;
&lt;p&gt;生产环境应限制 NetworkPolicy/Service 暴露面，并配置实际代理的 IP/CIDR；如果代理地址是动态变化的，优先固定出口或用网络层阻断直连，而不是放大信任范围。升级或修改信任配置后，必须用“直连 oauth2-proxy + 伪造 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Uri&lt;/code&gt;”的请求验证未认证请求仍返回 401；不要只验证正常入口能登录。&lt;/p&gt;
&lt;p&gt;如果同时启用 &lt;code dir=&quot;auto&quot;&gt;--trusted-ip&lt;/code&gt; 作为认证绕过白名单，必须单独审查 &lt;code dir=&quot;auto&quot;&gt;--real-client-ip-header&lt;/code&gt; 的来源链：客户端可直接到达 oauth2-proxy 时，不应信任它提交的 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-For&lt;/code&gt;。oauth2-proxy 当前仍有关于沿代理链解析该 Header 的安全改进 PR（&lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/pull/3478&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;#3478&lt;/a&gt;，截至本页更新尚未合入）；在确认所用版本已包含修复前，优先不要用基于转发头的 &lt;code dir=&quot;auto&quot;&gt;--trusted-ip&lt;/code&gt; 绕过认证，或在网络层保证只有受控代理能访问该服务。&lt;/p&gt;
&lt;p&gt;如果确实在没有 HTTPS 的本地开发环境运行，才临时使用 &lt;code dir=&quot;auto&quot;&gt;--cookie-secure=false&lt;/code&gt;；不要把这个开关作为生产环境 TLS 终结后的修复。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;验证修复&lt;/strong&gt;：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;清除浏览器所有 Cookie（DevTools → Application → Clear site data）&lt;/li&gt;
&lt;li&gt;重新访问应用 URL&lt;/li&gt;
&lt;li&gt;观察 Network 面板：&lt;code dir=&quot;auto&quot;&gt;/oauth2/start&lt;/code&gt; 的响应头应有以 &lt;code dir=&quot;auto&quot;&gt;_oauth2_proxy&lt;/code&gt; 开头的 CSRF &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt;；不要只按固定的 &lt;code dir=&quot;auto&quot;&gt;_oauth2_proxy_csrf&lt;/code&gt; 名称搜索&lt;/li&gt;
&lt;li&gt;登录完成后不应再出现 403&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;如果问题只在并行登录或多个标签页复现，可以显式为每个授权请求启用独立 CSRF Cookie。注意：该开关改变的是 Cookie 名称和数量，不是把同一个固定 Cookie 覆盖得更快：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-csrf-per-request=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 只在确认浏览器/代理出现 431 Request Header Fields Too Large 时设置上限；&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 上限过小会让较早的并行登录请求失效&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-csrf-per-request-limit=10&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--cookie-csrf-per-request-limit&lt;/code&gt; 只有在 &lt;code dir=&quot;auto&quot;&gt;--cookie-csrf-per-request=true&lt;/code&gt; 时生效；它限制 oauth2-proxy 保留的并行 CSRF Cookie 数量，超出后删除最早的 Cookie。官方配置文档将默认值列为无限制，并明确说明该上限用于避免 Cookie 数量增长导致 &lt;code dir=&quot;auto&quot;&gt;431 Request Header Fields Too Large&lt;/code&gt;。先不设置上限通常更容易验证根因，但生产环境应结合浏览器并发行为和代理 Header 大小限制决定是否加上限。改动后清理旧 Cookie，再用两个标签页同时访问受保护 URL，确认两次回调都能完成；若出现 431，回到上限、Cookie Domain 和代理 Header 限制一起检查。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;traefik-errors-中间件造成的并发-csrf-覆盖&quot;&gt;Traefik &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; 中间件造成的并发 CSRF 覆盖&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果使用 Traefik &lt;code dir=&quot;auto&quot;&gt;ForwardAuth&lt;/code&gt;，再用 &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt; 中间件把 401 重定向到 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_in&lt;/code&gt;，不要只测试“点击登录”这一条路径。页面加载时的 JavaScript、CSS、favicon 或 Service Worker 可能同时触发多个未认证请求；在 &lt;code dir=&quot;auto&quot;&gt;--skip-provider-button=true&lt;/code&gt; 时，这些请求可能各自启动授权流程并反复写入 CSRF Cookie。最后一个 Cookie 与浏览器正在完成的较早授权请求不匹配，就会得到 &lt;code dir=&quot;auto&quot;&gt;CSRF token mismatch&lt;/code&gt;，看起来像随机故障，实际是竞态。&lt;/p&gt;
&lt;p&gt;先看浏览器 Network 面板和 oauth2-proxy 访问日志：如果一次页面加载出现多个 &lt;code dir=&quot;auto&quot;&gt;/oauth2/start&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_in&lt;/code&gt;，并且它们连续返回 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie: _oauth2_proxy_csrf=...&lt;/code&gt;，就不要先改 SameSite 或加 Redis。可控的修复顺序是：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;暂时将 &lt;code dir=&quot;auto&quot;&gt;--skip-provider-button=false&lt;/code&gt;，让 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_in&lt;/code&gt; 只展示登录页，由用户的一次明确导航触发 &lt;code dir=&quot;auto&quot;&gt;/oauth2/start&lt;/code&gt;；这是降低并发启动的诊断和缓解措施，不是对所有代理拓扑的永久保证。&lt;/li&gt;
&lt;li&gt;在确认确实需要并行授权后，再启用 &lt;code dir=&quot;auto&quot;&gt;--cookie-csrf-per-request=true&lt;/code&gt;，并按代理 Header 大小设置 &lt;code dir=&quot;auto&quot;&gt;--cookie-csrf-per-request-limit&lt;/code&gt;；不要无限制地把 Cookie 数量调大。&lt;/li&gt;
&lt;li&gt;把静态资源和 Service Worker 的未认证请求从错误重定向链路中排除，或让入口只对页面导航触发登录。验证时保留浏览器 Network 日志，确认一次登录只产生预期的授权请求。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这个现象已有 oauth2-proxy issue &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3463&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;#3463&lt;/a&gt; 的复现记录；该 issue 报告的版本和 Traefik 版本属于具体案例，不能据此推断所有版本都相同。最终应以所部署版本的行为为准。关于子域名场景下 CSRF Cookie 不出现的另一类排查线索，可参阅 &lt;a href=&quot;https://stackoverflow.com/questions/77504002/oauth2-proxy-and-subdomains-unable-to-obtain-csrf-cookie&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Stack Overflow 问题&lt;/a&gt;，但不要把社区问答当作配置规范。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;cookie-名称前缀导致浏览器拒收&quot;&gt;Cookie 名称前缀导致浏览器拒收&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果日志显示 oauth2-proxy 找不到 CSRF Cookie，但 Network 面板中的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt; 已经返回，继续检查 Cookie 名称本身。&lt;code dir=&quot;auto&quot;&gt;--cookie-csrf-per-request=true&lt;/code&gt; 会把 CSRF 后缀拼到 Cookie 名称上；设置 &lt;code dir=&quot;auto&quot;&gt;--cookie-name=__Host-&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;__Host-Http-&lt;/code&gt; 时，最终名称可能变成 &lt;code dir=&quot;auto&quot;&gt;__Host-_abc123_csrf&lt;/code&gt;。这不再满足浏览器对 &lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; 前缀的约束，浏览器会直接拒收，服务端随后只能报告“找不到 Cookie”。oauth2-proxy Issue &lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3258&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;#3258&lt;/a&gt; 中记录了这一类现象；它是当前实现与 Cookie 前缀规则的组合问题，不是把 &lt;code dir=&quot;auto&quot;&gt;--cookie-domain&lt;/code&gt; 改成通配符就能解决的。&lt;/p&gt;
&lt;p&gt;排查时在浏览器 Console/Storage 中确认 Cookie 是否被拒绝，并临时使用普通名称验证：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-name=_oauth2_proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-csrf-per-request=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;如果普通名称能够完成回调，再决定是否需要安全前缀。不要为了保留 &lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; 前缀而关闭 CSRF 校验；如果必须使用前缀，应先在目标 oauth2-proxy 版本中验证其派生 CSRF 名称仍符合浏览器规则，并把浏览器实际收到的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt; 作为验收证据。回滚是恢复原 Cookie 名称并滚动更新；更新后清理旧 Cookie，未完成的授权流程需要重新发起。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;常见误区&lt;/strong&gt;：看到多副本就立刻加 Redis。这里有一个容易把排错方向带偏的细节：&lt;strong&gt;默认 Cookie Session Store 并不要求回调落到同一个 Pod&lt;/strong&gt;。只要多个副本使用相同的 &lt;code dir=&quot;auto&quot;&gt;--cookie-secret&lt;/code&gt;，各副本都能解密由其他副本签发的会话 Cookie；把“多副本”直接等同于“必须上 Redis”会平白增加一个运行依赖。当前 oauth2-proxy 文档将 &lt;code dir=&quot;auto&quot;&gt;cookie&lt;/code&gt; 列为默认 Session Store，&lt;code dir=&quot;auto&quot;&gt;redis&lt;/code&gt; 是另一种可选后端。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;只有在以下情况才优先考虑 Redis：Cookie 体积超过浏览器或代理限制、需要服务端集中撤销会话，或希望不把 OAuth Token 放进 Cookie。迁移时先保留相同的外部回调地址和 Cookie 参数，在灰度副本上启用 Redis，并为 Redis 配置 TLS、认证、超时和监控；不要把 &lt;code dir=&quot;auto&quot;&gt;--redis-insecure-skip-tls-verify=true&lt;/code&gt; 当成生产修复。另外，Redis 里存的是会话数据，不是会话的「永久续期券」：能刷新多久最终由 Keycloak 侧的会话上限决定，网关 Cookie 有效期设得比 IdP 会话长只会换来一次失败的刷新，相关字段与校验见 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-session-timeouts/&quot;&gt;IAM 会话超时排错&lt;/a&gt;。最小配置形态如下（连接字符串和密码放 Secret，不要写入 Git）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--session-store-type=redis&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--redis-connection-url=rediss://&amp;#x3C;redis-host&gt;:&amp;#x3C;port&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 按部署版本确认对应的密码参数；不要把密码拼进公开的命令示例或日志&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--redis-password=$(REDIS_PASSWORD)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;验证顺序&lt;/strong&gt;：先看 oauth2-proxy 启动日志确认 Session Store 初始化成功，再用浏览器完成一次全新的登录，最后滚动重启一个副本并访问受保护应用。如果 Redis 不可用，回滚到 &lt;code dir=&quot;auto&quot;&gt;--session-store-type=cookie&lt;/code&gt; 前要评估已有 Redis 会话是否失效；这不是无损切换，最好安排在可接受重新登录的维护窗口。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;2-expected-audience-got-account&quot;&gt;2. expected audience got [“account”]&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志典型输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oauth2-proxy[1] &amp;#x3C;timestamp&gt; &amp;#x3C;request&gt; 401 error validating token:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oidc: expected audience &quot;oauth2-proxy&quot; got [&quot;account&quot;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：oauth2-proxy 的 OIDC 校验会按 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;（audience）检查 ID Token 的接收方；当前配置文档中，&lt;code dir=&quot;auto&quot;&gt;--oidc-audience-claim&lt;/code&gt; 默认读取 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;，而 &lt;code dir=&quot;auto&quot;&gt;--oidc-extra-audience&lt;/code&gt; 只是额外允许的 audience。Keycloak 只把 &lt;code dir=&quot;auto&quot;&gt;account&lt;/code&gt; 放进 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 时，Token 没有包含 oauth2-proxy 的 Client ID，因此会被拒绝。不要把这个错误归因于某个固定版本号：应以实际运行镜像的启动参数和配置文档为准。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断-1&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 解码 ID Token 查看 aud 字段（在浏览器 DevTools → Network → /oauth2/callback 中找到 id_token）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;echo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&amp;#x3C;id_token&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cut&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d.&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-f2&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;base64&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;.aud&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 预期输出包含 oauth2-proxy 的 client ID，例如 [&quot;account&quot;, &quot;oauth2-proxy&quot;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果只有 [&quot;account&quot;]，先确认回调实际使用的 client_id；只有在确认登录的是该客户端后，&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 才能判断是缺 Audience Mapper 或 mapper 没绑定到实际生效的 Client Scope&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-1&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;在 Keycloak Admin Console 中：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;进入目标 Realm → Clients → &lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Client scopes&lt;/strong&gt; 标签 → 点击 &lt;code dir=&quot;auto&quot;&gt;oauth2-proxy-dedicated&lt;/code&gt;（或你用的 scope）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Add mapper&lt;/strong&gt; → &lt;strong&gt;By configuration&lt;/strong&gt; → 选择 &lt;strong&gt;Audience&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;填写：&lt;/li&gt;
&lt;/ol&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;字段&lt;/th&gt;
&lt;th&gt;值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Name&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;aud-oauth2-proxy&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Included Client Audience&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Add to ID token&lt;/td&gt;
&lt;td&gt;ON&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Add to access token&lt;/td&gt;
&lt;td&gt;ON&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;ol start=&quot;5&quot;&gt;
&lt;li&gt;保存后&lt;strong&gt;不需要重启 Keycloak&lt;/strong&gt;，新签发的 Token 立即生效。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;验证&lt;/strong&gt;：重新登录，解码新的 ID Token，确认 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 包含 &lt;code dir=&quot;auto&quot;&gt;&quot;oauth2-proxy&quot;&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;如果配置正确但仍然报错，检查 oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;--client-id&lt;/code&gt; 是否与 Keycloak 的 Client ID 完全一致（大小写敏感）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;不一定要改 Keycloak 的 Token&lt;/strong&gt;：如果同一个客户端需要接受多个明确的 audience，可以在 oauth2-proxy 中用 &lt;code dir=&quot;auto&quot;&gt;--oidc-extra-audience&lt;/code&gt; 增加允许值；它只是在校验时扩大白名单，不会把 audience 写进 Token，也不会替代 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、签名和 &lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 校验。例如：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--client-id=oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--oidc-extra-audience=legacy-dashboard&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;这里必须先确认 &lt;code dir=&quot;auto&quot;&gt;legacy-dashboard&lt;/code&gt; 确实是该 OIDC 客户端应接受的 audience，而不是为了让 401 消失就把任意值加入白名单。&lt;code dir=&quot;auto&quot;&gt;--oidc-extra-audience&lt;/code&gt; 只改变 oauth2-proxy 本地的允许列表，不会修改 Keycloak 已签发的 Token，也不会替代资源服务器对 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、签名、&lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 和自身 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 的校验。若问题是上游没有把正确的接收方写入 Token，优先修正 Keycloak 的 Audience mapper，并用&lt;strong&gt;新签发的同一种 Token&lt;/strong&gt;复核；不要拿 Access Token 的 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 去推断 oauth2-proxy 校验的 ID Token，或反过来混用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;更稳妥的验证命令&lt;/strong&gt;（处理 JWT 常见的 Base64URL 无填充，而不是直接假设普通 Base64）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;TOKEN&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&apos;&amp;#x3C;从实际回调或认证响应取得的 JWT&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;python3&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$TOKEN&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&amp;#x3C;&amp;#x3C;&lt;/span&gt;&lt;span&gt;&apos;PY&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;import base64&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;import json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;import sys&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;parts = sys.argv[1].split(&apos;.&apos;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;if len(parts) != 3:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;raise SystemExit(&apos;not a JWT: expected 3 segments&apos;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;payload = base64.urlsafe_b64decode(parts[1] + &apos;=&apos; * (-len(parts[1]) % 4))&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;print(json.dumps(json.loads(payload), ensure_ascii=False, indent=2))&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;PY&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;只把 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 等字段用于诊断，不要把真实生产 Token 粘贴到工单、聊天或日志中。JWT Payload 只是可读编码，不是加密材料；验签仍必须由 oauth2-proxy 使用 Discovery/JWKS 完成。&lt;/p&gt;
&lt;p&gt;只有在 &lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt; 自己应当成为 Token audience、或者后端也依赖该 claim 时，才在 Keycloak 添加 Audience Mapper。不要为了“让报错消失”使用跳过 issuer 或 JWT 校验的参数；那会把配置错误变成认证绕过风险。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;部署前先跑配置自检&quot;&gt;部署前先跑配置自检&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;不要等到浏览器完成一半 OAuth 流程后才发现 YAML 或 Secret 配错。oauth2-proxy 提供 &lt;code dir=&quot;auto&quot;&gt;--config-test&lt;/code&gt;，会按启动时的校验路径检查配置文件；使用 Redis Session Store 时，也会把 Redis 连通性纳入检查。把它放进镜像启动前的 Kubernetes Job 或 CI 步骤，可以把“登录后才暴露的错误”提前到部署阶段。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 配置文件只从 Secret 挂载；不要把 client secret 写进命令历史或日志&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--config=/etc/oauth2-proxy/oauth2-proxy.cfg&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--config-test&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;自检通过只代表参数、Provider 和会话存储配置满足启动校验，不代表 Redirect URI、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;、Cookie 属性和后端授权已经正确。上线前仍要执行一次真实回调，并用一个无权限用户验证 403；否则“配置能启动”很容易被误当成“权限边界成立”。依据：&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy Configuration Overview&lt;/a&gt;。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;3-登录后无限重定向redirect-loop&quot;&gt;3. 登录后无限重定向（redirect loop）&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：输入用户名密码 → Keycloak 返回 302 → 浏览器短暂闪一下应用页面 → 又被 302 到 Keycloak 登录页 → 周而复始，最终 &lt;code dir=&quot;auto&quot;&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;这是最复杂的错误类别，根因在四个层面之一。详细排查路线图见 &lt;strong&gt;&lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/&quot;&gt;Keycloak 重定向循环与 401 排错指南&lt;/a&gt;&lt;/strong&gt;，这里只给快速对照：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;层面&lt;/th&gt;
&lt;th&gt;快速检查&lt;/th&gt;
&lt;th&gt;高频原因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Cookie&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--cookie-domain&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--cookie-samesite&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SameSite=strict 拦截 Keycloak 回调；或 Domain 不匹配导致 Cookie 写不进去&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TLS/代理&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto&lt;/code&gt; 的值&lt;/td&gt;
&lt;td&gt;Keycloak 看到的是 HTTP，签发 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt; 的 redirect_uri&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OIDC 回调&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;redirect_uri&lt;/code&gt; 是否精确匹配&lt;/td&gt;
&lt;td&gt;Keycloak 配置的 Redirect URI 和实际请求差一个斜杠/端口/协议&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Token 校验&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--oidc-issuer-url&lt;/code&gt; 是否正确&lt;/td&gt;
&lt;td&gt;issuer URL 与 ID Token 中的 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt; 声明不一致&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;如果前四项都正常但重定向地址偶发变成内部域名或 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt;，继续检查&lt;strong&gt;代理头信任&lt;/strong&gt;：&lt;code dir=&quot;auto&quot;&gt;--reverse-proxy=true&lt;/code&gt; 配合未限制的 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt;，会让能直达 4180 端口的请求影响原始 Host/协议判断。生产配置应把 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt; 限定为 ingress-nginx 或负载均衡器的实际来源网段，并从网络层禁止其他来源访问该端口。oauth2-proxy 7.15.x 官方配置文档明确提示，未设置该参数时为兼容旧行为会信任所有来源。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;最快的排错方式&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 从集群网络路径确认 oauth2-proxy 能否访问 OIDC Discovery&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 不要默认 oauth2-proxy 镜像内含 wget/curl；用一次性排错 Pod，或换成集群已有的 debug 容器。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;run&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oidc-debug&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--rm&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--restart=Never&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;--image=curlimages/curl:8.10.1&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-fsS&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;{issuer, authorization_endpoint, token_endpoint, jwks_uri}&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果你的 Keycloak 仍由反向代理发布在 /auth 上下文，先把 URL 改为&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# https://keycloak.example.com/auth/realms/myrealm/.well-known/openid-configuration，&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 再用 jq 检查返回的 .issuer；路径必须以 Discovery 的实际值为准。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果集群禁止临时 Pod，使用已经存在的网络诊断容器执行同一 curl；&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 关键是测试路径、DNS 和 CA 信任，而不是测试 oauth2-proxy 容器是否带 wget。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 用浏览器 DevTools 跟踪完整流程&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Network 面板 → 勾选 Preserve log&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 找到 /oauth2/start → /auth?（跳转 Keycloak）→ /oauth2/callback?code= → /app 这条链路&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 哪个环节返回的 HTTP 状态码不对劲，就是那个环节的问题&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 检查当前 Deployment 是否设置了代理来源白名单&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jsonpath=&apos;{.spec.template.spec.containers[0].args}&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.[]&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;reverse-proxy|trusted-proxy-ip&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;回滚边界&lt;/strong&gt;：不要通过关闭 TLS Cookie 或跳过 issuer 校验来绕过代理头问题。先恢复上一份已验证的 &lt;code dir=&quot;auto&quot;&gt;--trusted-proxy-ip&lt;/code&gt;/Ingress 配置，再重新执行 Discovery 和浏览器回调验证；临时加入 &lt;code dir=&quot;auto&quot;&gt;0.0.0.0/0&lt;/code&gt; 只能用于隔离故障，不能作为生产修复。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;4-invalid_token&quot;&gt;4. invalid_token&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志典型输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;invalid_token&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;token contains an invalid number of segments&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;failed to verify token: oidc: unable to verify jwt: ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因分类&lt;/strong&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;子类型&lt;/th&gt;
&lt;th&gt;日志特征&lt;/th&gt;
&lt;th&gt;根因&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;JWT 格式错误&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invalid number of segments&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;传入的不是 JWT（可能是 refresh token 被当 access token 用了）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;签名校验失败&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;unable to verify jwt&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Keycloak 的公钥和签发 Token 的私钥不匹配（Realm 重建后密钥对变了）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;过期&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;token is expired&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Token 过期，但 oauth2-proxy 没正确 refresh&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;issuer 不匹配&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;issuer mismatch&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--oidc-issuer-url&lt;/code&gt; 与 Token 中 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt; 不同&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断-2&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 解码 Token 查看关键字段&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;echo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&amp;#x3C;token&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cut&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d.&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-f2&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;base64&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;{iss, aud, exp, iat, nbf}&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 对比 oidc-issuer-url&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oidc-issuer-url&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 确认 Keycloak 的 issuer 值&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;.issuer&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-2&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;issuer 不匹配&lt;/strong&gt;：&lt;code dir=&quot;auto&quot;&gt;--oidc-issuer-url&lt;/code&gt; 必须与 Keycloak OIDC Discovery 返回的 &lt;code dir=&quot;auto&quot;&gt;issuer&lt;/code&gt; 完全一致（注意尾部斜杠、端口号）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;签名校验失败&lt;/strong&gt;：先确认 Discovery/JWKS 端点可从 oauth2-proxy Pod 访问，并检查日志中的 &lt;code dir=&quot;auto&quot;&gt;kid&lt;/code&gt; 是否能在当前 JWKS 中找到。Keycloak 密钥轮换或 Realm 重建后，先按运行版本确认 JWKS 缓存刷新行为，再重启 oauth2-proxy；不要用跳过校验的开关掩盖密钥或网络问题。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Token 过期&lt;/strong&gt;：检查 &lt;code dir=&quot;auto&quot;&gt;--cookie-refresh&lt;/code&gt; 是否小于上游会话或 Token 的有效期；实际有效期以 Realm 和 Client 配置为准，不要把某个默认分钟数写死到生产判断里。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;不要用 &lt;code dir=&quot;auto&quot;&gt;--insecure-oidc-skip-issuer-verification&lt;/code&gt; 或类似“不验证”参数作为修复。它会降低认证边界，且无法修复签名、&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;、过期时间或错误的 Discovery 地址。需要定位时，分别记录 Discovery 返回的 &lt;code dir=&quot;auto&quot;&gt;issuer&lt;/code&gt;、JWKS URL、Token 的 &lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;kid&lt;/code&gt;，再恢复严格校验后验证。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;5-missing-state-parameter&quot;&gt;5. missing state parameter&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oauth2-proxy[1] &amp;#x3C;timestamp&gt; &amp;#x3C;request&gt; 403 missing state parameter&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：OAuth 2.0 的 CSRF 防护依赖 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 参数——oauth2-proxy 发起授权请求时生成一个随机 state，Keycloak 必须原样返回。如果 Keycloak 回调时 URL 中没有 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 参数，说明：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Keycloak 配置的回调 URI 带了额外参数&lt;/strong&gt;，覆盖了 oauth2-proxy 的 state&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;用户直接访问了 &lt;code dir=&quot;auto&quot;&gt;/oauth2/callback&lt;/code&gt;&lt;/strong&gt;（不应该手动访问）&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;中间有代理/网关&lt;/strong&gt; 截断了 URL 参数&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断-3&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 检查 Keycloak 客户端的 Valid Redirect URIs&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak Admin Console → Clients → oauth2-proxy → Settings&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 应为 https://myapp.example.com/oauth2/callback&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 不要加 ? 或额外查询参数&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 确认 Nginx/Traefik 没有截断 query string&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Nginx: 确认 proxy_pass 没有尾部斜杠错误&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Traefik: ForwardAuth 中间件默认保留 query string，不需要额外配置&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-3&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;在 Keycloak 中检查 Redirect URI 配置：去掉 &lt;code dir=&quot;auto&quot;&gt;?&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt; 或任何多余参数&lt;/li&gt;
&lt;li&gt;如果用了 CDN/WAF（Cloudflare、阿里云 WAF），检查是否有规则过滤了 URL 参数&lt;/li&gt;
&lt;li&gt;清除浏览器缓存后重试&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;6-cookie-too-large&quot;&gt;6. cookie too large&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;cookie value too long (4096 bytes max)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：Cookie Store 会把会话数据放入加密 Cookie；如果 Token 中包含大量 claims（如组列表、角色列表），Cookie 可能超过浏览器或代理的单 Cookie 大小限制。具体内容取决于 Provider、Session Store 和配置，不应假定三种 Token 都一定完整地存进 Cookie。&lt;/p&gt;
&lt;p&gt;高发于：Keycloak 用户属于几十个 group，每个 group 名字又很长。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-4&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;方案 1：使用 Redis Session Store，Cookie 只存 Session ID&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Redis 是降低 Cookie 体积和集中管理会话的选项，不是多副本部署的硬性前提。普通 Cookie store 在所有副本共享同一个 &lt;code dir=&quot;auto&quot;&gt;--cookie-secret&lt;/code&gt; 时可以无状态工作；启用 Redis 后，需要把 Redis 的高可用、备份和故障切换纳入 IAM 网关的运维范围。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--session-store-type=redis&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--redis-connection-url=rediss://redis.auth.svc.cluster.local:6380/0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 生产环境还应通过 Secret 注入 Redis 凭据，并校验证书；不要把密码写进 Git&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;方案 2：关闭不需要的凭据转发&lt;/strong&gt;&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果后端不需要 Access Token，不传递&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# --pass-access-token=false&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# --set-authorization-header=false&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# auth-url 模式也不需要 Basic Auth 头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--pass-basic-auth=false&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;方案 3：减少 Token 中的 claims&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在 Keycloak 中移除不必要的 Protocol Mapper（如大段的自定义属性映射），或用 Client Scope 限制 scope：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--scope=openid&lt;/span&gt;&lt;span&gt;   &lt;/span&gt;&lt;span&gt;# 只要 openid，不加 email profile（如果不需要的话）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;auth_request-模式下的一个隐藏问题set-cookie-被截断&quot;&gt;auth_request 模式下的一个隐藏问题：Set-Cookie 被截断&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果 oauth2-proxy 使用 Cookie Session Store，并且启用了 &lt;code dir=&quot;auto&quot;&gt;--cookie-refresh&lt;/code&gt;，&lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt; 在刷新会话时可能返回新的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt;。ingress-nginx 的 &lt;code dir=&quot;auto&quot;&gt;auth_request&lt;/code&gt; 默认只把认证结果带回上游，不能自动把所有 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt; 响应头转发给浏览器；Cookie 被拆成多个分片时，只转发第一片也会造成下一次请求认证失败。&lt;/p&gt;
&lt;p&gt;这和“Cookie 太大”不是同一个根因：前者是浏览器拒绝或无法保存，后者是认证子请求的响应头没有完整回传。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;处理顺序：&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;先在浏览器 Network 面板确认 &lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt; 或业务请求的响应是否出现 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt;，并检查是否有 &lt;code dir=&quot;auto&quot;&gt;_oauth2_proxy_1&lt;/code&gt; 等分片。&lt;/li&gt;
&lt;li&gt;如果只有第一片，按 ingress-nginx 官方 &lt;code dir=&quot;auto&quot;&gt;auth_request&lt;/code&gt; 示例显式转发刷新 Cookie 的所有分片；不要只添加一个 &lt;code dir=&quot;auto&quot;&gt;add_header Set-Cookie&lt;/code&gt; 就认为已修复。&lt;/li&gt;
&lt;li&gt;如果 Cookie 长期接近浏览器限制，改用 Redis Session Store 或精简 claims，并把 Redis 的可用性、备份和凭据轮换纳入变更范围。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;不要用增大 Nginx buffer 来掩盖 Cookie 分片没有转发的问题；buffer 解决的是代理处理大小，不会替你复制丢失的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt; 头。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;7-401-已登录但认证被拒&quot;&gt;7. 401 已登录但认证被拒&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：登录成功，Cookie 存在，但过一段时间（或刷新页面）返回 401。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：先区分两种 Session Store。默认 Cookie store 将会话加密放在浏览器 Cookie 中，因此副本 A、B 只要共享同一个 &lt;code dir=&quot;auto&quot;&gt;--cookie-secret&lt;/code&gt; 就能读取它；多副本本身不会造成“副本 B 不认识会话”。如果使用 Redis Session Store，则所有副本必须访问同一个 Redis。仍然出现 401 时，优先检查 Cookie 是否过期、刷新失败、Secret 是否不一致，以及代理是否丢失 Cookie，而不是先把问题归咎于副本数。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断-4&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 确认副本数&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. Cookie Session Store：确认所有副本使用同一个 Secret（不要打印 Secret 值）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-A3&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;cookie-secret|secretKeyRef&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. Redis Session Store：确认所有副本指向同一个 Redis，并查看 refresh/session 错误&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;session-store-type|redis-connection-url&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;refresh|expired|session&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-5&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 方案 1：需要服务端会话、集中撤销或 Cookie 过大时使用 Redis&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;args&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--session-store-type=redis&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--redis-connection-url=rediss://redis.auth.svc.cluster.local:6380/0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 凭据通过 Secret 注入；同时配置 Redis 的 TLS、认证、超时、监控和备份&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 方案 2：继续使用默认 Cookie Session Store&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 所有副本必须共享同一个 cookie-secret；不需要为了多副本单独启用&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Ingress session affinity。若 Secret 不一致，滚动发布后旧会话会间歇性失效。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Session affinity 只能掩盖路由问题，不能修复不同副本使用不同 &lt;code dir=&quot;auto&quot;&gt;--cookie-secret&lt;/code&gt; 或 Redis 数据不一致的问题。改用 Redis 或修改 Secret 前，先安排可接受重新登录的窗口；Cookie Store 与 Redis Store 之间不是无损热切换。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;8-missing-claim-email&quot;&gt;8. missing claim “email”&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;日志输出&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;could not get claim: missing claim &quot;email&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：当前配置或 Provider 校验路径需要 &lt;code dir=&quot;auto&quot;&gt;email&lt;/code&gt; claim，但该用户的 ID Token 没有它。LDAP/AD 属性映射、用户资料是否填写，以及请求的 scope/client scope 都可能影响最终 Token；不要仅凭管理界面能看到邮箱就推断它一定进入了 ID Token。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-6&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;方案 1：确保用户有邮箱&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在 Keycloak 中：Users → 目标用户 → Attributes → 添加 &lt;code dir=&quot;auto&quot;&gt;email&lt;/code&gt; 属性；或用 User Federation mapper 从 LDAP/AD 映射 &lt;code dir=&quot;auto&quot;&gt;mail&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;email&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;方案 2：不要用伪造邮箱绕过身份校验&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;不要把 &lt;code dir=&quot;auto&quot;&gt;--insecure-oidc-allow-unverified-email=true&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;--email-domain=*&lt;/code&gt; 或硬编码的 &lt;code dir=&quot;auto&quot;&gt;@placeholder.local&lt;/code&gt; 地址当作生产修复：它们可能扩大可登录范围，且不能补出缺失的用户身份属性。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;方案 3（推荐）：修正真实身份属性的来源&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;确认 LDAP/AD 的 &lt;code dir=&quot;auto&quot;&gt;mail&lt;/code&gt; 属性已映射到 Keycloak 的 &lt;code dir=&quot;auto&quot;&gt;email&lt;/code&gt;，用户资料中的邮箱已填写并按组织规则验证；确认客户端请求了需要的 scope，并用新签发的 ID Token 检查 claim。若业务确实不把邮箱作为身份标识，应按当前 oauth2-proxy 版本的 Provider 配置选择稳定的用户标识，而不是伪造邮箱；改动前先在测试 Realm 验证登录、域名限制和审计字段。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;9-erroraccess_denied&quot;&gt;9. error=access_denied&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：浏览器地址栏出现 &lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/oauth2/callback?error=access_denied&amp;#x26;...&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：Keycloak 拒绝了授权请求。常见原因：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;原因&lt;/th&gt;
&lt;th&gt;检查&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;用户不在 &lt;code dir=&quot;auto&quot;&gt;--allowed-group&lt;/code&gt; 指定的组里&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kubectl logs&lt;/code&gt; 可以看到 oauth2-proxy 把哪些 group 传给了 Provider&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client 的 “Consent Required” 关了但用户没有已存 consent&lt;/td&gt;
&lt;td&gt;Keycloak Clients → oauth2-proxy → 打开 Consent Required&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;用户被 Keycloak 的 Brute Force Detection 暂时锁定&lt;/td&gt;
&lt;td&gt;Keycloak → Realm Settings → Security Defenses → Brute Force Detection&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;scope&lt;/code&gt; 参数中请求了不被 Client 允许的 scope&lt;/td&gt;
&lt;td&gt;oauth2-proxy &lt;code dir=&quot;auto&quot;&gt;--scope=openid email profile&lt;/code&gt; 需要 Client 的 Client Scopes 包含这些&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-7&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;确认 &lt;code dir=&quot;auto&quot;&gt;--allowed-group&lt;/code&gt; 中的组名与 Keycloak 中的组名完全一致&lt;/li&gt;
&lt;li&gt;如果不需要组限制，去掉 &lt;code dir=&quot;auto&quot;&gt;--allowed-group&lt;/code&gt; 参数&lt;/li&gt;
&lt;li&gt;检查 Keycloak 的 Events（Admin Console → Events → Login Events），会显示具体的 “DENIED” 原因&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;10-nginx-ingress-返回-503&quot;&gt;10. Nginx Ingress 返回 503&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：访问应用 URL，Nginx 返回 503 Service Temporarily Unavailable。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：Ingress Controller 无法访问 oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;auth-url&lt;/code&gt; 端点。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;诊断-5&quot;&gt;诊断&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 确认 oauth2-proxy Service 的端点健康&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;endpoints&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 检查 Ingress annotation 中的 auth-url 是否可达&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&amp;#x3C;ingress-name&gt;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth-url&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 从 Ingress Controller Pod 测试连接&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress-nginx&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/ingress-nginx-controller&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-sS&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-w&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;%{http_code}&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;http://oauth2-proxy.auth.svc.cluster.local:4180/ping&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 预期：200（/ping 不要求认证）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-8&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;如果 endpoint 为空：检查 oauth2-proxy Pod 是否 Ready，&lt;code dir=&quot;auto&quot;&gt;kubectl describe pod&lt;/code&gt; 看 readiness probe&lt;/li&gt;
&lt;li&gt;如果 Service 名不对：确认 Ingress annotation 中用的是 &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;service&gt;.&amp;#x3C;namespace&gt;.svc.cluster.local&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;如果在 K3s/K0s 等非标准 K8s 发行版：确认 CoreDNS 正常，&lt;code dir=&quot;auto&quot;&gt;svc.cluster.local&lt;/code&gt; 可解析&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;如果 &lt;code dir=&quot;auto&quot;&gt;/ping&lt;/code&gt; 返回 200 但受保护请求仍然失败，继续检查 &lt;code dir=&quot;auto&quot;&gt;auth-url&lt;/code&gt; 是否指向集群内可达的 &lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt;，以及 &lt;code dir=&quot;auto&quot;&gt;auth-signin&lt;/code&gt; 是否使用了入口收到的原始请求 URI。ingress-nginx 官方外部认证示例把两者分成两个职责：&lt;code dir=&quot;auto&quot;&gt;auth-url&lt;/code&gt; 做认证判定，&lt;code dir=&quot;auto&quot;&gt;auth-signin&lt;/code&gt; 负责 401 后跳转；不要把登录回调地址误填成后端业务地址。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-url&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://$host/oauth2/auth&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-signin&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://$host/oauth2/start?rd=$escaped_request_uri&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;依据：&lt;a href=&quot;https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ingress-nginx External OAUTH Authentication&lt;/a&gt;。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;11-cookie-跨子域不生效&quot;&gt;11. Cookie 跨子域不生效&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：&lt;code dir=&quot;auto&quot;&gt;app1.example.com&lt;/code&gt; 登录成功，访问 &lt;code dir=&quot;auto&quot;&gt;app2.example.com&lt;/code&gt; 需要重新登录。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;先纠正一个容易误导排错的判断&lt;/strong&gt;：现代浏览器按照 RFC 6265 处理 &lt;code dir=&quot;auto&quot;&gt;Domain=example.com&lt;/code&gt; 和 &lt;code dir=&quot;auto&quot;&gt;Domain=.example.com&lt;/code&gt; 时，会忽略前导点号；两者都允许 Cookie 发送到 &lt;code dir=&quot;auto&quot;&gt;example.com&lt;/code&gt; 及其子域。真正的区别是：省略 &lt;code dir=&quot;auto&quot;&gt;Domain&lt;/code&gt; 属性时，Cookie 才是只对当前主机生效的 host-only Cookie。oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;--cookie-domain&lt;/code&gt; 应填写共享父域，但不应把“必须加点号”当成修复条件。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;修复-9&quot;&gt;修复&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# ✅ 跨子域共享：显式设置共享父域；前导点号可省略&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-domain=example.com&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# ✅ 只保护单个主机：省略 --cookie-domain，使用 host-only Cookie&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 不要为了“跨子域”写成不相关的父域，例如 .example.net&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;还要同时检查以下边界：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;所有应用确实属于同一个注册域；&lt;code dir=&quot;auto&quot;&gt;app1.example.com&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;app2.example.org&lt;/code&gt; 不能通过 Cookie Domain 共享。&lt;/li&gt;
&lt;li&gt;Cookie 的 &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;SameSite&lt;/code&gt; 和名称没有被入口代理或另一套 oauth2-proxy 配置覆盖。&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--cookie-domain&lt;/code&gt; 不能扩大到不受你控制的父域；共享 Cookie 会扩大会话泄露和登出影响范围。单个应用不需要 SSO 时，优先省略该参数。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;验证&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 浏览器 DevTools → Application → Cookies → 查看 _oauth2_proxy Cookie&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 跨子域场景应看到 Domain=example.com（浏览器可能以不同 UI 形式显示）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 同时确认 Path、Secure、SameSite 与部署拓扑一致&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;规范依据：&lt;a href=&quot;https://www.rfc-editor.org/rfc/rfc6265#section-4.1.2.3&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;RFC 6265 §4.1.2.3 Domain 属性&lt;/a&gt;；oauth2-proxy 参数说明见&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;官方配置文档&lt;/a&gt;。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;不要把-__host--cookie-前缀和跨子域共享混用&quot;&gt;不要把 &lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; Cookie 前缀和跨子域共享混用&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;oauth2-proxy 官方配置文档建议在启用 &lt;code dir=&quot;auto&quot;&gt;--cookie-secure&lt;/code&gt; 时考虑使用 &lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;__Secure-&lt;/code&gt; 前缀，但两者的边界不同：&lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; Cookie 必须带 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;Path=/&lt;/code&gt;，并且&lt;strong&gt;不能设置 &lt;code dir=&quot;auto&quot;&gt;Domain&lt;/code&gt;&lt;/strong&gt;。因此它只能绑定当前主机，不能与 &lt;code dir=&quot;auto&quot;&gt;--cookie-domain=example.com&lt;/code&gt; 组合实现跨子域 SSO；跨子域场景应使用符合部署边界的普通名称或 &lt;code dir=&quot;auto&quot;&gt;__Secure-&lt;/code&gt; 名称，并保留 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;。浏览器会拒绝不满足前缀约束的 &lt;code dir=&quot;auto&quot;&gt;Set-Cookie&lt;/code&gt;，表现仍可能只是“登录成功后 Cookie 不见了”。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 单主机部署：host-only Cookie，可考虑 __Host- 前缀&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-name=__Host-oauth2_proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-secure=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-path=/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 不要同时设置 --cookie-domain&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 跨子域 SSO：不能使用 __Host-；显式设置共享父域&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-name=__Secure-oauth2_proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-domain=example.com&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-secure=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;验证时不要只看 Cookie 是否出现，还要检查 DevTools 中的 &lt;code dir=&quot;auto&quot;&gt;Domain&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt; 和名称前缀。&lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; 约束见 &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie_prefixes&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN Cookie prefixes&lt;/a&gt;；oauth2-proxy 的名称与 Cookie 参数见&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;官方配置文档&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;如果两个应用不应该共享登录会话，不要为了减少一次登录而扩大 Cookie Domain；分别使用主机专属 Domain 和不同的 &lt;code dir=&quot;auto&quot;&gt;--cookie-name&lt;/code&gt;。共享父域还会扩大 Cookie 的发送范围，子域被接管或存在不可信应用时，风险边界也会一起扩大。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;12-登出一个应用全部退出&quot;&gt;12. 登出一个应用全部退出&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：在应用 A 点了退出，应用 B、C 也全部退出了。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;根因&lt;/strong&gt;：多个应用共用同一个 oauth2-proxy 实例和同一个 Cookie Domain。调用 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 时，清除了所有子域共享的 Cookie。&lt;/p&gt;
&lt;p&gt;如果现象是反过来的——某个应用仍处于登录状态，问题不在 Cookie 共享：&lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt; 只清 oauth2-proxy 自己的 Cookie，IdP 会话没有被结束，而没被通知到的客户端也不会自行登出。分层原因与最小配置见 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-single-logout/&quot;&gt;IAM 单点登出排错&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;这可能是&lt;strong&gt;符合预期的&lt;/strong&gt;（统一登出是 SSO 的标准行为），也可能是&lt;strong&gt;不想要的&lt;/strong&gt;（不同应用应该独立管理 session）。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;方案&quot;&gt;方案&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;如果需要各自独立&lt;/strong&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 每个应用部署独立的 oauth2-proxy 实例&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 关键差异：cookie-name 不同&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;实例 A&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-name=_oauth2_proxy_app_a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-domain=app-a.example.com&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;实例 B&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-name=_oauth2_proxy_app_b&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--cookie-domain=app-b.example.com&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;如果需要统一登出，但只想登出当前应用&lt;/strong&gt;：使用 Keycloak 的 &lt;code dir=&quot;auto&quot;&gt;/protocol/openid-connect/logout&lt;/code&gt; 而非 oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;/oauth2/sign_out&lt;/code&gt;。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;13-已登录但后端收不到正确的-token-或用户头&quot;&gt;13. 已登录，但后端收不到正确的 Token 或用户头&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;现象&lt;/strong&gt;：oauth2-proxy 日志显示 &lt;code dir=&quot;auto&quot;&gt;AuthSuccess&lt;/code&gt;，页面也能打开，但后端看不到 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-User&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Groups&lt;/code&gt;，或者拿到的 &lt;code dir=&quot;auto&quot;&gt;Authorization&lt;/code&gt; 被当成 access token 后返回 &lt;code dir=&quot;auto&quot;&gt;invalid audience&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;先区分两件事&lt;/strong&gt;：认证响应头不是自动转发到业务后端的。&lt;code dir=&quot;auto&quot;&gt;--set-xauthrequest&lt;/code&gt; 只让 oauth2-proxy 在 &lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt; 响应中生成 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-*&lt;/code&gt;；ingress-nginx 还必须用 &lt;code dir=&quot;auto&quot;&gt;auth-response-headers&lt;/code&gt; 显式复制它们。另一方面，&lt;code dir=&quot;auto&quot;&gt;--pass-authorization-header&lt;/code&gt; 在代理模式下传的是 &lt;strong&gt;OIDC ID Token&lt;/strong&gt;，不是给资源服务器使用的 OAuth access token；不要用它替代 API 的 access token。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;最小检查&quot;&gt;最小检查&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 确认 oauth2-proxy 的非敏感参数&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jsonpath=&apos;{.spec.template.spec.containers[0].args}&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.[]&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;set-xauthrequest|pass-access-token|pass-authorization-header&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 确认业务 Ingress 明确复制了认证响应头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;yaml&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;auth-response-headers|auth-url|auth-signin&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;按需求修复&quot;&gt;按需求修复&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;只需要登录身份时，保持最小配置：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--set-xauthrequest=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# ingress-nginx&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-response-headers&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&gt;-&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-Groups&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;后端确实要调用资源服务器时，才额外开启 access token：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--set-xauthrequest=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;--pass-access-token=true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# ingress-nginx：只列出真正需要的敏感头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-response-headers&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&gt;-&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-Access-Token&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;后端仍要独立校验 access token 的签名、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、面向自身的 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt; 和 scope。oauth2-proxy 通过认证只说明入口会话有效，不等于后端 API 授权成功。若后端收到 &lt;code dir=&quot;auto&quot;&gt;aud=oauth2-proxy&lt;/code&gt; 而自己的资源服务要求另一个 audience，应在 Keycloak 为资源服务配置 audience mapper，不能把 &lt;code dir=&quot;auto&quot;&gt;--pass-authorization-header&lt;/code&gt; 换上去碰运气。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;安全边界&lt;/strong&gt;：Ingress 必须覆盖或清理客户端提交的同名 Header，并阻止后端绕过 Ingress 直接访问。否则攻击者可以伪造 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Email&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Groups&lt;/code&gt;。Token 透传还会扩大凭据暴露面、日志脱敏范围和回滚复杂度；不用就不要开。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;依据：&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/#header-options&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy Header Options&lt;/a&gt; 和 &lt;a href=&quot;https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ingress-nginx External OAUTH Authentication&lt;/a&gt;。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;诊断命令速查&quot;&gt;诊断命令速查&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy 日志（最近 50 行，过滤错误）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-iE&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;error|fail|invalid|csrf|403|401&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 查看 oauth2-proxy 完整启动参数&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;get&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-o&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jsonpath=&apos;{.spec.template.spec.containers[0].args}&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.[]&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak OIDC Discovery&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;{issuer, authorization_endpoint, token_endpoint, jwks_uri}&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 解码 JWT（三部分，取第二部分 payload）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;echo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&amp;#x3C;jwt&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cut&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d.&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-f2&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;base64&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 检查 Keycloak 客户端配置的 Redirect URI&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak Admin Console → Clients → oauth2-proxy → Settings → Valid Redirect URIs&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 或通过 REST API：&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# curl -s -H &quot;Authorization: Bearer &amp;#x3C;admin_token&gt;&quot; \&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;#   https://keycloak.example.com/admin/realms/myrealm/clients?clientId=oauth2-proxy | jq .&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 测试 oauth2-proxy 健康端点&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;http://oauth2-proxy.auth.svc.cluster.local:4180/ping&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 预期：OK&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 模拟认证请求（不带 Cookie）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-v&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;http://oauth2-proxy.auth.svc.cluster.local:4180/oauth2/auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 预期：401（未认证）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;延伸阅读&quot;&gt;延伸阅读&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-oauth2-proxy/&quot;&gt;Keycloak + oauth2-proxy 集成实战指南&lt;/a&gt;——完整部署配置，从 Keycloak 到 Nginx Ingress 到 Traefik ForwardAuth&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/&quot;&gt;Keycloak 重定向循环与 401 排错指南&lt;/a&gt;——重定向循环的完整排查路线图&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/traefik-forwardauth-keycloak/&quot;&gt;Traefik ForwardAuth + Keycloak + oauth2-proxy&lt;/a&gt;——Traefik 网关下的配置与排错&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/implementation/oauth2-proxy-deep-dive/&quot;&gt;oauth2-proxy 深度介绍&lt;/a&gt;——架构原理、Provider 选型、Cookie/Session 机制&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 官方文档 — Keycloak OIDC Provider&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 配置总览（Session Store、Cookie 与 Header 参数）&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/#header-options&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy Header Options&lt;/a&gt;——区分 &lt;code dir=&quot;auto&quot;&gt;--pass-access-token&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;--pass-authorization-header&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;--set-xauthrequest&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/#cookie-options&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 配置总览：CSRF Cookie 并发与大小限制&lt;/a&gt;——&lt;code dir=&quot;auto&quot;&gt;cookie-csrf-per-request&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;cookie-csrf-per-request-limit&lt;/code&gt; 的行为&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.rfc-editor.org/rfc/rfc6749&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;RFC 6749 §4.1.1–§4.1.2、§10.12&lt;/a&gt;——授权码流程中的 &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; 往返与 CSRF 防护语义&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3258&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy Issue #3258：并行请求下的 CSRF Cookie 问题&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 官方配置总览：Cookie 前缀、CSRF Cookie 与可信代理&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN：Cookie 前缀与 Domain 属性&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.keycloak.org/server/reverseproxy&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak：反向代理与公开路径&lt;/a&gt;——确认当前 Keycloak 部署公开的 OIDC &lt;code dir=&quot;auto&quot;&gt;/realms/&lt;/code&gt; 路径，避免把旧版 &lt;code dir=&quot;auto&quot;&gt;/auth/realms/&lt;/code&gt; 路径当成新部署的默认值&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy GitHub Issues&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#domaindomain-value&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN：Set-Cookie 的 Domain 属性&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;iam-faq&quot;&gt;IAM FAQ&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;oauth2-proxy-和-nginx-ingress-auth-url-是什么关系&quot;&gt;oauth2-proxy 和 Nginx Ingress auth-url 是什么关系？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;oauth2-proxy 是认证决策点。Nginx Ingress 用 &lt;code dir=&quot;auto&quot;&gt;auth-url&lt;/code&gt; 注解把每个外部请求发给 oauth2-proxy 做认证判定。oauth2-proxy 返回 202 → Ingress 放行；返回 401 → Ingress 把用户重定向到 Keycloak 登录。这种模式叫&lt;strong&gt;外部认证（external auth）&lt;/strong&gt;，oauth2-proxy 不代理流量，只做判定。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;oauth2-proxy-和-keycloak-的-iam-职责怎么划分&quot;&gt;oauth2-proxy 和 Keycloak 的 IAM 职责怎么划分？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 是 IAM 的身份提供者（IDP）：管理用户、组、角色、密码策略、MFA、身份联邦。oauth2-proxy 是策略执行点（PEP）：在流量入口拦住未认证请求，发起 OIDC 登录，向后端透传认证结果。两者配合形成完整的 IAM 认证链路——Keycloak 管「你是谁」，oauth2-proxy 管「你能不能进这个应用」。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;多副本-oauth2-proxy-一定要-redis-吗&quot;&gt;多副本 oauth2-proxy 一定要 Redis 吗？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;不一定。默认 Cookie store 是无状态的，多副本共享同一个 &lt;code dir=&quot;auto&quot;&gt;--cookie-secret&lt;/code&gt; 即可读取会话；Redis 主要用于减小 Cookie、集中撤销会话或把状态放到服务端。启用 Redis 后，Redis 也成为 IAM 网关的运行依赖，需要配置认证、TLS、监控和备份。&lt;/p&gt;
</content:encoded><category>keycloak</category><category>oauth2-proxy</category><category>auth</category></item><item><title>IAM 网关 Keycloak 重定向循环与 401 排错</title><link>https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/</guid><description>IAM 网关中 Keycloak 登录循环与 401 的诊断流程，覆盖 Cookie、反向代理 Header、OIDC 回调、TLS 终结和 SameSite 排查。</description><pubDate>Tue, 07 Jul 2026 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;场景&quot;&gt;场景&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;你已经部署好了 Keycloak +反向代理，用户能在 Keycloak 登录页输入用户名密码，但登录成功后浏览器在 Keycloak 和应用之间反复跳转，最终浏览器报 &lt;code dir=&quot;auto&quot;&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;；或者直接返回 401，看起来“登录成功了但就是进不去”。&lt;/p&gt;
&lt;p&gt;这类问题的根因几乎都在 &lt;strong&gt;Cookie、反向代理 Header、TLS 终结 和 OIDC 回调 URI&lt;/strong&gt; 四个环节。本文给出一个系统性的排查路线图。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;适用与不适用&quot;&gt;适用与不适用&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;适用&lt;/th&gt;
&lt;th&gt;不适用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Keycloak + 任意反向代理（Nginx/Traefik/HAProxy/ALB）&lt;/td&gt;
&lt;td&gt;Keycloak 本身无法启动（那是部署问题）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;oauth2-proxy / Traefik ForwardAuth / Nginx auth-url 模式&lt;/td&gt;
&lt;td&gt;用户凭据错误（先确认用户名密码正确）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;OIDC 标准客户端（非 Keycloak Adapter）&lt;/td&gt;
&lt;td&gt;Keycloak Adapter 老项目（Adapters 已弃用，参考 &lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-adapter-migration/&quot;&gt;迁移指南&lt;/a&gt; 迁移到标准 OIDC 库再排查）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SAML 单点登录重定向问题&lt;/td&gt;
&lt;td&gt;纯 LDAP/Kerberos 认证（不涉及 HTTP 重定向）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h2 id=&quot;排查路线图&quot;&gt;排查路线图&lt;/h2&gt;&lt;/div&gt;
&lt;pre&gt;flowchart TD
    A[用户登录后重定向循环 / 401] --&gt; B{反向代理配置是否正确？}
    B --&gt;|否| B1[X-Forwarded-For / X-Forwarded-Proto 缺失]
    B --&gt;|是| C{Cookie 是否能写入浏览器？}
    C --&gt;|否| C1[SameSite 过严 / Domain 不匹配 / Secure 标记与 HTTP 冲突]
    C --&gt;|是| D{OIDC 回调 URI 是否匹配？}
    D --&gt;|否| D1[redirect_uri 拼写错误 / 协议不匹配 / 端口不一致]
    D --&gt;|是| E{TLS 终结在哪一层？}
    E --&gt;|错层| E1[代理层 HTTP → Keycloak 看到 HTTP 而非 HTTPS]
    E --&gt;|正确| F{认证后的 Token 校验？}
    F --&gt;|失败| F1[audience / issuer / nbf 校验失败]
    F --&gt;|通过| G[✅ 认证链路正常，检查应用层逻辑]&lt;/pre&gt;
&lt;div&gt;&lt;h2 id=&quot;第一关反向代理-header&quot;&gt;第一关：反向代理 Header&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 自身不面向公网时，反向代理必须正确传递代理头，且 Keycloak 必须配置为解析代理实际发送的格式。缺少或错误解析这些头时，Keycloak 可能构建出错误的重定向 URL；更危险的是，如果代理把客户端自己提交的 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 原样转发，外部用户可以伪造来源协议或主机名。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;三个必需-header&quot;&gt;三个必需 Header&lt;/h3&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Header&lt;/th&gt;
&lt;th&gt;含义&lt;/th&gt;
&lt;th&gt;缺失后果&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-For&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;真实客户端 IP&lt;/td&gt;
&lt;td&gt;Keycloak 可能把代理 IP 当成客户端，影响限流和审计&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;原始请求协议（http/https）&lt;/td&gt;
&lt;td&gt;Keycloak 生成的 redirect_uri 可能变成 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt;，TLS 不匹配导致循环&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Host&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;原始请求 Host 头&lt;/td&gt;
&lt;td&gt;Keycloak 重定向到内部 hostname 而非公网域名&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;信任边界&lt;/strong&gt;：&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 不是客户端输入就可信。TLS 终结层应先删除或覆盖来自上游的同名 Header，再写入它实际观察到的值；Keycloak 只应接收来自受信代理的请求。若链路中有多层代理，逐层确认哪一层负责覆盖 Header，不要仅在应用日志里看到一个值就认为它可靠。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;nginx-配置检查&quot;&gt;Nginx 配置检查&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;location&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/ &lt;/span&gt;&lt;span&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_pass &lt;/span&gt;&lt;span&gt;http://keycloak:8080;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_set_header &lt;/span&gt;&lt;span&gt;Host $host;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_set_header &lt;/span&gt;&lt;span&gt;X-Real-IP $remote_addr;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;# 单层公网入口覆盖客户端头；多级代理链需先在边界清洗后再保留链路&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_set_header &lt;/span&gt;&lt;span&gt;X-Forwarded-For $remote_addr;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_set_header &lt;/span&gt;&lt;span&gt;X-Forwarded-Proto $scheme;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;   &lt;span&gt; &lt;/span&gt;&lt;/span&gt;&lt;span&gt;proxy_set_header &lt;/span&gt;&lt;span&gt;X-Forwarded-Host $host;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;$proxy_add_x_forwarded_for&lt;/code&gt; 会保留客户端提交的旧值并追加当前地址。只有在每一跳都已清洗来源头、且确实需要保留多级代理链时才使用它；单层公网入口应覆盖而不是追加。无论采用哪种写法，都要让入口代理覆盖 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Host&lt;/code&gt; 和 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Port&lt;/code&gt;，并用网络策略限制 Keycloak 只接受来自代理的连接。&lt;/p&gt;
&lt;p&gt;Keycloak 的 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS=xforwarded&lt;/code&gt; 只是选择 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 的解析格式，不会替代理清洗客户端输入。生产环境还应按实际网络配置 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_TRUSTED_ADDRESSES&lt;/code&gt;（或 &lt;code dir=&quot;auto&quot;&gt;--proxy-trusted-addresses&lt;/code&gt;），并避免把后端 Service 或管理端口暴露给不受信任网络。若使用 TLS passthrough，则不要启用 &lt;code dir=&quot;auto&quot;&gt;proxy-headers&lt;/code&gt;，改用 PROXY protocol；两者不能同时启用。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;快速验证&quot;&gt;快速验证&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 在 Keycloak 容器内检查它看到的头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果 Keycloak 有 admin 权限，检查 Server Info → 查看前端 URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 或者直接 curl 测试：&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-G&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-v&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;--data-urlencode &lt;/span&gt;&lt;span&gt;&quot;client_id=myclient&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;--data-urlencode &lt;/span&gt;&lt;span&gt;&quot;redirect_uri=https://myapp.example.com/callback&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;--data-urlencode &lt;/span&gt;&lt;span&gt;&quot;response_type=code&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;--data-urlencode &lt;/span&gt;&lt;span&gt;&quot;scope=openid&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 观察 Location 头中的 redirect_uri 是否使用 https:// 和正确域名&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 仅用于诊断；不要把真实凭据或 Token 放进命令行/日志。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;再从代理外部发送故意伪造的来源头，确认上游不会照单全收：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-skI&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-H&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;Host: attacker.example&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-H&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;X-Forwarded-Proto: http&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;-H&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;X-Forwarded-Host: attacker.example&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;验证重点不是响应码，而是响应中的 URL、日志中的客户端地址和 Keycloak 生成的 issuer 仍属于预期域名。若伪造头能改变这些值，先修复代理覆盖规则和后端网络边界，不要用关闭 hostname 校验来“修好”重定向。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;traefik-配置检查&quot;&gt;Traefik 配置检查&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Traefik IngressRoute 不需要手动设这些 Header，Traefik 默认会传&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 但需要确认 Keycloak Service 使用正确的端口和 scheme&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;apiVersion&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;traefik.io/v1alpha1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;IngressRoute&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;metadata&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;spec&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;entryPoints&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;websecure&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;routes&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;match&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Host(`keycloak.example.com`)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Rule&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;services&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;port&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;8080&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;# 关键：告诉 Traefik 后端是 HTTP（内部不加密）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;# Keycloak 看到 X-Forwarded-Proto: https 才会生成正确的重定向&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;第二关cookie-配置&quot;&gt;第二关：Cookie 配置&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;samesite-过严&quot;&gt;SameSite 过严&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;用户在 Keycloak 登录后，浏览器跳回应用时携带的 Cookie 被 SameSite=Strict 拦截，导致应用认为“没登录”，再次重定向到 Keycloak。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;SameSite 值&lt;/th&gt;
&lt;th&gt;行为&lt;/th&gt;
&lt;th&gt;推荐&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Strict&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;跨站请求完全不带 Cookie&lt;/td&gt;
&lt;td&gt;❌ 会导致回调时 Cookie 丢失&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Lax&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;顶级导航（GET 请求）带 Cookie&lt;/td&gt;
&lt;td&gt;✅ OIDC 回调是 GET 请求，Lax 足够&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;总是发送&lt;/td&gt;
&lt;td&gt;需要配合 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt; 标记，仅 HTTPS&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h3 id=&quot;cookie-domain-不匹配&quot;&gt;Cookie Domain 不匹配&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果配置了 &lt;code dir=&quot;auto&quot;&gt;--cookie-domain=.example.com&lt;/code&gt;，但实际访问 &lt;code dir=&quot;auto&quot;&gt;app.other.com&lt;/code&gt;，Cookie 不会随请求发送。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;判断边界&lt;/strong&gt;：不要把“前面有没有点号”当成判断依据。现代浏览器会忽略 &lt;code dir=&quot;auto&quot;&gt;Domain&lt;/code&gt; 属性值前的前导点号，所以 &lt;code dir=&quot;auto&quot;&gt;.example.com&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;example.com&lt;/code&gt; 在这里等价；真正决定 Cookie 是否发送的是 Domain 是否覆盖当前主机名，以及当前请求是否满足 Secure、SameSite 和路径条件。&lt;code dir=&quot;auto&quot;&gt;example.com&lt;/code&gt; 可以覆盖 &lt;code dir=&quot;auto&quot;&gt;app.example.com&lt;/code&gt;，但不能覆盖 &lt;code dir=&quot;auto&quot;&gt;other.example.net&lt;/code&gt;。详见 &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#domaindomain-value&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN：Set-Cookie 的 Domain 属性&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;常见错误&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;把不同主域名误当成同一 Cookie 作用域&lt;/li&gt;
&lt;li&gt;为了让多个应用复用会话，把 Domain 扩大到包含不可信子域的共同父域&lt;/li&gt;
&lt;li&gt;使用 &lt;code dir=&quot;auto&quot;&gt;__Host-&lt;/code&gt; 前缀却同时设置了 &lt;code dir=&quot;auto&quot;&gt;Domain&lt;/code&gt;；该前缀要求 Cookie 不带 Domain 属性，浏览器会拒收&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h3 id=&quot;cookie-secure-与-http-冲突&quot;&gt;Cookie Secure 与 HTTP 冲突&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;生产环境 Keycloak 要求 &lt;code dir=&quot;auto&quot;&gt;Cookie Secure=true&lt;/code&gt;，但如果反向代理和 Keycloak 之间走 HTTP（内部网络），Keycloak 在收到 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto: https&lt;/code&gt; 时会把 Cookie 标记为 Secure。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;症状&lt;/strong&gt;：如果用户实际通过 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt; 访问，浏览器不会在后续 HTTP 请求中发送带 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt; 属性的 Cookie，导致每次请求都重新跳转登录。不要把这个现象与“代理到 Keycloak 的内部连接使用 HTTP”混淆：浏览器只看到它与外部入口之间的连接；典型的 HTTPS 终结拓扑中，浏览器到入口是 HTTPS，因此可以接受并发送 Secure Cookie，入口到 Keycloak 使用 HTTP 本身不会造成该问题。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;解决方案&lt;/strong&gt;：确保浏览器到反向代理是 HTTPS（TLS 终结在代理层），并让代理把 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto: https&lt;/code&gt; 传给 Keycloak。代理到 Keycloak 走 HTTP 是正常的；如果外部确实只能使用 HTTP，开发环境才临时关闭 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;，生产环境应修复外部 TLS，而不是把 Cookie 安全属性关掉。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;第三关oidc-回调-uri-精确匹配&quot;&gt;第三关：OIDC 回调 URI 精确匹配&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;OAuth 2.0 规范要求 &lt;code dir=&quot;auto&quot;&gt;redirect_uri&lt;/code&gt; 必须与客户端注册的值&lt;strong&gt;完全一致&lt;/strong&gt;。多数重定向循环由此引起：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;注册值&lt;/th&gt;
&lt;th&gt;实际请求&lt;/th&gt;
&lt;th&gt;匹配？&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;✅&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;❌ 多了尾部斜杠&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;http://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;❌ 协议不同&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com:8443/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;❌ 端口不同&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;✅ Keycloak 可匹配，但生产环境仍建议收紧&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h3 id=&quot;在-keycloak-中检查&quot;&gt;在 Keycloak 中检查&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Keycloak Admin Console → Clients → &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;your-client&gt;&lt;/code&gt; → Settings → Valid Redirect URIs。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;建议&lt;/strong&gt;：开发阶段用通配符 &lt;code dir=&quot;auto&quot;&gt;https://myapp.example.com/*&lt;/code&gt;，生产环境收紧为精确路径。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;在-oauth2-proxy-中检查&quot;&gt;在 oauth2-proxy 中检查&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;--redirect-url&lt;/code&gt; 参数必须与 Keycloak 注册的 redirect URI 一致。如果不指定，oauth2-proxy 会自动构造为 &lt;code dir=&quot;auto&quot;&gt;https://&amp;#x3C;当前Host&gt;/oauth2/callback&lt;/code&gt;。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy 日志中搜索 callback URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;redirect&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;第四关tls-终结层次&quot;&gt;第四关：TLS 终结层次&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 部署在 Kubernetes 中时，典型的 TLS 终结拓扑：&lt;/p&gt;
&lt;pre&gt;graph LR
    Browser[浏览器 HTTPS] --&gt;|TLS| LB[负载均衡/Ingress&amp;#x3C;br/&gt;TLS 终结]
    LB --&gt;|HTTP :8080| KC[Keycloak Pod&amp;#x3C;br/&gt;HTTP]
    KC --&gt;|X-Forwarded-Proto: https| Redirect[生成 https:// redirect_uri]&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;如果 Keycloak 没有正确识别 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-Proto&lt;/code&gt;&lt;/strong&gt;，它会认为请求是 HTTP，于是生成的 redirect_uri 也是 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt;。浏览器访问 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt; 又被重定向到 Keycloak（这次可能走 HTTPS），形成循环。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;keycloak-26配置代理头不要照搬旧版-kc_proxy&quot;&gt;Keycloak 26+：配置代理头，不要照搬旧版 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY&lt;/code&gt;&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 当前的 Quarkus 配置使用 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS&lt;/code&gt;（命令行形式为 &lt;code dir=&quot;auto&quot;&gt;--proxy-headers&lt;/code&gt;）选择代理头格式。下面的示例适用于 TLS 在 Ingress 终结、Keycloak Pod 内使用 HTTP 的常见拓扑：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;env&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_HTTP_ENABLED&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;true&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_PROXY_HEADERS&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;xforwarded&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;xforwarded&lt;/code&gt; 对应 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 头；如果你的代理发送标准 &lt;code dir=&quot;auto&quot;&gt;Forwarded&lt;/code&gt; 头，则使用 &lt;code dir=&quot;auto&quot;&gt;forwarded&lt;/code&gt;。两者不要混用。关键不是把某个旧版 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY=edge&lt;/code&gt; 原样搬过来，而是让代理实际发送的头格式与 Keycloak 配置一致，并固定公网主机名：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;env&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_HOSTNAME&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://keycloak.example.com&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;KC_PROXY&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;proxy=edge&lt;/code&gt; 等旧版示例在网上仍很常见，但不应作为 Keycloak 26+ 的默认配置。升级时先执行 &lt;code dir=&quot;auto&quot;&gt;kc.sh show-config&lt;/code&gt;，确认最终生效的配置，再删除已弃用或不再识别的参数。不要为了“先能跑”关闭 hostname 校验。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;检查项&lt;/th&gt;
&lt;th&gt;正确做法&lt;/th&gt;
&lt;th&gt;典型误区&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;代理头格式&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS=xforwarded&lt;/code&gt; 配合 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;配置为 &lt;code dir=&quot;auto&quot;&gt;forwarded&lt;/code&gt;，代理却只发送 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;公网地址&lt;/td&gt;
&lt;td&gt;使用 &lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME=https://keycloak.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;依赖内部 Service 名称自动推断&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;TLS 终结&lt;/td&gt;
&lt;td&gt;外部 HTTPS、内部 HTTP 时启用 &lt;code dir=&quot;auto&quot;&gt;KC_HTTP_ENABLED=true&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;让 Keycloak 误以为外部也是 HTTP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;旧配置&lt;/td&gt;
&lt;td&gt;升级前后用 &lt;code dir=&quot;auto&quot;&gt;kc.sh show-config&lt;/code&gt; 对比&lt;/td&gt;
&lt;td&gt;继续堆叠 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY=edge&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME_STRICT=false&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Keycloak 24 及更早版本&lt;/strong&gt;的配置语义不同。维护旧集群时按对应版本文档操作；不要把旧配置和新配置混在同一个 Deployment 里。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;hostname v2 的完整选项映射（v1 → v2）、四种部署拓扑的最小配置、启动校验错误文本与 issuer / 邮件链接排错，见 &lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-hostname-v2-config/&quot;&gt;Keycloak Hostname v2 配置与 v1 选项迁移&lt;/a&gt;。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;div&gt;&lt;h3 id=&quot;验证&quot;&gt;验证&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 在 Keycloak 管理控制台检查&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Realm Settings → General → Frontend URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 如果设置了，它会覆盖自动检测的 URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 排查时先清空这个字段，让 Keycloak 自动检测&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;第五关token-校验失败导致-401&quot;&gt;第五关：Token 校验失败导致 401&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;如果登录流程完成（Keycloak 返回了 code，应用换到了 token），但后续请求仍然 401：&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;audience-不匹配&quot;&gt;Audience 不匹配&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;oauth2-proxy 的 Keycloak OIDC Provider 会校验 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;（audience），并要求其中包含 &lt;code dir=&quot;auto&quot;&gt;--client-id&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;--oidc-extra-audience&lt;/code&gt; 配置的值。Keycloak 客户端如果没有把 oauth2-proxy 的 client ID 写入 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;，就会出现 &lt;code dir=&quot;auto&quot;&gt;expected audience&lt;/code&gt; 错误；不要把这个结论绑定到某个旧版本号，实际行为应以所部署版本的 Provider 文档和启动日志为准。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;// 错误日志&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;{&lt;/span&gt;&lt;span&gt;&quot;error&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;invalid_token&quot;&lt;/span&gt;&lt;span&gt;, &lt;/span&gt;&lt;span&gt;&quot;error_description&quot;&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;expected audience &lt;/span&gt;&lt;span&gt;\&quot;&lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt;\&quot;&lt;/span&gt;&lt;span&gt; got [&lt;/span&gt;&lt;span&gt;\&quot;&lt;/span&gt;&lt;span&gt;account&lt;/span&gt;&lt;span&gt;\&quot;&lt;/span&gt;&lt;span&gt;]&quot;&lt;/span&gt;&lt;span&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;解决&lt;/strong&gt;：在 Keycloak 客户端的 dedicated client scope 中添加 Audience mapper，把 &lt;code dir=&quot;auto&quot;&gt;Included Client Audience&lt;/code&gt; 设为 oauth2-proxy 的 client ID。至少勾选 &lt;strong&gt;Add to ID token&lt;/strong&gt;；如果 oauth2-proxy 配置了 &lt;code dir=&quot;auto&quot;&gt;--pass-access-token&lt;/code&gt;，或后端还会校验它转发的 Access Token，同时勾选 &lt;strong&gt;Add to access token&lt;/strong&gt;。保存后必须重新走一遍登录流程，旧 Cookie/Token 不会被 mapper 修复。&lt;/p&gt;
&lt;p&gt;不要为了消除 401 而关闭 audience 校验或把任意 audience 加入白名单：&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 表示 Token 的预期接收方，扩大允许列表会把发给其他应用的 Token 引入当前网关。oauth2-proxy 官方 Keycloak OIDC 文档明确要求 audience mapper，并说明其校验 &lt;code dir=&quot;auto&quot;&gt;--client-id&lt;/code&gt; 或 &lt;code dir=&quot;auto&quot;&gt;--oidc-extra-audience&lt;/code&gt;；实际部署还应分别检查 ID Token 和 Access Token 的用途。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;issuer-url-不一致&quot;&gt;Issuer URL 不一致&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;oauth2-proxy 从 &lt;code dir=&quot;auto&quot;&gt;--oidc-issuer-url&lt;/code&gt; 构造 discovery URL。如果配置的 issuer 与 Keycloak 实际签发的不一致，JWT 校验会失败。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 检查 Keycloak 实际 issuer&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;.issuer&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 输出例: &quot;https://keycloak.example.com/realms/myrealm&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy 的 --oidc-issuer-url 必须完全一致（尾部不带斜杠）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 正确: --oidc-issuer-url=https://keycloak.example.com/realms/myrealm&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 错误: --oidc-issuer-url=https://keycloak.example.com/realms/myrealm/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 错误: --oidc-issuer-url=https://keycloak.example.com （漏了 /realms/myrealm）&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak 17+ 默认使用 /realms/&amp;#x3C;realm&gt;；旧版常见 /auth/realms/&amp;#x3C;realm&gt;，不要跨版本照搬。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;token-时间偏差-nbfexp&quot;&gt;Token 时间偏差 (nbf/exp)&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;如果 Keycloak 容器和 oauth2-proxy 容器之间时钟偏差超过 Token 的 &lt;code dir=&quot;auto&quot;&gt;nbf&lt;/code&gt;（not before）或 &lt;code dir=&quot;auto&quot;&gt;exp&lt;/code&gt;（expiration）窗口：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 检查各 Pod 的时间&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;date&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;date&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 不要套用固定的“可接受秒数”；按实际 nbf/exp、部署的 clock-skew&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 配置和验证库行为判断，并确保所有节点由 NTP/chrony 同步&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;常见错误症状速查表&quot;&gt;常见错误症状速查表&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状&lt;/th&gt;
&lt;th&gt;浏览器表现&lt;/th&gt;
&lt;th&gt;最可能原因&lt;/th&gt;
&lt;th&gt;优先检查&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;登录后立即回到登录页&lt;/td&gt;
&lt;td&gt;URL 在 login 和 app 之间闪烁&lt;/td&gt;
&lt;td&gt;Cookie 未写入 / 被清除&lt;/td&gt;
&lt;td&gt;SameSite、Cookie Domain、Cookie Secure&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ERR_TOO_MANY_REDIRECTS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;浏览器直接报错&lt;/td&gt;
&lt;td&gt;redirect_uri 不匹配 / X-Forwarded-Proto 缺失&lt;/td&gt;
&lt;td&gt;反向代理 Header、Keycloak &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录成功显示 401&lt;/td&gt;
&lt;td&gt;页面空白或 JSON 错误&lt;/td&gt;
&lt;td&gt;Token 校验失败&lt;/td&gt;
&lt;td&gt;Audience mapper、issuer URL、时钟偏差&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;首次访问正常，刷新后 401&lt;/td&gt;
&lt;td&gt;Cookie 存在但被拒绝&lt;/td&gt;
&lt;td&gt;Cookie Secure 与 HTTP 冲突&lt;/td&gt;
&lt;td&gt;确认外部 HTTPS→内部 HTTP 的 TLS 终结&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;一个浏览器正常、另一个异常&lt;/td&gt;
&lt;td&gt;浏览器对第三方 Cookie、跟踪保护或站点上下文的处理差异&lt;/td&gt;
&lt;td&gt;SameSite、Cookie Domain、Secure 以及浏览器开发者工具中的阻止原因&lt;/td&gt;
&lt;td&gt;先看 Network/Storage 面板中的 Cookie 阻止理由，不要假定某个浏览器固定使用 Strict&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;子域名间跳转丢失登录&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;app1.example.com&lt;/code&gt; 和 &lt;code dir=&quot;auto&quot;&gt;app2.example.com&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cookie Domain 未覆盖子域&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--cookie-domain=.example.com&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Keycloak Admin Console 也重定向&lt;/td&gt;
&lt;td&gt;Admin Console 自身无法使用&lt;/td&gt;
&lt;td&gt;KC_HOSTNAME 配置问题&lt;/td&gt;
&lt;td&gt;检查 &lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME_ADMIN_URL&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h2 id=&quot;诊断命令速查&quot;&gt;诊断命令速查&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. 查看 Keycloak 日志 — 确认它看到的请求 URL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=100&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;redirect\|callback\|login&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. 用 curl 模拟完整流程，观察每一跳&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-v&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-L&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--cookie-jar&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/tmp/cookies.txt&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;https://myapp.example.com/&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&amp;#x26;1&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-E&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;^&amp;#x3C; HTTP|^&amp;#x3C; Location|^&amp;#x3C; Set-Cookie&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 检查 oauth2-proxy 日志&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 4. 检查 Ingress Controller 日志&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress-nginx&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/ingress-nginx-controller&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=50&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 5. 检查 Keycloak 是否正确识别代理头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 在 Keycloak Admin Console → Server Info → 搜索 &quot;proxy&quot; / &quot;hostname&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 或通过 Metrics 端点确认&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;http://localhost:9000/metrics&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak_requests&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 6. 解码 JWT 检查 issuer / audience&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 从浏览器 DevTools → Application → Cookies → 复制 KEYCLOAK_SESSION 或 AUTH_SESSION_ID&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 然后用 jwt.io 粘贴解码，检查 iss / aud / nbf / exp 字段&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;生产环境注意事项&quot;&gt;生产环境注意事项&lt;/h2&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;不要用 &lt;code dir=&quot;auto&quot;&gt;SameSite=None&lt;/code&gt; 作为万金油&lt;/strong&gt;：它允许跨站请求携带 Cookie，且必须同时设置 &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt;；只有确实需要跨站上下文时才使用。优先确认 OIDC 回调是否是顶级 GET 导航，以及 &lt;code dir=&quot;auto&quot;&gt;Lax&lt;/code&gt; 是否已经满足场景。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME_STRICT=false&lt;/code&gt; 不是长期方案&lt;/strong&gt;：在旧版 Keycloak 中常见，但它会放宽 hostname 校验，有安全风险。Keycloak 26+ 应明确配置 &lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;监视管理员的登录体验&lt;/strong&gt;：如果终端用户能登录但管理员不能，检查 &lt;code dir=&quot;auto&quot;&gt;KC_HOSTNAME_ADMIN_URL&lt;/code&gt; 是否配置。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;反向代理的 &lt;code dir=&quot;auto&quot;&gt;proxy_set_header Host $host&lt;/code&gt; 不能省&lt;/strong&gt;：Keycloak 需要知道外部 Host 来构建正确的 redirect_uri。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不要把 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 当作普通透传头&lt;/strong&gt;：入口代理必须覆盖客户端同名头，Keycloak 后端只允许可信代理访问；否则修复了重定向循环，却留下了 Host/IP 伪造的安全边界漏洞。&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;回滚方式&quot;&gt;回滚方式&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;如果排查过程中修改了反向代理配置导致服务不可用：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Nginx Ingress：回滚 ConfigMap 或 Ingress&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;rollout&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;undo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deployment/ingress-nginx-controller&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress-nginx&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# Keycloak Deployment：回滚环境变量改动&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;rollout&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;undo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deployment/keycloak&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy：回滚配置&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;rollout&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;undo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deployment/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;重要&lt;/strong&gt;：在修改反向代理或 Keycloak 环境变量之前，先用 &lt;code dir=&quot;auto&quot;&gt;kubectl get &amp;#x3C;resource&gt; -o yaml &gt; backup.yaml&lt;/code&gt; 导出当前配置。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;iam-faq&quot;&gt;IAM FAQ&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;iam-网关出现重定向循环先查-cookie-还是-keycloak&quot;&gt;IAM 网关出现重定向循环，先查 Cookie 还是 Keycloak？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;先沿浏览器的实际跳转链路定位：如果回调响应没有写入会话 Cookie，先看 Domain、Secure、SameSite 和代理协议；如果 Cookie 已写入但随后 401，再检查 OIDC Discovery、&lt;code dir=&quot;auto&quot;&gt;iss&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 和签名。不要把所有 401 都归因于 Keycloak 密码或 Cookie。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;iam-系统可以把-samesitestrict-作为默认值吗&quot;&gt;IAM 系统可以把 &lt;code dir=&quot;auto&quot;&gt;SameSite=Strict&lt;/code&gt; 作为默认值吗？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;不能直接假设可以。OIDC 登录通常需要从身份提供者返回应用回调端点；&lt;code dir=&quot;auto&quot;&gt;Strict&lt;/code&gt; 会缩小跨站请求携带 Cookie 的范围，可能使回调后的会话不可用。对常见的顶级 GET 回调，&lt;code dir=&quot;auto&quot;&gt;Lax&lt;/code&gt; 通常更符合需求，但最终应在目标浏览器的 Network/Storage 面板中验证，而不是只凭配置文件判断。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;iam-网关为什么不应该只靠扩大-cookie-domain-修复登录&quot;&gt;IAM 网关为什么不应该只靠扩大 Cookie Domain 修复登录？&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;扩大 Domain 会让 Cookie 发送给更多子域；如果其中存在不可信或可被接管的子域，会扩大会话暴露面。只有多个应用确实需要共享会话、且共同父域的所有子域都在同一信任边界内时，才使用父域 Cookie；否则为每个应用使用主机专属 Domain 和独立 Cookie 名称。&lt;/p&gt;
&lt;hr&gt;
&lt;div&gt;&lt;h2 id=&quot;延伸阅读&quot;&gt;延伸阅读&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/solution-blogs/keycloak-oauth2-proxy/&quot;&gt;Keycloak + oauth2-proxy 集成实战指南&lt;/a&gt;：完整配置 + audience mapper + Nginx Ingress auth-url 示例&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/protocols/oauth2-authorization-code-pkce/&quot;&gt;OAuth 2.0 深度解读 — 授权码流程与 PKCE&lt;/a&gt;：理解 redirect_uri 在授权码流程中的角色&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/protocols/oauth2-attack-surface/&quot;&gt;OAuth 2.0 攻击面图解&lt;/a&gt;：redirect_uri 劫持与 CSRF 防护&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.keycloak.org/server/hostname&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak 官方文档 — Configuring the hostname&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.keycloak.org/server/reverseproxy&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak 官方文档 — Configuring a reverse proxy&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.keycloak.org/server/reverseproxy&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak 官方文档：Reverse proxy headers&lt;/a&gt;：代理头格式、覆盖和来源校验&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 官方配置参考&lt;/a&gt;：&lt;code dir=&quot;auto&quot;&gt;redirect-url&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;cookie-samesite&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;set-xauthrequest&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy 官方 Keycloak OIDC 配置&lt;/a&gt;：issuer URL、Audience mapper、ID/Access Token claim 与角色/组授权&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ingress-nginx 外部认证示例&lt;/a&gt;：&lt;code dir=&quot;auto&quot;&gt;auth-url&lt;/code&gt; 与 &lt;code dir=&quot;auto&quot;&gt;auth-signin&lt;/code&gt; 的 Ingress 关系&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/keycloak/keycloak/issues/42997&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Keycloak GitHub Issue #42997&lt;/a&gt;：反向代理下登录重定向循环的实际案例&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues/3258&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy GitHub Issue #3258&lt;/a&gt;：并发回调与 CSRF 校验问题&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/oauth2-proxy/oauth2-proxy/issues?q=redirect+loop&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;oauth2-proxy GitHub Issues — redirect loop&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#domaindomain-value&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MDN：Set-Cookie 的 Domain 属性&lt;/a&gt;：前导点号已被浏览器忽略，以及 Domain 的匹配边界&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>oauth2-proxy</category><category>auth</category></item><item><title>IAM 网关：Keycloak + oauth2-proxy 保护内部应用</title><link>https://idaas.xlabs.club/blog/keycloak-oauth2-proxy-ingress-forwardauth/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-oauth2-proxy-ingress-forwardauth/</guid><description>IAM 网关使用 Keycloak 与 oauth2-proxy，通过 NGINX Ingress 或 Traefik ForwardAuth 为内部应用添加 OIDC 认证，覆盖可信代理、Cookie 与回滚。</description><pubDate>Fri, 03 Jul 2026 16:00:00 GMT</pubDate><content:encoded>&lt;p&gt;很多内部应用没有原生 OIDC 登录，或者不值得为了一个后台页面改业务代码。更稳的做法是在入口层放一个 &lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt;：浏览器先到 Keycloak 登录，&lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt; 建立会话，再由 NGINX Ingress &lt;code dir=&quot;auto&quot;&gt;auth_request&lt;/code&gt; 或 Traefik &lt;code dir=&quot;auto&quot;&gt;ForwardAuth&lt;/code&gt; 决定是否放行。&lt;/p&gt;
&lt;p&gt;这不是万能身份中台方案。它适合保护只需要「登录后可访问」或按组粗粒度授权的 Web 应用；如果后端需要细粒度 API 权限、租户隔离或可审计的业务授权，仍应在应用内实现 OIDC/JWT 校验和授权逻辑。网关层认证只能挡门，不能替应用做业务决策。保安不是产品经理，虽然有时都很想拦需求。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;适用与不适用场景&quot;&gt;适用与不适用场景&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;内部控制台、只给员工访问的管理页面&lt;/td&gt;
&lt;td&gt;适合。用 oauth2-proxy 统一接 Keycloak，按邮箱域、groups 或 roles 放行。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多个同域名子路径应用共用登录&lt;/td&gt;
&lt;td&gt;适合，但要统一 &lt;code dir=&quot;auto&quot;&gt;cookie-domain&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;redirect-url&lt;/code&gt; 和入口路径。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;后端只需要用户邮箱/用户名/组信息&lt;/td&gt;
&lt;td&gt;可用 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-*&lt;/code&gt; 头透传，但入口代理必须覆盖同名请求头，避免客户端伪造。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API 需要资源级权限、租户级权限、审计责任链&lt;/td&gt;
&lt;td&gt;不适合只靠网关认证。后端应验证 access token，并做授权判断。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;原生支持 OIDC 的 Grafana、GitLab、Vault 等&lt;/td&gt;
&lt;td&gt;优先用原生 OIDC；oauth2-proxy 更适合不支持 OIDC 的应用。&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h2 id=&quot;最小架构&quot;&gt;最小架构&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;Browser&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;-&gt; https://app.example.test&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;-&gt; NGINX Ingress auth-url / Traefik ForwardAuth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;-&gt; oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;-&gt; Keycloak realm: internal&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;-&gt; upstream app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;三个 URL 必须先定死：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;名称&lt;/th&gt;
&lt;th&gt;示例&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Keycloak issuer&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://sso.example.test/realms/internal&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;oauth2-proxy 发现 OIDC 端点。Keycloak 17+ 新部署默认不带 &lt;code dir=&quot;auto&quot;&gt;/auth&lt;/code&gt;。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;应用入口&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://app.example.test&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;用户访问的外部地址，也是 cookie 生效域。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;oauth2-proxy 回调&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://app.example.test/oauth2/callback&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Keycloak Client 的合法 Redirect URI。&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;上线前先访问：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-fsS&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://sso.example.test/realms/internal/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.issuer,.authorization_endpoint,.token_endpoint,.jwks_uri&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;返回的 &lt;code dir=&quot;auto&quot;&gt;issuer&lt;/code&gt; 必须和 &lt;code dir=&quot;auto&quot;&gt;--oidc-issuer-url&lt;/code&gt; 完全一致。差一个 &lt;code dir=&quot;auto&quot;&gt;/auth&lt;/code&gt;、协议或 host，后面就是 302 套娃现场。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;keycloak-端配置&quot;&gt;Keycloak 端配置&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;在目标 Realm 中创建一个 OpenID Connect Client：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;建议值&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Client ID&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Client authentication&lt;/td&gt;
&lt;td&gt;开启，使用 confidential client&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Standard flow&lt;/td&gt;
&lt;td&gt;开启&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Direct access grants&lt;/td&gt;
&lt;td&gt;关闭，除非有明确脚本登录需求&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Valid redirect URIs&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://app.example.test/oauth2/callback&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Web origins&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;https://app.example.test&lt;/code&gt; 或按实际域名配置&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;然后补两个 mapper：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Audience mapper&lt;/strong&gt;：把 &lt;code dir=&quot;auto&quot;&gt;Included Client Audience&lt;/code&gt; 设置为 &lt;code dir=&quot;auto&quot;&gt;oauth2-proxy&lt;/code&gt;。oauth2-proxy 的 OIDC 登录回调主要校验 ID Token 的 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt;；如果只在 access token 上增加 audience，回调仍可能报 &lt;code dir=&quot;auto&quot;&gt;expected audience&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;invalid aud&lt;/code&gt;，日志里常见只看到 &lt;code dir=&quot;auto&quot;&gt;account&lt;/code&gt;。除非后端确实需要该 claim，否则不要为了代理登录把 audience 无条件加到 access token。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Group Membership mapper&lt;/strong&gt;：把组写入 &lt;code dir=&quot;auto&quot;&gt;groups&lt;/code&gt; claim。若只按 realm role 控制，也可以用 oauth2-proxy 的 Keycloak OIDC provider role 选项，但 groups 更容易给 Ingress/后端统一消费。&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;生产环境建议单独建 Client，不要复用业务系统 Client。Client Secret 按密钥管理系统下发，轮换时先让 oauth2-proxy 支持新 Secret，再撤旧 Secret；别在发布窗口玩盲盒。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;oauth2-proxy-最小配置&quot;&gt;oauth2-proxy 最小配置&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;用环境变量承载密钥，配置文件只保留可审计的非敏感项：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# oauth2-proxy.cfg&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;provider&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;keycloak-oidc&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oidc_issuer_url&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;https://sso.example.test/realms/internal&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;client_id&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;oauth2-proxy&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;redirect_url&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;https://app.example.test/oauth2/callback&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;email_domains&lt;/span&gt;&lt;span&gt; = [&lt;/span&gt;&lt;span&gt;&quot;*&quot;&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;code_challenge_method&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;S256&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;cookie_secure&lt;/span&gt;&lt;span&gt; = true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;cookie_samesite&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;lax&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;cookie_domains&lt;/span&gt;&lt;span&gt; = [&lt;/span&gt;&lt;span&gt;&quot;.example.test&quot;&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;whitelist_domains&lt;/span&gt;&lt;span&gt; = [&lt;/span&gt;&lt;span&gt;&quot;.example.test&quot;&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;set_xauthrequest&lt;/span&gt;&lt;span&gt; = true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;set_authorization_header&lt;/span&gt;&lt;span&gt; = true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;pass_access_token&lt;/span&gt;&lt;span&gt; = true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;reverse_proxy&lt;/span&gt;&lt;span&gt; = true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 只填写实际反向代理的出口 CIDR；不要在生产环境无条件信任所有来源&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;trusted_proxy_ip&lt;/span&gt;&lt;span&gt; = &lt;/span&gt;&lt;span&gt;&quot;10.42.0.0/16&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;reverse_proxy=true&lt;/code&gt; 只表示 oauth2-proxy 运行在反向代理后面，不等于可以信任任意请求带来的 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; 头。&lt;code dir=&quot;auto&quot;&gt;trusted_proxy_ip&lt;/code&gt; 应替换为 ingress-nginx/Traefik 到 oauth2-proxy 的实际源地址范围；如果 oauth2-proxy 可被客户端直连，未限制可信代理范围时，攻击者可能伪造转发头，影响外部协议、主机或客户端 IP 的判断。先用集群网络配置和访问日志确认 CIDR，再放行，不能把示例网段原样复制到生产环境。&lt;/p&gt;
&lt;p&gt;对应 Secret：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;export&lt;/span&gt;&lt;span&gt; OAUTH2_PROXY_CLIENT_SECRET&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&apos;&amp;#x3C;keycloak-client-secret&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;export&lt;/span&gt;&lt;span&gt; OAUTH2_PROXY_COOKIE_SECRET&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&apos;&amp;#x3C;32-byte-base64-or-hex-secret&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--config=/etc/oauth2-proxy/oauth2-proxy.cfg&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;注意：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;cookie_secret&lt;/code&gt; 要足够长且稳定。Pod 重启就换 secret，会把所有会话打掉；发布没问题，用户会骂。&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;set_xauthrequest=true&lt;/code&gt; 会让 &lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt; 响应带 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-User&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Email&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-Groups&lt;/code&gt; 等头，适合 NGINX &lt;code dir=&quot;auto&quot;&gt;auth_request&lt;/code&gt; 模式。&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pass_access_token=true&lt;/code&gt; 会把 access token 放到响应头，只有后端确实需要 token 时才开，并限制入口到后端的可信网络边界。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;nginx-ingress-配置&quot;&gt;NGINX Ingress 配置&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;同一个 host 通常需要两个 Ingress：一个暴露 oauth2-proxy 的 &lt;code dir=&quot;auto&quot;&gt;/oauth2&lt;/code&gt; 路径，一个保护业务应用。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;apiVersion&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;networking.k8s.io/v1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Ingress&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;metadata&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;namespace&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;spec&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;ingressClassName&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;nginx&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;rules&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;host&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app.example.test&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;http&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;paths&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;path&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;/oauth2&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;pathType&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Prefix&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;backend&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;          &lt;/span&gt;&lt;span&gt;service&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;oauth2-proxy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;port&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;              &lt;/span&gt;&lt;span&gt;number&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;4180&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;---&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;apiVersion&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;networking.k8s.io/v1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Ingress&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;metadata&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;namespace&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;annotations&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-url&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://$host/oauth2/auth&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-signin&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://$host/oauth2/start?rd=$escaped_request_uri&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-response-headers&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-Groups,Authorization&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;spec&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;ingressClassName&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;nginx&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;rules&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;host&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app.example.test&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;http&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;paths&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;path&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;pathType&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Prefix&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;backend&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;          &lt;/span&gt;&lt;span&gt;service&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;port&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;              &lt;/span&gt;&lt;span&gt;number&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;80&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;如果要让后端读取用户信息，只信任 Ingress 注入的头；应用直连入口要禁掉，或者在后端清理来自外部请求的同名 header。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;traefik-forwardauth-配置&quot;&gt;Traefik ForwardAuth 配置&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Traefik 的思路相同：ForwardAuth middleware 先问 oauth2-proxy，允许后再转发到后端。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;apiVersion&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;traefik.io/v1alpha1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Middleware&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;metadata&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;oauth2-forwardauth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;namespace&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;spec&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;forwardAuth&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;address&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;http://oauth2-proxy.platform.svc.cluster.local:4180/oauth2/auth&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;authResponseHeaders&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;X-Auth-Request-User&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;X-Auth-Request-Email&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;X-Auth-Request-Groups&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;Authorization&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;---&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;apiVersion&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;networking.k8s.io/v1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kind&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Ingress&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;metadata&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;namespace&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;annotations&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;traefik.ingress.kubernetes.io/router.middlewares&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app-oauth2-forwardauth@kubernetescrd&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;spec&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;ingressClassName&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;traefik&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;rules&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;host&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;app.example.test&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;http&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;      &lt;/span&gt;&lt;span&gt;paths&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;&lt;span&gt;      &lt;/span&gt;&lt;/span&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;path&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;pathType&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;Prefix&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;        &lt;/span&gt;&lt;span&gt;backend&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;          &lt;/span&gt;&lt;span&gt;service&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;            &lt;/span&gt;&lt;span&gt;port&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;              &lt;/span&gt;&lt;span&gt;number&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;80&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;trustForwardHeader: true&lt;/code&gt; 只能在 Traefik 位于已验证的受信任入口之后使用；它不是“让转发头正常工作”的通用开关。若 Traefik 直接暴露给客户端，外部请求可能伪造 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;，进而污染 oauth2-proxy 对协议和 host 的判断。生产环境应限制 Traefik 的入口网络，并让 oauth2-proxy 只信任 Traefik 的源地址 CIDR；不需要信任上游转发头时，优先保持默认的严格边界。&lt;/p&gt;
&lt;p&gt;还需要把 &lt;code dir=&quot;auto&quot;&gt;/oauth2&lt;/code&gt; 路径路由到 oauth2-proxy，否则登录开始和回调没有入口。Traefik 场景下更容易遗漏这条路由，症状通常是 &lt;code dir=&quot;auto&quot;&gt;/oauth2/start&lt;/code&gt; 404 或登录后回不到应用。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;验证命令&quot;&gt;验证命令&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;按这个顺序查，能少走很多弯路：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 1. OIDC discovery 是否可访问，issuer 是否匹配&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-fsS&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://sso.example.test/realms/internal/.well-known/openid-configuration&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-r&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.issuer&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 2. oauth2-proxy 是否健康&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=100&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;platform&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;port-forward&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;svc/oauth2-proxy&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;4180:4180&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-i&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;http://127.0.0.1:4180/oauth2/auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 3. 外部入口是否能跳到 Keycloak&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-kI&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;https://app.example.test/&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;sed&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;1,12p&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 4. 登录后检查 cookie 与回调&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 浏览器开发者工具查看 /oauth2/callback 是否 Set-Cookie，Domain/SameSite/Secure 是否符合预期。&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 5. 后端是否收到认证头&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;logs&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;deploy/internal-app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--tail=100&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;access token 的 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 可以在测试环境临时解码确认：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;TOKEN&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&apos;&amp;#x3C;access-token&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;printf&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;%s&apos;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$TOKEN&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cut&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d.&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-f2&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;base64&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-d&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;|&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;jq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&apos;.aud,.groups&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;不要把生产 token 粘进在线解码网站。这个建议朴素，但能保平安。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;常见错误症状表&quot;&gt;常见错误症状表&lt;/h2&gt;&lt;/div&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;症状 / 日志&lt;/th&gt;
&lt;th&gt;常见根因&lt;/th&gt;
&lt;th&gt;修正方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;expected audience&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;invalid aud&lt;/code&gt;，&lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 里只有 &lt;code dir=&quot;auto&quot;&gt;account&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;oauth2-proxy 校验的 ID Token 没包含其 client ID&lt;/td&gt;
&lt;td&gt;在 Keycloak Client 增加 Audience mapper，至少勾选 &lt;strong&gt;Add to ID token&lt;/strong&gt;；后端确实验证 Access Token 时再单独勾选 &lt;strong&gt;Add to access token&lt;/strong&gt;。或在 oauth2-proxy 配置额外允许的 audience，但不要长期放宽校验。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;登录成功后反复跳转&lt;/td&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;redirect_url&lt;/code&gt;、Ingress &lt;code dir=&quot;auto&quot;&gt;auth-signin&lt;/code&gt;、cookie domain 或 SameSite 与真实入口不一致&lt;/td&gt;
&lt;td&gt;固定 &lt;code dir=&quot;auto&quot;&gt;redirect_url=https://app.example.test/oauth2/callback&lt;/code&gt;；跨子域再设置 &lt;code dir=&quot;auto&quot;&gt;.example.test&lt;/code&gt; cookie domain；检查外部 HTTPS 入口。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;csrf cookie not found&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;回调域名和发起登录域名不一致，或 cookie 被浏览器拒收&lt;/td&gt;
&lt;td&gt;统一 host；启用 HTTPS；检查 &lt;code dir=&quot;auto&quot;&gt;cookie_secure&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;cookie_samesite&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;cookie_domains&lt;/code&gt;。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/oauth2/auth&lt;/code&gt; 一直 401&lt;/td&gt;
&lt;td&gt;浏览器没有带 oauth2-proxy session cookie，或请求没有走同一个 host&lt;/td&gt;
&lt;td&gt;先确认 &lt;code dir=&quot;auto&quot;&gt;/oauth2/callback&lt;/code&gt; 是否成功 Set-Cookie，再查 Ingress/Traefik 路由是否共用同一 host。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;后端拿不到用户/邮箱/组&lt;/td&gt;
&lt;td&gt;oauth2-proxy 没开 &lt;code dir=&quot;auto&quot;&gt;set_xauthrequest&lt;/code&gt;，或 Ingress/ForwardAuth 没透传响应头&lt;/td&gt;
&lt;td&gt;开启 &lt;code dir=&quot;auto&quot;&gt;set_xauthrequest=true&lt;/code&gt;；NGINX 设置 &lt;code dir=&quot;auto&quot;&gt;auth-response-headers&lt;/code&gt;；Traefik 设置 &lt;code dir=&quot;auto&quot;&gt;authResponseHeaders&lt;/code&gt;。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Keycloak 回调 URL 变成 &lt;code dir=&quot;auto&quot;&gt;http://&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;反向代理没有正确设置或覆盖 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;Forwarded&lt;/code&gt; 头&lt;/td&gt;
&lt;td&gt;Keycloak 生产部署配置 hostname/proxy headers；入口代理必须覆盖来自客户端的转发头。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Keycloak 17+ issuer 不匹配&lt;/td&gt;
&lt;td&gt;沿用旧 WildFly &lt;code dir=&quot;auto&quot;&gt;/auth/realms/&amp;#x3C;realm&gt;&lt;/code&gt; 路径&lt;/td&gt;
&lt;td&gt;新部署使用 &lt;code dir=&quot;auto&quot;&gt;/realms/&amp;#x3C;realm&gt;&lt;/code&gt;；只有旧版本或明确保留兼容路径时才使用 &lt;code dir=&quot;auto&quot;&gt;/auth/realms/&amp;#x3C;realm&gt;&lt;/code&gt;。&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Traefik 登录入口 404&lt;/td&gt;
&lt;td&gt;只配置了 ForwardAuth，没把 &lt;code dir=&quot;auto&quot;&gt;/oauth2&lt;/code&gt; 路径路由到 oauth2-proxy&lt;/td&gt;
&lt;td&gt;给 &lt;code dir=&quot;auto&quot;&gt;app.example.test/oauth2/*&lt;/code&gt; 增加到 oauth2-proxy 的 Router/Ingress。&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;div&gt;&lt;h2 id=&quot;生产检查清单&quot;&gt;生产检查清单&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; Keycloak issuer、oauth2-proxy &lt;code dir=&quot;auto&quot;&gt;oidc_issuer_url&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;.well-known&lt;/code&gt; 返回值完全一致。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; Client Redirect URI 精确到 &lt;code dir=&quot;auto&quot;&gt;/oauth2/callback&lt;/code&gt;，没有无约束通配。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; access token 的 &lt;code dir=&quot;auto&quot;&gt;aud&lt;/code&gt; 包含 oauth2-proxy Client ID。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; groups/roles claim 命名和 oauth2-proxy 配置一致。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; cookie secret 稳定保存，不随 Pod 重建变化。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; 所有外部入口使用 HTTPS，Cookie &lt;code dir=&quot;auto&quot;&gt;Secure&lt;/code&gt; 生效。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; &lt;code dir=&quot;auto&quot;&gt;reverse_proxy&lt;/code&gt;、&lt;code dir=&quot;auto&quot;&gt;trusted_proxy_ip&lt;/code&gt; 与 Traefik &lt;code dir=&quot;auto&quot;&gt;trustForwardHeader&lt;/code&gt; 只信任已核实的代理网络，oauth2-proxy 不可被客户端绕过直连。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; 后端只信任来自入口代理的 &lt;code dir=&quot;auto&quot;&gt;X-Auth-Request-*&lt;/code&gt; 头，禁止绕过 Ingress/Traefik 直连。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; 日志里不打印 access token、ID token、client secret。&lt;/li&gt;
&lt;li&gt;&lt;input type=&quot;checkbox&quot; disabled&gt; 有一键回滚方式：移除认证中间件/注解，而不是删除 Keycloak Client。&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;回滚方式&quot;&gt;回滚方式&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;NGINX Ingress 回滚最小动作：删除业务 Ingress 上的三条认证注解，保留 oauth2-proxy Deployment、Service 和 Keycloak Client，方便事后复盘。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;annotate&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-url-&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-signin-&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;nginx.ingress.kubernetes.io/auth-response-headers-&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Traefik 回滚最小动作：移除业务 Ingress/IngressRoute 上的 ForwardAuth middleware 引用，保留 oauth2-proxy 路由。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;annotate&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;ingress&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;internal-app&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;traefik.ingress.kubernetes.io/router.middlewares-&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;回滚后先确认业务恢复，再排查 audience、cookie、转发头。事故中最怕一边修配置一边删资源，最后连案发现场都没了。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;相关章节&quot;&gt;相关章节&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/keycloak/integrations/&quot;&gt;Keycloak 与第三方开源软件集成&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/keycloak/troubleshooting/&quot;&gt;Keycloak 常见问题排查&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://idaas.xlabs.club/docs/implementation/kubernetes-production/&quot;&gt;Keycloak Kubernetes 生产部署&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;div&gt;&lt;h2 id=&quot;参考资料&quot;&gt;参考资料&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;oauth2-proxy Keycloak OIDC provider 文档：&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;oauth2-proxy 配置总览：&lt;a href=&quot;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;ingress-nginx External OAUTH Authentication 示例：&lt;a href=&quot;https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Traefik ForwardAuth middleware 文档：&lt;a href=&quot;https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/forwardauth/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/forwardauth/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Keycloak hostname/proxy headers 文档：&lt;a href=&quot;https://www.keycloak.org/server/hostname&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/server/hostname&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Keycloak OIDC endpoints 文档：&lt;a href=&quot;https://www.keycloak.org/securing-apps/oidc-layers&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;https://www.keycloak.org/securing-apps/oidc-layers&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>oauth2-proxy</category><category>auth</category></item><item><title>Keycloak HTTPS Required 错误与反向代理排错指南</title><link>https://idaas.xlabs.club/blog/keycloak-https-required/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-https-required/</guid><description>Keycloak 报 HTTPS required 或 Invalid redirect_uri 的排查：核对 KC_PROXY_HEADERS、KC_HOSTNAME 与反向代理 X-Forwarded-* 头。</description><pubDate>Sun, 31 Mar 2024 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;问题描述&quot;&gt;问题描述&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;以 Http 方式登录，页面错误提示如下。&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;We&apos;re sorry... HTTPS required.&lt;/code&gt;&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;问题原因&quot;&gt;问题原因&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 各个 Realm 默认的登录设置里，&lt;code dir=&quot;auto&quot;&gt;Require SSL&lt;/code&gt; 为 &lt;code dir=&quot;auto&quot;&gt;external requests&lt;/code&gt;，对于外部请求，必须是 Https。
非外部请求，也就是私有地址，可以是 http，如：&lt;code dir=&quot;auto&quot;&gt;localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, 172.16.x.x&lt;/code&gt;。
详细参考&lt;a href=&quot;https://www.keycloak.org/docs/latest/server_installation/index.html#setting-up-https-ssl&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;官方文档说明&lt;/a&gt;。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;解决方案&quot;&gt;解决方案&lt;/h2&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;配置 https 并使用 https 登录，毫无疑问，这是正确的解决方案。&lt;/p&gt;
&lt;p&gt;生产环境可以在反向代理 / Ingress 上终结 TLS，但必须让 Keycloak 解析代理实际写入的头。Keycloak 26+ 使用 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS=xforwarded&lt;/code&gt;（或 &lt;code dir=&quot;auto&quot;&gt;forwarded&lt;/code&gt;），而不是照搬旧版 &lt;code dir=&quot;auto&quot;&gt;proxy=edge&lt;/code&gt;；同时固定公网地址，避免它根据内部请求推断回调地址。详见 &lt;a href=&quot;https://idaas.xlabs.club/blog/keycloak-redirect-loop-troubleshooting/&quot;&gt;Keycloak 26+ 代理头排错&lt;/a&gt; 和&lt;a href=&quot;https://idaas.xlabs.club/docs/keycloak/security-features/&quot;&gt;安全增强功能&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;例如 TLS 在 Ingress 终结、Keycloak Pod 内使用 HTTP，且 Ingress 覆盖写入 &lt;code dir=&quot;auto&quot;&gt;X-Forwarded-*&lt;/code&gt;：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;env&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_HTTP_ENABLED&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;true&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_PROXY_HEADERS&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;xforwarded&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;- &lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;KC_HOSTNAME&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;value&lt;/span&gt;&lt;span&gt;: &lt;/span&gt;&lt;span&gt;&quot;https://keycloak.example.com&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;如果代理发送的是标准 &lt;code dir=&quot;auto&quot;&gt;Forwarded&lt;/code&gt; 头，把 &lt;code dir=&quot;auto&quot;&gt;KC_PROXY_HEADERS&lt;/code&gt; 改为 &lt;code dir=&quot;auto&quot;&gt;forwarded&lt;/code&gt;；不要混用两种格式。代理必须覆盖而不是追加客户端提交的同名头，并把 Keycloak Service 限制为只能由受信任代理访问。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;如果只是测试环境，可以修改 Realm 的设置，&lt;code dir=&quot;auto&quot;&gt;Require SSL&lt;/code&gt; 改为 &lt;code dir=&quot;auto&quot;&gt;none&lt;/code&gt;。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;K8S 命令行调用 Keycloak 官方 admin 工具 &lt;code dir=&quot;auto&quot;&gt;kcadm&lt;/code&gt; 修改（Quarkus 版默认上下文路径为 &lt;code dir=&quot;auto&quot;&gt;/&lt;/code&gt;，已无 &lt;code dir=&quot;auto&quot;&gt;/auth&lt;/code&gt; 前缀）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# login with a admin user&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-it&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak-pod&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/opt/keycloak/bin/kcadm.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;config&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;credentials&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--server&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;http://localhost:8080&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--realm&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;master&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--user&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;admin&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--password&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;admin-password&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# update your realm config&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-it&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak-pod&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/opt/keycloak/bin/kcadm.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;update&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;realms/master&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-s&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;sslRequired=none&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;也可以直接在管理控制台 → Realm → Realm Settings → Login → Require SSL 处改为 &lt;code dir=&quot;auto&quot;&gt;none&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;blockquote&gt;
&lt;p&gt;⚠️ &lt;strong&gt;不建议&lt;/strong&gt;直接写库 &lt;code dir=&quot;auto&quot;&gt;update REALM set ssl_required=&apos;NONE&apos;&lt;/code&gt;：直接改库绕过了 Infinispan 缓存层，可能导致缓存与数据库不一致，且不在 Keycloak 官方支持范围内。请优先使用 &lt;code dir=&quot;auto&quot;&gt;kcadm.sh&lt;/code&gt; 或控制台。&lt;/p&gt;
&lt;/blockquote&gt;
</content:encoded><category>keycloak</category><category>auth</category></item><item><title>Keycloak Kubernetes 导入导出与数据迁移实战</title><link>https://idaas.xlabs.club/blog/keycloak-export-import-on-k8s/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-export-import-on-k8s/</guid><description>Keycloak 在 Kubernetes 环境下 Realm 导入导出与迁移：Helm/Operator 配置、volume 挂载与命令行导入的踩坑与方案</description><pubDate>Sun, 31 Mar 2024 16:00:00 GMT</pubDate><content:encoded>&lt;blockquote&gt;
&lt;p&gt;本文以 &lt;strong&gt;Keycloak Quarkus 发行版（17+）&lt;/strong&gt; 为准。Keycloak 17 起官方已移除 WildFly 发行版，旧版用 &lt;code dir=&quot;auto&quot;&gt;standalone.sh -Dkeycloak.migration.action=export&lt;/code&gt; 的导出方式不再适用，统一改用 &lt;code dir=&quot;auto&quot;&gt;kc.sh export&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;kc.sh import&lt;/code&gt;。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;div&gt;&lt;h2 id=&quot;问题描述&quot;&gt;问题描述&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 集群跑在 Kubernetes 上，初始化了一些配置，想完整地导出来备份或迁移。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;解决方案&quot;&gt;解决方案&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;命令行导出&quot;&gt;命令行导出&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Quarkus 版本使用 &lt;code dir=&quot;auto&quot;&gt;kc.sh export&lt;/code&gt; 一次性导出整个 Realm。&lt;code dir=&quot;auto&quot;&gt;export&lt;/code&gt; 子命令以「仅导出」模式启动，不会常驻监听端口，因此&lt;strong&gt;无需&lt;/strong&gt;像旧 WildFly 版本那样设置端口偏移规避端口冲突。&lt;/p&gt;
&lt;p&gt;导出为单个文件：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-it&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak-0&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/opt/keycloak/bin/kc.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;export&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;--file&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/tmp/keycloak-export.json&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--realm&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;myrealm&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;导出为目录（每个 Realm 一个文件）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-it&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;exec&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak-0&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/opt/keycloak/bin/kc.sh&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;export&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;--dir&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;/tmp/export&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;--realm&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;myrealm&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;blockquote&gt;
&lt;p&gt;若不指定 &lt;code dir=&quot;auto&quot;&gt;--realm&lt;/code&gt;，则导出&lt;strong&gt;除 &lt;code dir=&quot;auto&quot;&gt;master&lt;/code&gt; 外&lt;/strong&gt;的所有 Realm；&lt;code dir=&quot;auto&quot;&gt;master&lt;/code&gt; Realm 不参与导出。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;导出完成后，用 &lt;code dir=&quot;auto&quot;&gt;kubectl cp&lt;/code&gt; 把文件从 Pod 复制出来（注意 Pod 内 &lt;code dir=&quot;auto&quot;&gt;/tmp&lt;/code&gt; 通常才对当前用户可写）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;kubectl&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-n&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;cp&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;keycloak-0:/tmp/export&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;./keycloak-export&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;启动时导入&quot;&gt;启动时导入&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;Quarkus 版本通过 &lt;code dir=&quot;auto&quot;&gt;--import-realm&lt;/code&gt; 在启动时自动导入 &lt;code dir=&quot;auto&quot;&gt;data/import&lt;/code&gt; 目录下的 Realm JSON：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 容器启动参数 / 环境变量&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;KC_IMPORT&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;/opt/keycloak/data/import&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;KC_ARGS&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&quot;--import-realm&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;挂载好 Realm JSON 后首次启动即自动导入；之后不再重复导入。Operator / Helm 部署可在 &lt;code dir=&quot;auto&quot;&gt;Keycloak&lt;/code&gt; CR 或 values 中用 &lt;code dir=&quot;auto&quot;&gt;RealmImport&lt;/code&gt;（Operator）或 extraEnv 传入。&lt;/p&gt;
&lt;div&gt;&lt;h3 id=&quot;复杂配置导入报错&quot;&gt;复杂配置导入报错&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;若导出的配置较复杂（包含授权策略、自定义脚本等），导入时可能遇到：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;ERROR&lt;/span&gt;&lt;span&gt;: Script upload is disabled&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 已默认禁用内嵌脚本上传（出于安全考虑）。脚本类 SPI 应改为打成 JAR 放入 &lt;code dir=&quot;auto&quot;&gt;providers/&lt;/code&gt; 部署，而非通过导入 JSON 携带脚本。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;注意事项&quot;&gt;注意事项&lt;/h2&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;管理控制台也能导出，但导出&lt;strong&gt;不全&lt;/strong&gt;：密码、密钥等敏感信息不会包含，务必以命令行导出为准。&lt;/li&gt;
&lt;li&gt;导出的是普通 JSON 文件，可按需手工编辑再导入，不必每次改动都重新导出。&lt;/li&gt;
&lt;li&gt;Realm、用户、Client 也可通过 &lt;code dir=&quot;auto&quot;&gt;kcadm.sh&lt;/code&gt; 分别操作，特殊定制可拆分后独立导入。&lt;/li&gt;
&lt;li&gt;生产备份请结合数据库快照 + Realm JSON 双重保障，二者互为校验。&lt;/li&gt;
&lt;/ol&gt;
</content:encoded><category>keycloak</category><category>kubernetes</category></item><item><title>Keycloak Liquibase 与 MySQL 组复制冲突排查与解决</title><link>https://idaas.xlabs.club/blog/keycloak-liquibase-mysql-group-replication/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/keycloak-liquibase-mysql-group-replication/</guid><description>Keycloak 在 MySQL Group Replication 下 Liquibase 数据库迁移失败的排查与解决方案：锁表与迁移串行化</description><pubDate>Sun, 31 Mar 2024 16:00:00 GMT</pubDate><content:encoded>&lt;div&gt;&lt;h2 id=&quot;问题描述&quot;&gt;问题描述&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 对接的是一个 MGR(mysql group replication)的集群，安装时出错，数据初始化失败。&lt;/p&gt;
&lt;p&gt;查看 Keycloak 启动日志，错误信息大致如下（Quarkus 版日志形如）。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;ERROR&lt;/span&gt;&lt;span&gt; [&lt;/span&gt;&lt;span&gt;org.keycloak.connections.jpa.updater.liquibase.LiquibaseJpaUpdaterProvider&lt;/span&gt;&lt;span&gt;] (executor-thread-&lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;) Initializing database schema. Using changelog META-INF/jpa-&lt;/span&gt;&lt;span&gt;changelog-master.xml&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;ERROR&lt;/span&gt;&lt;span&gt; [&lt;/span&gt;&lt;span&gt;org.keycloak.connections.jpa.updater.liquibase.conn.DefaultLiquibaseConnectionProvider&lt;/span&gt;&lt;span&gt;] (executor-thread-&lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;) Change Set META-INF/jpa-&lt;/span&gt;&lt;span&gt;changelog-1.0.0.Final.xml&lt;/span&gt;&lt;span&gt;::&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;.&lt;/span&gt;&lt;span&gt;0&lt;/span&gt;&lt;span&gt;.&lt;/span&gt;&lt;span&gt;0&lt;/span&gt;&lt;span&gt;.Final-KEYCLOAK-&lt;/span&gt;&lt;span&gt;5461&lt;/span&gt;&lt;span&gt;::sthorger@&lt;/span&gt;&lt;span&gt;redhat.com&lt;/span&gt;&lt;span&gt; failed.  &lt;/span&gt;&lt;span&gt;Error&lt;/span&gt;&lt;span&gt;: Table &lt;/span&gt;&lt;span&gt;&apos;APPLICATION_DEFAULT_ROLES&apos;&lt;/span&gt;&lt;span&gt; already exists [Failed SQL: CREATE TABLE &lt;/span&gt;&lt;span&gt;keycloak.APPLICATION_DEFAULT_ROLES&lt;/span&gt;&lt;span&gt; (APPLICATION_ID VARCHAR(&lt;/span&gt;&lt;span&gt;36&lt;/span&gt;&lt;span&gt;) NOT NULL, ROLE_ID VARCHAR(&lt;/span&gt;&lt;span&gt;36&lt;/span&gt;&lt;span&gt;) NOT NULL)]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;ERROR&lt;/span&gt;&lt;span&gt; [&lt;/span&gt;&lt;span&gt;org.keycloak.services&lt;/span&gt;&lt;span&gt;] (executor-thread-&lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;java.lang.RuntimeException&lt;/span&gt;&lt;span&gt;: Failed to update database&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;查看 MySQL 日志，看到如下错误。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;[ERROR]&lt;/span&gt;&lt;span&gt; Plugin group_replication reported: &lt;/span&gt;&lt;span&gt;&apos;Table DATABASECHANGELOG does not have any PRIMARY KEY. This is not compatible with Group Replication&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;问题原因&quot;&gt;问题原因&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;根据 MySQL 日志，很明确了是因为 DATABASECHANGELOG 没有主键。MySQL group replication 要求表必须有主键或者非 Null 的唯一索引。&lt;/p&gt;
&lt;p&gt;keycloak 使用 Liquibase 初始化数据。Liquibase 自动创建的 DATABASECHANGELOG 表没有主键，主要是为了避免特定数据库 key 的长度限制。查看 &lt;a href=&quot;https://docs.liquibase.com/concepts/basic/databasechangelog-table.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Liquibase 官方说明&lt;/a&gt;，“id”, “author”, “filename”可以作为唯一索引。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;解决方案&quot;&gt;解决方案&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;解决办法也很简单，在 keycloak 启动之前，提前创建好 DATABASECHANGELOG 表并增加主键（或唯一性索引）。&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;CREATE&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;TABLE&lt;/span&gt;&lt;span&gt; `&lt;/span&gt;&lt;span&gt;DATABASECHANGELOG&lt;/span&gt;&lt;span&gt;` (&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`ID`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`AUTHOR`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`FILENAME`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`DATEEXECUTED`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;datetime&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`ORDEREXECUTED`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;int&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;11&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`EXECTYPE`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;10&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;NOT NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`MD5SUM`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;35&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`DESCRIPTION`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`COMMENTS`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`TAG`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`LIQUIBASE`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;20&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`CONTEXTS`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`LABELS`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;255&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;`DEPLOYMENT_ID`&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;varchar&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;10&lt;/span&gt;&lt;span&gt;) &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;NULL&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;PRIMARY KEY&lt;/span&gt;&lt;span&gt; (&lt;/span&gt;&lt;span&gt;`ID`&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt;`AUTHOR`&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt;`FILENAME`&lt;/span&gt;&lt;span&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;) ENGINE&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;InnoDB &lt;/span&gt;&lt;span&gt;DEFAULT&lt;/span&gt;&lt;span&gt; CHARSET&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;utf8mb4;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;问题症状&quot;&gt;问题症状&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Keycloak 启动时 Liquibase 报错，无法完成数据库迁移：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;ERROR: Liquibase failed to start because the database is read-only&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;or the current user lacks write permissions.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;在 MySQL Group Replication 环境中，节点切换期间可能出现短暂只读状态，导致 Liquibase 的 &lt;code dir=&quot;auto&quot;&gt;DATABASECHANGELOGLOCK&lt;/code&gt; 表写入失败。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;根因分析&quot;&gt;根因分析&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;Liquibase 使用 &lt;code dir=&quot;auto&quot;&gt;DATABASECHANGELOGLOCK&lt;/code&gt; 表实现分布式锁，防止多个 Keycloak 实例同时执行数据库迁移。在 MySQL Group Replication 环境下：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;写节点（Primary）故障转移时，新 Primary 有短暂的只读窗口&lt;/li&gt;
&lt;li&gt;如果 Keycloak 恰好在此时启动，Liquibase 获取锁失败&lt;/li&gt;
&lt;li&gt;Keycloak 默认会重试，但默认重试策略不够适应 GR 的切换耗时&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;解决方案-1&quot;&gt;解决方案&lt;/h2&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;方案一延长-liquibase-重试&quot;&gt;方案一：延长 Liquibase 重试&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;在 Keycloak 配置中增加 Liquibase 的重试参数（Keycloak 21+ 支持）：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 环境变量方式&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;KC_DB_URL&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;jdbc:mysql://...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;KC_SPI_LIQUIBASE_RETRY_COUNT&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;10&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;KC_SPI_LIQUIBASE_RETRY_DELAY&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;5&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;方案二调整-mysql-gr-参数&quot;&gt;方案二：调整 MySQL GR 参数&lt;/h3&gt;&lt;/div&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;-- 降低只读窗口时间&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;SET&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;GLOBAL&lt;/span&gt;&lt;span&gt; group_replication_member_expel_timeout &lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;10&lt;/span&gt;&lt;span&gt;;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;SET&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;GLOBAL&lt;/span&gt;&lt;span&gt; group_replication_unreachable_majority_timeout &lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;30&lt;/span&gt;&lt;span&gt;;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h3 id=&quot;方案三预检查数据库可写性&quot;&gt;方案三：预检查数据库可写性&lt;/h3&gt;&lt;/div&gt;
&lt;p&gt;在 Keycloak 启动脚本中增加预检查：&lt;/p&gt;
&lt;div&gt;&lt;figure&gt;&lt;figcaption&gt;&lt;span&gt;&lt;/span&gt;&lt;/figcaption&gt;&lt;pre&gt;&lt;code&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;# 等待 MySQL 可写&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;for&lt;/span&gt;&lt;span&gt; i &lt;/span&gt;&lt;span&gt;in&lt;/span&gt;&lt;span&gt; $(&lt;/span&gt;&lt;span&gt;seq&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;30&lt;/span&gt;&lt;span&gt;); &lt;/span&gt;&lt;span&gt;do&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;if&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;mysql&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-h&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$DB_HOST&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-u&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$DB_USER&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-p&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;$DB_PASS&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;-e&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;SELECT 1&quot;&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&gt;&lt;/span&gt;&lt;span&gt;/dev/null&lt;/span&gt;&lt;span&gt;; &lt;/span&gt;&lt;span&gt;then&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;echo&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;&quot;MySQL ready&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;    &lt;/span&gt;&lt;span&gt;break&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;fi&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;  &lt;/span&gt;&lt;span&gt;sleep&lt;/span&gt;&lt;span&gt; &lt;/span&gt;&lt;span&gt;2&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div&gt;&lt;div&gt;&lt;span&gt;done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;div&gt;&lt;h2 id=&quot;预防措施&quot;&gt;预防措施&lt;/h2&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;在 Kubernetes 中为 Keycloak Pod 配置 &lt;code dir=&quot;auto&quot;&gt;initContainer&lt;/code&gt; 做数据库就绪检查&lt;/li&gt;
&lt;li&gt;MySQL GR 集群设置合理的故障转移超时，避免 Keycloak 启动窗口与 GR 切换窗口重叠&lt;/li&gt;
&lt;li&gt;生产环境建议使用 PostgreSQL，避免 MySQL GR 的只读状态问题&lt;/li&gt;
&lt;/ul&gt;
</content:encoded><category>keycloak</category><category>database</category></item><item><title>Windows Server AD 域服务安装与 LDAPS 启用完整指南</title><link>https://idaas.xlabs.club/blog/windows-ad/</link><guid isPermaLink="true">https://idaas.xlabs.club/blog/windows-ad/</guid><description>Windows Server AD 域服务从零安装：添加域服务角色、配置新林域控、用户与组管理、LDAPS 证书配置，适用于 Keycloak 对接前的测试环境搭建</description><pubDate>Mon, 14 Dec 2020 15:54:37 GMT</pubDate><content:encoded>&lt;p&gt;说明：此步骤仅仅是为了如何快速搭建起一个测试版 Windows AD 服务，不可用于生产。&lt;/p&gt;
&lt;div&gt;&lt;h2 id=&quot;前置条件&quot;&gt;前置条件&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;安装 Windows AD 域控服务器，需要提前准备：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Windows Server 2008 及更新版本操作系统，如 4 核 8G 内存，60G 硬盘的主机一台。&lt;/li&gt;
&lt;li&gt;提前规划好域名，比如本示例为 iam.nxest.local.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Windows Server 不同版本略有差异，但是基本要做的就是下面几项：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;启用功能：角色和功能里添加 Windows AD 域服务。&lt;/li&gt;
&lt;li&gt;配置：配置 AD 域名、管理员密码等基本信息。&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;windows-server-2012-步骤如下&quot;&gt;Windows Server 2012 步骤如下&lt;/h2&gt;&lt;/div&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;点击开始菜单，找到“服务器管理器”，打开，显示如下界面。
&lt;a href=&quot;./ad-001.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;764&quot; height=&quot;499&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-001.qO09sOIY_Z1AtaMH.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;点击右上角 管理&gt;“添加角色和功能”按钮，弹出如下界面。
&lt;a href=&quot;./ad-002.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1466&quot; height=&quot;729&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-002.CwdyR_Q__DRLJD.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;选择“基于角色或基于功能的安装”，然后点“下一步”。
&lt;a href=&quot;./ad-003.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1192&quot; height=&quot;834&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-003.YVhGQBwy_1Qtryk.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;服务器选择这里选择默认的，假如你需要针对其它主机安装 AD 角色，这里可以选择你需要的主机，点击“下一步”。
&lt;a href=&quot;./ad-004.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1194&quot; height=&quot;838&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-004.ekliiGNw_qnQUE.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;这里勾选“Active Directory 域服务”。
&lt;a href=&quot;./ad-005.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1185&quot; height=&quot;835&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-005.SH2zhGi4_XH47K.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;当勾选这个选项时，会弹出对话框，点“添加功能”，在功能这个选项卡直接点下一步，一直下一步直到最后一步点击安装。
&lt;a href=&quot;./ad-006.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1197&quot; height=&quot;828&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-006.DKMo_1Fm_2aTm9b.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;安装成功后我们点击“关闭”，但这还没有完全安装成功，还需要继续配置。点击服务器右上角的“功能按钮”, 弹出继续配置 AD 的对话框。
&lt;a href=&quot;./ad-007.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1459&quot; height=&quot;741&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-007.Cd4spnda_ZP0Cph.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;根据提示，添加新林，输入准备好的域名。
&lt;a href=&quot;./ad-008.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1157&quot; height=&quot;829&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-008.jtmA5FOS_Z20yiAC.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;林功能级别选择最高的版本。
&lt;a href=&quot;./ad-009.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1167&quot; height=&quot;825&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-009.WC7KFYWR_14vMOo.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;输入 NetBIOS 域名，都是简称，一般是你准备的域名的第一位。
&lt;a href=&quot;./ad-010.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1143&quot; height=&quot;826&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-010.Wl6Hez3Y_24OIEm.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;下一步，默认即可。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;下一步，先决条件检查，可能花费 10 分钟左右，请耐心等待。
&lt;a href=&quot;./ad-012.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1173&quot; height=&quot;834&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-012.z5w3oAm7_Z1W5uAN.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;检查通过后才能点击安装。
&lt;a href=&quot;./ad-013.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;1164&quot; height=&quot;826&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-013.B8AliJQl_17Bk8h.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;安装完成后，会提示注销重启，如果未提示重启，请手动重启下服务器。
&lt;a href=&quot;./ad-014.png&quot;&gt;&lt;img alt=&quot;AD&quot; loading=&quot;lazy&quot; decoding=&quot;async&quot; width=&quot;865&quot; height=&quot;412&quot; src=&quot;https://idaas.xlabs.club/_astro/ad-014.ChvHNQJT_1XaOX5.webp&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;div&gt;&lt;h2 id=&quot;用户管理&quot;&gt;用户管理&lt;/h2&gt;&lt;/div&gt;
&lt;p&gt;安装完成后，可通过“Active Directory 用户和计算机”管理用户。此功能可通过控制面板或菜单搜索到。&lt;/p&gt;
&lt;p&gt;打开后即可在 Users 下右键创建组和用户，请根据需要提前划分分组，增加用户。&lt;/p&gt;
</content:encoded><category>active-directory</category></item></channel></rss>