Alauda Build of Keycloak

Realm and Multi-Tenancy

TOC

What Is a RealmThe master RealmRealm IsolationMulti-Tenancy PatternsOne Realm per Tenant (Recommended)Shared Realm with GroupsRealm Configuration via KeycloakRealmImport

What Is a Realm

A Realm is the foundational isolation unit in Keycloak. Each Realm manages its own set of users, credentials, roles, groups, clients, and authentication policies independently from other Realms. Realms do not share user databases or configuration, making them the primary mechanism for multi-tenancy in Keycloak.

Think of a Realm as a dedicated identity domain — analogous to a tenant in a multi-tenant SaaS application.

The master Realm

Every Keycloak installation includes a built-in Realm called master. The master Realm is the top-level administrative domain and is used exclusively for:

  • Managing other Realms (creating, configuring, and deleting them)
  • Managing Keycloak server-level settings
  • Hosting the Keycloak Admin Console
Security Recommendation

Do not use the master Realm to manage application users or host application clients. Create dedicated Realms for each application or tenant to maintain proper isolation.

Realm Isolation

Each Realm provides full isolation across the following dimensions:

DimensionScope
UsersUser accounts, credentials, and profiles exist only within their Realm
ClientsApplications registered in a Realm cannot be accessed from another Realm
RolesRealm-level and client-level roles are scoped to their Realm
Authentication FlowsLogin pages, MFA, and other flows are configured per Realm
Identity ProvidersExternal IdP integrations (LDAP, OIDC, SAML) are Realm-specific
SessionsUser sessions are isolated; SSO applies within a single Realm only

Multi-Tenancy Patterns

Keycloak supports two common multi-tenancy patterns:

Each tenant gets its own dedicated Realm. This provides the strongest isolation, allowing each tenant to have completely independent users, roles, clients, and authentication configuration.

  • Pros: Full data isolation, independent configuration, no risk of cross-tenant data leakage.
  • Cons: Management overhead increases with the number of Realms; Realm-level settings must be configured separately for each tenant.

Shared Realm with Groups

Multiple tenants share a single Realm, and tenants are separated using Keycloak Groups or custom attributes on users.

  • Pros: Lower operational overhead, simpler to manage at scale.
  • Cons: Weaker isolation; requires careful access control to prevent cross-tenant data access. Not recommended for strict compliance scenarios.

Realm Configuration via KeycloakRealmImport

In Alauda Build of Keycloak, Realm configurations can be managed declaratively using the KeycloakRealmImport Custom Resource. This enables GitOps-style management of Realm definitions.

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"

For the full API reference, see KeycloakRealmImport API.