【架构与设计】基于Keycloak的用户中心管理系统设计

用户中心 - 技术方案设计

1. 设计摘要

用户中心是以开源的身份和访问管理（IAM）解决方案 Keycloak 为底层框架 。提供统一的身份认证、授权、用户管理、单点登录（SSO）和多因素认证（MFA）能力，支持 OpenID Connect、OAuth 2.0、SAML 2.0 等标准协议，适用于现代化应用架构（如微服务、SPA、移动端）及传统企业系统集成。

核心价值

• 统一身份管理： 集中化用户、角色、权限管理。
• 标准化协议支持： 无缝集成异构系统。
• 开箱即用安全： 内置 MFA、密码策略、审计日志。
• 开发效率提升： 将身份逻辑从业务代码中解耦。

设计原则

Keycloak组件独享数据库，其他服务不允许对Keycloak数据进行访问，统一通过API进行访问

2. 核心功能

2.1 身份认证与单点登录（SSO）

• 协议支持：
  • OpenID Connect（OIDC）
  • OAuth 2.0
  • SAML 2.0
  • LDAP（用户联邦）
• SSO 实现： 用户登录一次后，可访问所有信任应用（Web/移动/API）。

2.2 用户与权限管理

• 用户存储：
  • 外部数据库（PostgreSQL/MySQL 等）
  • 社交登录（Google、GitHub、微信、钉钉等）
• 精细化授权：
  • 基于角色的访问控制（RBAC）
  • 基于属性的访问控制（ABAC）
  • 时间锁
  • 位置锁
• 用户、组织、角色属性动态配置： 可自定义界面展示属性

2.3 安全增强

• 多因子认证（MFA）： 支持 TOTP、邮件/短信验证码、WebAuthn（FIDO2）。
• 自适应风险策略： 根据 IP、地理位置、设备信息动态触发 MFA。
• 安全事件审计： 记录所有登录、权限变更、管理员操作日志。
• 无密码登录： 魔法链接（Magic Link）或生物识别替代传统密码

2.4 面向现代架构的支持

• 微服务/API 保护： 通过 OAuth 2.0 颁发 JWT 令牌，网关或服务直接验证令牌。
• SPA/移动端适配： 支持 PKCE 流程、Refresh Token 轮换。
• 服务间通信： Client Credentials 模式保护机器间调用。

3. 架构边界

3.1 包含功能

• 身份认证与单点登录（SSO）
• 用户存储（PostgreSQL/MySQL 等）
• 社交登录（钉钉）
• 用户、组织、角色、资源管理
• 用户、组织、角色属性动态配置
• 基于角色的访问控制（RBAC）
• 微服务/API 保护
• 安全事件审计
• 日志可观测性
• LDAP同步现有企业用户体系
• 备份还原
• 基础配置（Token有效期、客户端登陆超时等）

3.2 不包含功能

• 基于属性的访问控制（ABAC）
• 多因子认证（MFA）
• 自适应风险策略
• SPA/移动端适配
• 无密码登录（如：人脸识别）
• 时间锁
• 位置锁
• 配置身份联邦对接AWS、Azure等云平台
• 数据权限

4. 关键用例图

核心用例说明

• 用户登录
  • 参与者： 用户、网关、用户中心、Keycloak
  • 流程： 用户访问应用 → 令牌（Token）过期 → 重定向到系统登录页 → 输入凭据 → 网关 → 用户中心 → Keycloak验证身份 → 颁发令牌（Token）。
• 单点登录访问应用
  • 参与者： 用户、网关、用户中心、Keycloak、业务应用
  • 流程： 用户登录后访问其他关联应用 → 网关将请求转发到用户中心 → 用户中心向Keycloak验证令牌有效性 → 自动授权访问（无需重复登录）。
• 注销
  • 参与者： 用户、网关、用户中心、Keycloak、所有业务应用
  • 流程： 用户触发登出 → 网关将请求转发到用户中心 → 用户中心向Keycloak发起销毁会话请求 → Keycloak销毁会话 → 通知所有关联应用执行本地登出 → 清理用户状态。
• 令牌验证
  • 参与者： 网关、用户中心、Keycloak
  • 流程： 网关收到用户请求 → 向用户中心发送令牌验证请求 → 用户中心请求Keycloak验证 → Keycloak返回有效性及用户信息。
• 用户体系同步
  • 参与者： 系统管理人员、 网关、用户中心、Keycloak
  • 流程： 系统管理人员导入LDAP协议的用户数据 → 网关将请求转发到用户中心 → 用户中心处理导入请求 → 用户中心调用Keycloak接口将用户信息落库。
• 初始化配置导入
  • 参与者： Keycloak
  • 流程： 系统运维人员将初始化好的权限信息导入初装环境 → Keycloak处理导入请求并将配置信息落库。

5. 概念模型图

6. 组件图

7. 单点登录时序图

8. 高可用设计

1. 无状态服务：
   • Keycloak 业务节点不存储会话数据，依赖数据库或外部缓存共享状态。
   • 用户会话（Sessions）、令牌（Tokens）存储于共享数据库或分布式缓存。
2. 共享数据库：
   • 所有节点连接同一数据库（如 PostgreSQL或 MySQL）。
   • 数据库保障高可用（主从切换、读写分离）最佳。
3. 分布式缓存：
   • 使用 Infinispan（默认嵌入式）或 外部 Redis 缓存：
     • 用户会话（sessions）
     • 重复登录限制（loginFailures）
     • 令牌撤销列表（actionTokens）
   • 缓存集群模式：跨节点同步数据，避免单点故障。
4. 负载均衡与健康检查：
   • 配置 HTTP 健康检查（/auth/realms/master）。
5. 灾难恢复：
   • 定期备份数据库（用户数据 + Realm 配置）。
   • 多可用区（AZ）部署节点与数据库。
6. 日志可观测性
   • 集成可观测平台SDK
7. 备份还原
   • 依赖系统整体备份还原方案，若系统没有整体备份还原方案，只需要备份还原Keycloak数据库，用户和权限数据不会太大，采用逻辑备份，转储SQL备份还原。

9. 部署建议

• 云原生部署：

  • Kubernetes：通过 StatefulSet 部署，使用外部数据库（PostgreSQL）。
  • Helm Chart：官方提供 keycloak/keycloak Helm Chart。

• 推荐最小配置：

  • CPU: 2 核
  • 内存: 2 GB - 4 GB
    • JVM 堆内存:
      • 在 2GB RAM 的机器上，设置 -Xms1g -Xmx2g 或 -Xms1g -Xmx3g。
      • 在 4GB RAM 上可设置 -Xms2g -Xmx3g。