Keycloak-js中的check-sso

Keycloak 中的 check-sso 类型是 前端应用初始化时的一种单点登录（SSO）检查模式，主要用于判断用户是否已通过其他系统登录并存在有效的 SSO 会话。它的核心目标是 在不强制用户重新登录的前提下，静默检查当前用户的认证状态，从而优化用户体验。

---

check-sso 的核心行为

当你在 keycloak-js 的初始化配置中设置 onLoad: 'check-sso' 时，会发生以下动作：

1. 静默检查 SSO 会话
   Keycloak 会向 Keycloak 服务器发送一个隐藏的 iframe 请求，检查当前浏览器是否存在有效的 SSO 会话（例如用户已通过同一域下的其他应用登录）。

2. 自动获取令牌（若存在会话）

   • 如果存在有效会话，Keycloak 会自动获取访问令牌（Access Token）和刷新令牌（Refresh Token），并存储在浏览器中（如 localStorage）。
   • 如果不存在有效会话，不会重定向到登录页面，用户仍停留在当前页面。

3. 无用户感知
   整个过程在后台进行，用户不会看到登录页面的跳转或弹窗。

---

典型使用场景

check-sso 适用于以下场景：

• 非敏感页面初始化检查
  例如，应用首页希望展示部分公共内容，同时根据用户是否登录动态调整界面（如显示“登录”或“个人中心”按钮）。
• 避免不必要的登录跳转
  用户可能已通过其他关联应用登录，此时无需重复认证。
• 结合按需登录
  仅当用户尝试访问受保护资源时，才触发显式登录（如调用 keycloak.login()）。

---

代码示例

在 keycloak-js 中配置 check-sso：

import Keycloak from 'keycloak-js';

const keycloak = Keycloak({
  url: 'https://keycloak-server/auth',
  realm: 'my-realm',
  clientId: 'my-client'
});

keycloak.init({
  onLoad: 'check-sso',  // 启用 check-sso 模式
  silentCheckSsoRedirectUri: 'https://your-app/silent-check-sso.html' // 静默检查的 URI
}).then((authenticated) => {
  if (authenticated) {
    console.log('用户已登录，令牌：', keycloak.token);
  } else {
    console.log('用户未登录，但未强制跳转');
    // 可在此处展示部分内容，等待用户主动触发登录
  }
});

---

与其他模式的对比

初始化模式	check-sso	login-required	none
行为	静默检查 SSO 会话，不强制跳转登录页	如果未登录，直接重定向到 Keycloak 登录页	完全依赖手动触发登录
用户体验	无感知，适合非敏感入口	强制登录，适合受保护路由初始化	完全自定义流程
适用场景	首页、公共页面	受保护的后台或功能页面	需要精细控制登录的 SPA

---

关键注意事项

1. 静默检查的 URI（silentCheckSsoRedirectUri）
   Keycloak 通过隐藏的 iframe 执行 SSO 检查，需提供一个 HTML 文件（通常为空）作为回调地址。确保该 URI 在 Keycloak 客户端配置中允许。

2. 令牌有效期管理
   check-sso 不会自动刷新令牌。需通过 enableSilentCheck 配置静默刷新：

   keycloak.init({
     onLoad: 'check-sso',
     silentCheckSsoRedirectUri: '...',
     enableSilentCheck: true  // 开启静默令牌刷新
   });

3. 安全性权衡

   • 优点：减少用户频繁登录的干扰。
   • 风险：在公共设备上可能导致未主动注销的会话残留。建议结合短期令牌有效期和自动注销机制。

---

总结

check-sso 是 Keycloak 前端适配器中一种轻量级的认证状态检查模式，适合需要兼顾用户体验和安全性的场景。它通过静默检查 SSO 会话，避免不必要的登录跳转，同时为按需登录提供基础。实际使用时需结合业务需求配置静默刷新和安全策略。