Keycloak realms aren’t just isolated namespaces; they’re actually fully independent authentication and authorization servers, each with its own users, roles, clients, and identity providers.
Let’s see this in action. Imagine we have a Keycloak instance running on keycloak.example.com. We can create two distinct realms: my-app-realm for our internal applications and partner-portal for our external partners.
# Example of creating a realm via Keycloak Admin CLI
/opt/keycloak/bin/kcadm.sh create realms -s realm=my-app-realm -s enabled=true
/opt/keycloak/bin/kcadm.sh create realms -s realm=partner-portal -s enabled=true
Now, within my-app-realm, we can define users like alice and bob and clients such as internal-dashboard and api-gateway. These users and clients are only visible and manageable within my-app-realm. They don’t appear in partner-portal at all.
Similarly, partner-portal could have its own users, say vendor-x and vendor-y, and clients like partner-api and partner-login. These are completely separate. If alice from my-app-realm tries to log in to partner-portal, Keycloak won’t recognize her credentials because she doesn’t exist in that realm.
This separation is crucial for security and manageability. It allows you to:
- Isolate Environments: Prevent authentication configurations, users, or client secrets from one application or user group from impacting another. This is vital for multi-tenancy or separating different business units.
- Customize Policies: Apply different password policies, multi-factor authentication (MFA) requirements, or session timeouts to different groups of users or applications. For instance, your
partner-portalmight require MFA for all users, whilemy-app-realmmight only enforce it for administrative roles. - Manage Identity Providers Independently: Each realm can be configured with its own set of identity providers (e.g., Google, Azure AD, SAML providers).
my-app-realmmight use your corporate Azure AD, whilepartner-portalmight allow partners to log in using their own corporate SAML solutions.
The core of realm configuration lies in its settings. You access these through the Keycloak Admin Console (e.g., http://keycloak.example.com/admin/) by selecting the desired realm. Key settings include:
- General: Basic realm name, enabled status, and display name.
- Login: Policies for password requirements (length, complexity, expiration), brute-force detection, and registration settings.
- Email: Configuration for sending emails for password resets, account verification, etc. This requires SMTP server details.
- Tokens: Settings for access token, refresh token, and ID token lifetimes, as well as refresh token revocation policies. For example, you might set the "Access Token Lifespan" to
300seconds (5 minutes) for a highly secure internal realm, but3600seconds (1 hour) for a partner portal. - Identity Providers: Adding and configuring external IdPs for federated login.
- User Federation: Connecting to external user directories like LDAP or Active Directory.
- Client Scopes: Defining default scopes for clients, controlling what information (e.g., user roles, email) is included in tokens.
Consider the "Security Defenses" tab within a realm’s settings. Here, you can fine-tune "Brute Force Detection" with settings like "Max failed logins" (e.g., 5) before an account is temporarily locked, and "Wait time" (e.g., 600 seconds) before the user can try again. You can also enable "Account Lockout" and set its "Account Lockout duration" (e.g., 1440 minutes or 1 day). These granular controls are applied per realm.
A common pitfall is assuming that configuring a client in one realm makes it available or known in another. Clients are strictly bound to their realm. If internal-dashboard is configured in my-app-realm, it cannot be used to authenticate users against partner-portal. You would need to create a new client definition within partner-portal for any application intended to use that realm’s authentication.
When you configure a client within a realm, you’ll set its "Client Protocol" (e.g., openid-connect) and "Access Type" (e.g., confidential for server-side apps, public for SPAs, or bearer-only for APIs that only validate tokens). For a confidential client, you’ll generate a "Client Secret," which is effectively a password for that client application to authenticate itself to Keycloak. This secret is again, realm-specific.
The most counterintuitive aspect of Keycloak realms is that they are not just organizational containers but fully fledged, independently operating authentication and authorization microservices running within a single Keycloak instance. Each realm has its own database schema (or distinct tables within a shared schema, depending on configuration), its own session management, its own token signing keys (unless explicitly configured to share), and its own set of configured authentication flows. This means that even if two realms share the same Keycloak server and the same underlying database, they are logically and functionally distinct, preventing any cross-realm leakage of sensitive information or authentication state.
Once you’ve mastered realm configuration, the next logical step is to explore the intricacies of custom authentication flows and SPIs (Service Provider Interfaces) within a specific realm to tailor authentication behavior even further.