如何在React应用中使用Keycloak JavaScript适配器实现Authorization Code with PKCE流程？

一、Keycloak后台客户端配置 #

先在Keycloak管理控制台完成客户端基础配置：

• 将客户端**访问类型（Access Type）**设为public（公开客户端是启用PKCE的前提）
• 进入「高级设置」→「流程设置」，确认勾选「Authorization Code」授权类型，且「Proof Key for Code Exchange Code Challenge Method」选择S256（Keycloak对公开客户端默认强制启用PKCE，这里做二次确认）
• 配置「有效重定向URI」：本地开发填http://localhost:3000/*，生产环境替换为正式域名
• 配置「Web Origins」：填入前端应用域名（如http://localhost:3000），避免跨域问题

二、安装Keycloak JS适配器 #

用包管理器安装官方适配器：

npm install keycloak-js
# 或使用yarn
yarn add keycloak-js

三、初始化Keycloak实例 #

在项目中创建工具文件（如src/utils/keycloak.js），初始化并导出Keycloak实例：

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
  url: 'https://你的Keycloak服务器地址', // 示例：https://keycloak.example.com
  realm: '你的Realm名称', // 示例："my-app-realm"
  clientId: '你的公开客户端ID', // 示例："react-public-client"
  pkceMethod: 'S256' // 明确指定PKCE加密方法，确保走Authorization Code + PKCE流程
});

export default keycloak;

四、在应用入口集成认证逻辑 #

修改src/index.js，在应用渲染前完成Keycloak初始化，处理登录状态：

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import keycloak from './utils/keycloak';

// 初始化Keycloak
keycloak.init({
  onLoad: 'login-required', // 可选值：'login-required'强制登录；'check-sso'仅检查登录状态
  silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html` // 静默检查登录的回调页面
}).then(authenticated => {
  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(
    <React.StrictMode>
      <App keycloak={keycloak} isAuthenticated={authenticated} />
    </React.StrictMode>
  );
}).catch(err => {
  console.error('Keycloak初始化失败', err);
});

五、创建静默检查页面 #

在public目录下新建silent-check-sso.html，用于无感知验证登录状态，避免频繁跳转：

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

六、在组件中使用认证状态与API #

在业务组件（如App.js）中，可直接调用Keycloak实例获取用户信息、处理登出：

import React, { useEffect } from 'react';

function App({ keycloak, isAuthenticated }) {
  // 自动刷新令牌，避免过期
  useEffect(() => {
    const refreshInterval = setInterval(() => {
      keycloak.updateToken(70).then(refreshed => {
        if (refreshed) console.log('令牌已自动刷新');
      }).catch(() => {
        console.error('令牌刷新失败，将重新引导登录');
        keycloak.login();
      });
    }, 60000); // 每分钟检查一次令牌状态

    return () => clearInterval(refreshInterval);
  }, [keycloak]);

  if (!isAuthenticated) {
    return <div>正在验证身份...</div>;
  }

  return (
    <div className="app-container">
      <h1>欢迎回来，{keycloak.tokenParsed.preferred_username}！</h1>
      <button onClick={() => keycloak.logout({ redirectUri: window.location.origin })}>
        登出
      </button>
      <div>
        <h3>用户信息</h3>
        <p>邮箱: {keycloak.tokenParsed.email}</p>
        <p>角色: {keycloak.tokenParsed.realm_access.roles.join(', ')}</p>
      </div>
    </div>
  );
}

export default App;

关键注意事项 #

• 公开客户端禁止存储客户端密钥，PKCE流程正是为了弥补公开客户端的安全短板
• 生产环境必须使用HTTPS协议，防止令牌在传输过程中被窃取
• 有效重定向URI必须严格匹配前端回调地址，否则Keycloak会拒绝授权请求
• 若需自定义登录页面，可在Keycloak客户端设置中配置「登录主题」，或通过适配器参数自定义跳转逻辑

内容的提问来源于stack exchange，提问作者Junaid Khan Pathan