本文介绍如何将 keycloak 集成从“强制登录”模式切换为“可选认证”模式，使 react 单页应用支持游客浏览，并仅在访问敏感路由或组件时按需触发登录，兼顾用户体验与安全性。
本文介绍如何将 keycloak 集成从“强制登录”模式切换为“可选认证”模式，使 react 单页应用支持游客浏览，并仅在访问敏感路由或组件时按需触发登录，兼顾用户体验与安全性。
在传统 Keycloak + React SPA 集成中，onLoad: “login-required” 会强制用户在应用启动时完成认证，否则直接跳转至 Keycloak 登录页——这适用于内部管理后台等强身份约束场景。但面向公众的网站（如企业官网、产品文档、营销页面）往往需要支持“先浏览、后登录”：用户可自由访问首页、介绍页等内容，仅在点击「控制台」「个人中心」「提交表单」等操作时才触发认证流程。
实现这一目标的核心在于解耦初始化认证与路由/业务逻辑。关键修改仅需两步：
✅ 第一步：调整 Keycloak 初始化配置
将 init() 的 onLoad 选项由 “login-required” 改为 “check-sso”：
// index.js 或应用入口文件 window.keycloak .init({ onLoad: "check-sso", // ← 关键变更：静默检查 SSO 状态，不强制跳转 checkLoginiframe: false, // 提升兼容性（尤其在 iframe 或跨域场景） promiseType: "native", // 使用原生 Promise（推荐） }) .then((authenticated) => { console.log("Keycloak initialized. Authenticated:", authenticated); ReactDOM.render(<App />, document.getElementById("root")); }) .catch((error) => { console.error("Keycloak initialization failed:", error); });“check-sso” 模式下，Keycloak 会尝试通过隐藏 iframe 或静默重定向验证用户是否已在 Keycloak 会话中登录。若已登录，则 authenticated 为 true，且 window.keycloak.Token 等凭据可用；若未登录，则 authenticated 为 false，但应用仍正常启动，用户可继续浏览。
✅ 第二步：按需触发登录（组件级保护）
不再依赖全局拦截，而是将认证逻辑下沉到具体需要保护的组件或路由中。推荐封装一个可复用的受保护组件：
// components/ProtectedRoute.tsx import React, { useEffect } from 'react'; interface ProtectedProps { children: React.ReactNode; } export const ProtectedRoute: React.FC<ProtectedProps> = ({ children }) => { useEffect(() => { const keycloak = window.keycloak; // 若未认证，主动跳转登录页 if (!keycloak?.authenticated) { keycloak?.login(); } }, []); // 初始渲染时可能尚未完成 auth 检查，可加 loading 状态或条件渲染 if (!window.keycloak?.authenticated) { return <div>Redirecting to login...</div>; } return <>{children}</>; };在路由中使用（以 React router v6 为例）：
// App.tsx import { Routes, Route } from 'react-router-dom'; import { ProtectedRoute } from './components/ProtectedRoute'; function App() { return ( <Routes> <Route path="/" element={<HomePage />} /> {/* 公开页面 */} <Route path="/docs" element={<DocsPage />} /> <Route path="/dashboard" element={ <ProtectedRoute> <DashboardPage /> </ProtectedRoute> } /> <Route path="/profile" element={ <ProtectedRoute> <ProfilePage /> </ProtectedRoute> } /> </Routes> ); }? 进阶提示：对于更精细的权限控制（如基于角色的路由），可在 ProtectedRoute 内增加 keycloak.hasRealmRole() 或 keycloak.hasResourceRole() 校验，并配合 keycloak.logout() 实现登出逻辑。
⚠️ 注意事项与最佳实践
- Token 刷新：check-sso 不自动刷新 token。建议在应用中集成定时刷新逻辑（如使用 keycloak.updateToken(30) 每 30 秒检查过期），或监听 onAuthRefreshSuccess 事件。
- SSO session 超时：若用户长时间无操作，Keycloak SSO Session 过期后 check-sso 将返回 false，此时再次调用 login() 会无缝跳转（无需重复输入凭证，只要浏览器 cookie 有效）。
- 服务端校验不可省略：前端保护仅为体验优化，所有敏感 API 必须在后端通过 Keycloak Adapter（如 spring Security Keycloak Adapter）进行 token 解析与鉴权，杜绝绕过风险。
- 避免全局 keycloak.login() 多次调用：可在调用前加锁（如 if (!keycloak.authenticated && !loginPending)），防止重复跳转。
通过以上改造，你的 React 应用即可优雅支持“可选认证”模式：既保留 Keycloak 的企业级安全能力，又提供类消费级产品的流畅访客体验。