Alauda Application Services Identity Management E1
  • 简体中文

    • 导入和导出

    Keycloak 支持导入和导出 Realm 配置，用于备份、迁移和环境复制。

    目录

    导出方法通过 Admin Console 导出（部分导出）通过 CLI 导出（完整导出）通过 REST API 导出导入方法通过 KeycloakRealmImport CRD 导入（推荐用于初始设置）通过 CLI 导入（启动时导入）通过 Admin Console 导入环境之间的迁移

    导出方法

    通过 Admin Console 导出（部分导出）

    1. 在 Admin Console 中选择目标 Realm。
    2. 转到 Realm Settings > Action 菜单（右上角）> Partial export。
    3. 选择要包含的内容：
      • Groups and related roles
      • Clients
      • Roles
    4. 点击 Export。
    5. 系统将下载一个 JSON 文件，其中包含所选 Realm 的配置。
    部分导出的限制

    部分导出不包含用户数据、机密或凭据。它仅导出结构配置（客户端、角色、组、身份验证流等）。

    通过 CLI 导出（完整导出）

    如需包含用户和凭据的完整导出，请使用 Keycloak CLI 导出命令。在 Kubernetes 环境中，可将其作为 Job 运行，或通过 exec 进入 Pod：

    # Exec into the Keycloak Pod
kubectl exec -it <keycloak-pod> -n <namespace> -- \
  /opt/keycloak/bin/kc.sh export \
    --dir /tmp/export \
    --realm <realm-name> \
    --users realm_file

    导出选项：

    选项描述
    --dir <path>导出文件的输出目录
    --file <path>输出到单个文件（--dir 的替代方式）
    --realm <name>导出特定 Realm（省略则导出所有 Realm）
    --users realm_file在 Realm 导出文件中包含用户
    --users same_file在同一文件中包含用户（用于单文件导出）
    --users skip从导出中排除用户
    --users different_files将用户导出到单独的文件（适用于大型用户集）
    需要重启服务器

    Keycloak CLI 导出命令要求服务器已停止，或在特殊导出模式下运行。在 Kubernetes 中，最佳做法是将其作为一次性 Job 运行，或缩减 deployment，运行导出后再将其扩容回原规模。或者，使用 Admin REST API 进行实时导出。

    通过 REST API 导出

    使用 Admin REST API 执行实时、无中断的部分导出：

    # Export a realm (does not include secrets or user credentials)
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>" | jq . > realm-export.json

# Export users
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users?max=1000" | jq . > users-export.json

# Export clients
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients" | jq . > clients-export.json

    导入方法

    通过 KeycloakRealmImport CRD 导入（推荐用于初始设置）

    KeycloakRealmImport CRD 是在 Kubernetes 部署中进行初始 Realm 配置的首选方法。有关详细信息，请参阅管理 Realm。

    apiVersion: k8s.keycloak.org/v2beta1
kind: KeycloakRealmImport
metadata:
  name: my-realm-import
spec:
  keycloakCRName: example-kc
  realm:
    # Full realm JSON embedded here
    KeycloakRealmImport 是一次性导入

    KeycloakRealmImport CRD 会在创建资源时执行一次性导入。它不是持续同步控制器——之后通过 Admin Console 或 REST API 进行的更改不会反映回 CR，更新 CR 也不会自动将更改重新应用到现有 Realm。

    具体而言：

    • 它会在导入时创建新的 Realm。如果已存在同名 Realm，导入不会覆盖或更新现有 Realm。
    • 它不会跟踪或协调持续变化的 Realm 状态。
    • 初始导入后修改 CR 不会自动触发重新导入。
    • 它不会删除 Realm 或 Realm 对象——这是一种仅用于创建的机制。
    • 不应将其作为完整的生命周期管理或 GitOps 同步机制。

    如需在初始导入后持续更改 Realm 配置，请使用 Admin Console 或 Admin REST API。

    通过 CLI 导入（启动时导入）

    将导出文件放置在目录中，并配置 Keycloak 在启动时执行导入：

    kubectl exec -it <keycloak-pod> -n <namespace> -- \
  /opt/keycloak/bin/kc.sh import \
    --dir /tmp/export \
    --override true
    选项描述
    --dir <path>包含要导入的导出文件的目录
    --file <path>从单个文件导入
    --override true如果 Realm 已存在，则覆盖现有 Realm 配置

    通过 Admin Console 导入

    1. 转到创建 Realm（左上角下拉菜单 > 创建 Realm）。
    2. 单击浏览并选择 Realm 导出 JSON 文件。
    3. 单击创建。

    此方法会根据 JSON 文件创建新的 Realm。它不会合并到现有 Realm 中。

    环境之间的迁移

    要将一个环境中的 Keycloak 配置复制到另一个环境：

    1. 从源环境导出 Realm（使用部分导出或 REST API）。
    2. 检查并清理导出内容：
      • 删除特定于环境的 URL 和主机名。
      • 删除或替换客户端密钥（对密钥使用 KeycloakRealmImport 占位符）。
      • 更新重定向 URI，使其与目标环境匹配。
    3. 使用 KeycloakRealmImport CRD 导入到目标环境。

    有关从 Red Hat Single Sign-On 迁移的信息，请参阅从 RH-SSO 迁移。