Alauda Build of Keycloak
  • 简体中文

    • 从 Red Hat Single Sign-On 迁移到 Keycloak

    本指南介绍如何将运行在 OpenShift 上的 Red Hat Single Sign-On (RH-SSO) 7.x 的身份数据迁移到运行在 Kubernetes 上的 Alauda Build of Keycloak。

    目录

    概述迁移流程前提条件第 1 步：从 RH-SSO 导出数据第 2 步：复制导出文件第 3 步：导入数据到 Keycloak第 4 步：验证迁移注意事项参考文档

    概述

    Red Hat Single Sign-On (RH-SSO) 7.x 是 Red Hat 基于 Keycloak Community Edition 开发的商业发行版。两者在核心数据模型和存储结构上完全兼容。

    本次迁移采用官方推荐的导出/导入机制，能够完整迁移以下数据：

    • Realm 配置
    • 用户（包括凭证和状态）
    • Realm 角色和客户端角色
    • 客户端及其权限映射
    • 复合角色和内置管理权限

    迁移流程

    RH-SSO (OpenShift)
   ↓ 导出为 JSON 文件
本地机器
   ↓ 复制迁移文件
Keycloak (Kubernetes)
   ↓ 导入 JSON 文件
迁移完成

    前提条件

    • 具有通过 oc rsh 访问 OpenShift 上 RH-SSO Pod 的权限。
    • 运行中的 Kubernetes 上 Alauda Build of Keycloak 实例。
    • 对目标 Kubernetes 集群的 kubectl 访问权限。
    • 本地机器上有足够的磁盘空间存放导出的 JSON 文件。

    第 1 步：从 RH-SSO 导出数据

    服务影响

    导出命令会在偏移端口启动一个独立的辅助服务器进程。该操作不会中断正在运行的 RH-SSO 服务，但建议在低流量时段执行以降低风险。

    连接到 RH-SSO Pod 并运行导出命令：

    # 连接到 RH-SSO Pod
oc rsh <rh-sso-pod-name>

# 在 Pod 内运行导出命令
/opt/eap/bin/standalone.sh \
  -c standalone-openshift.xml \
  -Dkeycloak.migration.action=export \
  -Dkeycloak.migration.provider=singleFile \
  -Dkeycloak.migration.file=/tmp/sso-export.json \
  -Dkeycloak.migration.usersExportStrategy=REALM_FILE \
  -Djboss.socket.binding.port-offset=502

    等待导出完成。进程会打印日志输出后退出。导出文件保存在 Pod 内的 /tmp/sso-export.json。

    第 2 步：复制导出文件

    将导出文件从 RH-SSO Pod 复制到本地机器，再复制到 Keycloak Pod：

    # 从 RH-SSO Pod (OpenShift) 复制到本地机器
oc cp <rh-sso-pod-name>:/tmp/sso-export.json /tmp/sso-export.json

# 从本地机器复制到 Keycloak Pod (Kubernetes)
kubectl cp /tmp/sso-export.json \
  <namespace>/<keycloak-pod-name>:/tmp/sso-export.json

    第 3 步：导入数据到 Keycloak

    连接到 Keycloak Pod 并运行导入命令：

    # 连接到 Keycloak Pod
kubectl exec -it <keycloak-pod-name> -n <namespace> -- /bin/bash

# 在 Pod 内运行导入命令
/opt/keycloak/bin/kc.sh import \
  --file /tmp/sso-export.json \
  --override true
    覆盖模式

    --override true 参数会替换目标 Keycloak 实例中同名的任何现有 Realm。如果希望在存在冲突 Realm 时导入失败以保留当前数据，请移除此参数。

    第 4 步：验证迁移

    导入完成后，验证所有数据是否正确迁移：

    1. 登录 Keycloak 管理控制台。
    2. 确认导入的 Realm 出现在 Realm 下拉列表中。
    3. 验证每个导入的 Realm 中：

      • 用户数量与源 RH-SSO 一致

      • 客户端配置完整

      • 角色分配正确

      • 复合角色和权限映射保持不变

        # 查看导入的 Realm
kubectl exec -it <keycloak-pod-name> -n <namespace> -- \
  /opt/keycloak/bin/kc.sh show-config

    注意事项

    • 导入成功指示：执行导入命令后，日志会打印 Realm '<realm-name>' imported 以确认导入成功。最后出现的 ERROR: Address already in use 是导入过程中的端口冲突，不影响数据导入结果。
    • 凭证兼容性：RH-SSO 7.x 与 Keycloak 26.x 使用兼容的凭证存储格式。用户密码会被迁移且导入后仍然有效。
    • 客户端密钥：客户端密钥包含在导出文件中，导入后请确认其是否被保留。
    • 覆盖模式：--override true 参数会替换同名 Realm。若希望在存在冲突 Realm 时导入失败，请移除此参数。

    参考文档