2025-04-12

Keycloak-connect与Keycloak-js区别详解

Keycloak-connect 和 Keycloak-js 是 Keycloak 的两个客户端适配器，用于不同环境下的身份验证和授权集成。以下是它们的核心区别：

1. 运行环境

Keycloak-connect
用于 Node.js 服务器端（如 Express、Koa 等框架）。作为中间件，保护后端 API 或服务端渲染应用。
Keycloak-js
用于 浏览器客户端（如 React、Vue、Angular 等前端应用）。处理前端身份验证流程，直接与 Keycloak 服务器交互。

2. 核心功能

Keycloak-connect
- 验证请求中的访问令牌（Access Token）或会话 Cookie。
- 提供 Express 中间件，自动拦截未认证请求。
- 支持服务端的 OAuth2 授权码流程（Authorization Code Flow）。
- 管理服务器端会话，与 Keycloak 服务器通信校验令牌有效性。
Keycloak-js
- 处理用户登录、注销、令牌获取和刷新。
- 支持浏览器端的 OpenID Connect 流程（如隐式流程或带 PKCE 的授权码流程）。
- 自动将令牌存储在浏览器（如 localStorage 或 sessionStorage）。
- 支持静默刷新过期令牌，无需用户交互。

3. 集成场景

Keycloak-connect 的典型用例

const express = require('express');
const Keycloak = require('keycloak-connect');

const app = express();
const keycloak = new Keycloak({}, keycloakConfig);

// 保护路由
app.get('/api/protected', keycloak.protect(), (req, res) => {
  res.json({ data: '敏感数据' });
});

Keycloak-js 的典型用例

import Keycloak from 'keycloak-js';

const keycloak = Keycloak(keycloakConfig);

keycloak.init({ onLoad: 'login-required' }).then((authenticated) => {
  if (authenticated) {
    // 用户已登录，获取访问令牌
    const token = keycloak.token;
    // 调用受保护的 API
    fetch('/api/protected', {
      headers: { Authorization: `Bearer ${token}` }
    });
  }
});

4. 协议流程支持

Keycloak-connect
主要使用 OAuth2 授权码流程（适合服务端安全存储客户端密钥）。
Keycloak-js
支持 隐式流程（Implicit Flow） 或 带 PKCE 的授权码流程（Authorization Code Flow with PKCE）（适合公共客户端，防止令牌拦截）。

5. 安全角色

Keycloak-connect
- 确保后端 API 仅允许合法请求访问。
- 验证令牌签名、有效期及用户权限（如角色校验）。
Keycloak-js
- 管理用户登录状态，避免前端敏感信息泄露。
- 通过重定向或弹出窗口实现认证，不处理令牌签名验证（依赖后端验证）。

6. 依赖与存储

Keycloak-connect
- 依赖服务端会话存储（如 Redis 或内存存储）。
- 需要安全存储客户端凭证（如 Client Secret）。
Keycloak-js
- 依赖浏览器存储机制（localStorage/sessionStorage）。
- 无客户端密钥（作为公共客户端运行）。

总结对比表

特性	Keycloak-connect	Keycloak-js
环境	Node.js 服务端	浏览器客户端
主要职责	API 保护、令牌验证	用户登录、令牌管理
典型流程	授权码流程	隐式流程/PKCE 授权码流程
存储	服务端会话	浏览器存储
安全校验	验证令牌签名、过期时间	依赖后端校验令牌
适用场景	保护后端路由、微服务	单页应用（SPA）身份验证

常见误区

错误使用场景
- 在前端项目中使用 keycloak-connect：无法运行，依赖 Node.js 模块。
- 在服务端用 keycloak-js 验证令牌：不安全，需后端验证签名和有效性。
协作关系
二者常结合使用：前端通过 keycloak-js 获取令牌，后端通过 keycloak-connect 验证令牌，共同实现完整的身份认证体系。

正确区分二者可确保在全栈应用中实现安全、高效的身份管理。