Alauda Build of Keycloak
  • 简体中文

    • Realm 与多租户

    目录

    什么是 Realmmaster RealmRealm 隔离多租户模式每租户一个 Realm（推荐）共享 Realm + 组通过 KeycloakRealmImport 配置 Realm

    什么是 Realm

    Realm 是 Keycloak 中的基础隔离单元。每个 Realm 独立管理其自己的用户、凭据、角色、组、客户端和认证策略，彼此之间互不共享。Realm 不共享用户数据库或配置，是 Keycloak 实现多租户的主要机制。

    可以将 Realm 理解为一个专用的身份域——类似于多租户 SaaS 应用中的租户。

    master Realm

    每个 Keycloak 安装都包含一个内置的 Realm，称为 master。master Realm 是顶层的管理域，专门用于：

    • 管理其他 Realm（创建、配置和删除）
    • 管理 Keycloak 服务器级别的设置
    • 托管 Keycloak 管理控制台
    安全建议

    不要使用 master Realm 来管理应用用户或托管应用客户端。应为每个应用或租户创建专用的 Realm，以保持适当的隔离。

    Realm 隔离

    每个 Realm 在以下维度上提供完全隔离：

    维度范围
    用户用户账户、凭据和配置文件仅存在于其所属 Realm
    客户端注册在某个 Realm 的应用无法从其他 Realm 访问
    角色Realm 级别和客户端级别的角色均限定于其所属 Realm
    认证流程登录页面、多因素认证及其他流程均按 Realm 配置
    身份提供者外部身份提供者集成（LDAP、OIDC、SAML）是 Realm 特定的
    会话用户会话隔离；单点登录（SSO）仅在单个 Realm 内生效

    多租户模式

    Keycloak 支持两种常见的多租户模式：

    每租户一个 Realm（推荐）

    每个租户拥有自己的专用 Realm。此方式提供最强的隔离，允许每个租户拥有完全独立的用户、角色、客户端和认证配置。

    • 优点：数据完全隔离，配置独立，无跨租户数据泄露风险。
    • 缺点：随着 Realm 数量增加，管理开销增大；每个租户需单独配置 Realm 级别设置。

    共享 Realm + 组

    多个租户共享一个 Realm，租户通过 Keycloak 组 或用户上的自定义属性进行区分。

    • 优点：运维开销较低，规模化管理更简单。
    • 缺点：隔离性较弱；需严格访问控制以防止跨租户数据访问。不适合严格合规场景。

    通过 KeycloakRealmImport 配置 Realm

    在 Alauda Build 版本的 Keycloak 中，可以使用 KeycloakRealmImport 自定义资源以声明式方式管理 Realm 配置，实现 GitOps 风格的 Realm 定义管理。

    apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-import
spec:
  keycloakCRName: example-kc
  realm:
    realm: my-tenant
    enabled: true
    displayName: "My Tenant Realm"

    完整 API 参考见 KeycloakRealmImport API。