React + keycloak-js访问首页陷入#error=login_required重定向循环

在基础React应用中使用keycloak-js和@react-keycloak/web实现认证时，遇到异常重定向循环：访问http://localhost:3000/时，会反复跳转到redirectUri（http://localhost:3000/home），并附加#error=login_required&state=xxx参数。明明未设置onLoad为login-required，但问题依然存在。

移除keycloak.init()中的pkceMethod选项可临时解决，但业务必须使用PKCE认证，因此需要针对性方案。

相关代码 #

index.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ReactKeycloakProvider } from "@react-keycloak/web";
import App from './App';
import Keycloak from "keycloak-js";

import { Routes, Route, BrowserRouter } from 'react-router-dom';

let keycloak = new Keycloak({
    url: "http://localhost:8081/",
    realm: "realm",
    clientId: "realm-public",
    loadUserProfileAtStartup: false
});

keycloak.init({
    redirectUri: "http://localhost:3000/home",
    pkceMethod: "S256"
});

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
    <ReactKeycloakProvider authClient={keycloak}>
        <React.StrictMode>
            <BrowserRouter>
                <Routes>
                    <Route path="/" element={<App keycloak={keycloak}/>} />
                </Routes>
            </BrowserRouter>
       </React.StrictMode>
    </ReactKeycloakProvider>
);

App.js

function App({keycloak}) {
    return (
        <div>
            <p> 12345 </p>
            <button onClick={() => keycloak.login()}> Click me </button>
        </div>
    );
}

使用版本 #

• react: 18.2.0
• @react-keycloak/web: 3.4.0
• react-router-dom: 6.3.0
• keycloak-js: 19.0.1

解决方案 #

1. 修正Keycloak初始化逻辑，避免异步冲突 #

keycloak.init()是异步操作，手动调用后直接渲染ReactKeycloakProvider会导致Provider在初始化完成前触发无效校验，引发重定向。应将初始化配置交给ReactKeycloakProvider的initOptions属性处理，而非手动调用：

// ... 其他导入代码不变

let keycloak = new Keycloak({
    url: "http://localhost:8081/",
    realm: "realm",
    clientId: "realm-public",
    loadUserProfileAtStartup: false
});

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
    <ReactKeycloakProvider 
        authClient={keycloak}
        initOptions={{
            redirectUri: "http://localhost:3000/home",
            pkceMethod: "S256",
            onLoad: 'check-sso' // 显式设置为check-sso，避免默认行为触发强制登录
        }}
    >
        <React.StrictMode>
            <BrowserRouter>
                <Routes>
                    <Route path="/" element={<App />} />
                    <Route path="/home" element={<App />} /> {/* 新增home路由匹配redirectUri */}
                </Routes>
            </BrowserRouter>
       </React.StrictMode>
    </ReactKeycloakProvider>
);

2. 补全redirectUri对应的路由 #

原代码仅配置了/路由，重定向到/home后无匹配路由，会触发React Router fallback或Keycloak重新校验，进而引发循环。必须在路由表中添加/home路由。

3. 使用官方钩子获取Keycloak实例 #

避免手动传递keycloak实例，改用@react-keycloak/web提供的useKeycloak钩子，保证获取的是已初始化完成的实例：

import { useKeycloak } from '@react-keycloak/web';

function App() {
    const { keycloak } = useKeycloak();
    
    // 等待实例初始化完成再渲染交互元素
    if (!keycloak) {
        return <div>Loading...</div>;
    }

    return (
        <div>
            <p> 12345 </p>
            <button onClick={() => keycloak.login()}> Click me </button>
        </div>
    );
}

export default App;

4. 检查Keycloak客户端配置 #

• 确保后台客户端的Valid Redirect URIs包含http://localhost:3000/*或明确的http://localhost:3000/home
• 确认客户端Access Type设置为public（与代码中realm-public客户端匹配）
• 验证Keycloak客户端是否开启PKCE支持（Keycloak 19默认支持，可在客户端设置中确认）

内容的提问来源于stack exchange，提问作者Krusty the Clown