本地开发环境中Keycloak与React的无限重定向循环问题

DevOps 小满

2026-6-14

本地开发环境Keycloak登录后无限重定向问题（v15.0.2）

问题背景

维护的旧React应用用Keycloak 15.0.2做身份认证，本地开发时登录成功后浏览器就陷入无限重定向，在http://localhost:3000和带state、session_state、code参数的同地址来回跳。生产、预生产环境完全正常，已经排除<React.StrictMode>的影响，试过设置checkLoginIframe: false、禁用Chrome的SameSite安全设置，都没解决。

初始化代码如下：

<ReactKeycloakProvider
    authClient={keycloak}
    initOptions={{
      onLoad: "check-sso",
      silentCheckSsoRedirectUri: window.location.origin + "/silent-check-sso.html"
    }}
    LoadingComponent={<KeycloakLoadingComponent/>}
>
  <AppContent/>
</ReactKeycloakProvider>

解决办法

1. 检查`silent-check-sso.html`文件

先确认项目public文件夹里有没有silent-check-sso.html，内容得是下面这样：

<!DOCTYPE html>
<html>
<body>
  <script>
    parent.postMessage(location.href, location.origin);
  </script>
</body>
</html>

要是文件丢了或者内容不对，静默SSO校验会失败，直接触发重复重定向。

2. 调整初始化参数

在initOptions里加上pkceMethod: 'S256'，同时去Keycloak控制台把对应客户端的PKCE功能打开：

initOptions={{
  onLoad: "check-sso",
  silentCheckSsoRedirectUri: window.location.origin + "/silent-check-sso.html",
  pkceMethod: 'S256',
  checkLoginIframe: false
}}

旧版本Keycloak在本地HTTP环境下，没开PKCE的话授权码交换容易出问题，导致循环重定向。

3. 核对Keycloak客户端的重定向URI

登录Keycloak控制台，找到对应客户端的Valid Redirect URIs，必须包含http://localhost:3000/*（注意带通配符）。要是只配了http://localhost:3000，带参数的回调地址会被拒绝，Keycloak就会重新发起授权请求。

4. 统一本地环境的协议

如果本地开发服务器强制用HTTPS（比如.env里设了HTTPS=true），但Keycloak客户端配的是HTTP重定向URI，协议不匹配也会触发循环。要么本地改回HTTP，要么把Keycloak的重定向URI改成https://localhost:3000/*。

5. 清浏览器缓存和Cookie

本地环境里残留的旧Keycloak会话Cookie可能搞乱校验逻辑，彻底清掉localhost相关的Cookie和缓存再重新测。

内容的提问来源于stack exchange，提问作者becharn