Keycloak v26对接React应用时出现登录无限循环问题求助

环境与代码说明 #

• 生产环境使用Keycloak v26，依赖库版本：keycloak-js: "^26.0.0"
• 严格遵循官方JavaScript适配器文档及教程编写React认证Hook，代码如下：

import { useEffect, useState } from "react"
import Keycloak from 'keycloak-js';

const useAuth = () => {

  const [isLoading, setIsLoading] = useState(false);
  const [isLoggedIn, setisLoggedIn] = useState(false);

  useEffect(() => {
    setIsLoading(true);
    const client = new Keycloak({
      url: `${import.meta.env.VITE_KEYCLOAK_URL}`,
      realm: import.meta.env.VITE_KEYCLOAK_REALM,
      clientId: import.meta.env.VITE_KEYCLOAK_CLIENT_ID,
    });
    
    console.log('client created', client);

    client.init({
      onLoad: 'login-required',
    })
    .then((res) => {
      console.log('res', res);
      setisLoggedIn(true);
    })
    .finally(() => {
      setIsLoading(false);
    });

  }, []);

  return {isLoggedIn, isLoading};
}

export default useAuth

当前问题 #

应用出现登录无限循环问题，相关请求Payload及循环状态截图已提供。已严格按文档配置，请求排查问题原因。

排查方向与解决方案 #

1. Keycloak实例重复初始化 #

当前Hook每次组件挂载都会新建Keycloak实例，页面重定向后组件重新挂载，新实例无法读取之前的认证状态，会再次触发登录流程，导致循环。

• 修复方案：将Keycloak实例提升到全局作用域缓存，避免重复创建：

// 全局创建实例，仅初始化一次
const keycloakInstance = new Keycloak({
  url: import.meta.env.VITE_KEYCLOAK_URL,
  realm: import.meta.env.VITE_KEYCLOAK_REALM,
  clientId: import.meta.env.VITE_KEYCLOAK_CLIENT_ID,
});

const useAuth = () => {
  const [isLoading, setIsLoading] = useState(false);
  const [isLoggedIn, setisLoggedIn] = useState(false);

  useEffect(() => {
    setIsLoading(true);
    keycloakInstance.init({
      onLoad: 'login-required',
      // 开启状态持久化，默认sessionStorage，可按需改为localStorage
      persistence: 'sessionStorage'
    })
    .then((res) => {
      console.log('认证结果:', res);
      // 直接用init返回的布尔值设置登录状态，避免硬编码为true
      setisLoggedIn(res);
    })
    .catch(err => {
      console.error('Keycloak初始化失败:', err);
    })
    .finally(() => {
      setIsLoading(false);
    });
  }, []);

  return {isLoggedIn, isLoading, keycloakInstance};
}

2. 客户端重定向URI配置错误 #

检查Keycloak控制台中对应客户端的Valid Redirect URIs，必须包含当前应用的完整域名（如生产环境https://your-app-domain/*，开发环境http://localhost:5173/*）。若URI不匹配，Keycloak会拒绝认证并跳转回应用，触发重复登录。

• 验证方式：查看浏览器网络请求，认证回调阶段是否返回invalid_redirect_uri错误。

3. 认证状态参数丢失 #

Keycloak登录后会通过code和state参数传递认证状态，若这些参数被路由拦截或清除，适配器无法完成认证流程，会再次触发登录。

• 检查React路由配置，确保认证回调路径（通常是应用根路径）不会自动清除URL参数；
• 在init执行前打印window.location.search，确认参数是否存在。

4. HTTPS环境Cookie配置问题 #

生产环境使用HTTPS时，需调整Keycloak Realm的Cookie配置：

• 将Cookie Secure设为On；
• 根据跨域情况设置Cookie SameSite为Lax或None；
• 若应用与Keycloak跨域，需确保跨域Cookie权限配置正确，避免认证状态无法持久化。

5. 禁用登录iframe检查（可选） #

部分环境下，Keycloak的登录iframe检查会导致循环，可尝试在init配置中添加checkLoginIframe: false：

keycloakInstance.init({
  onLoad: 'login-required',
  checkLoginIframe: false
})

内容的提问来源于stack exchange，提问作者Aspiring Dev 23000