Keycloak’s "separate realms per customer" approach to multi-tenancy is fundamentally a massive, deliberate duplication of configuration, and it’s brilliant.
Let’s watch Keycloak in action with a real-world scenario. Imagine you’re building a SaaS product where each customer gets their own isolated user management.
# Start a Keycloak instance (example using Docker)
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.1 start-dev
# Access the admin console at http://localhost:8080
# Create the first customer realm
# Navigate to "Master" realm -> "Add realm"
# Realm name: "customer-a"
# Enable "Enabled"
# Create the second customer realm
# Navigate to "Master" realm -> "Add realm"
# Realm name: "customer-b"
# Enable "Enabled"
# Inside "customer-a" realm:
# Create a client for your application
# Navigate to "Clients" -> "Create client"
# Client ID: "my-saas-app"
# Client Protocol: "openid-connect"
# Root URL: http://localhost:3000 (your app's URL)
# Valid Redirect URIs: http://localhost:3000/callback
# Inside "customer-b" realm:
# Create the same client
# Navigate to "Clients" -> "Create client"
# Client ID: "my-saas-app"
# Client Protocol: "openid-connect"
# Root URL: http://localhost:3000
# Valid Redirect URIs: http://localhost:3000/callback
# Create users within each realm
# Inside "customer-a" realm:
# Navigate to "Users" -> "Create user"
# Username: "alice@customer-a.com"
# Set password for Alice
# Inside "customer-b" realm:
# Navigate to "Users" -> "Create user"
# Username: "bob@customer-b.com"
# Set password for Bob
Now, when Alice from customer-a logs into http://localhost:3000, your application will direct her to Keycloak’s login endpoint for the customer-a realm. The same applies to Bob from customer-b, who will be directed to the customer-b realm.
The fundamental problem this solves is isolation. In a multi-tenant system, a breach or misconfiguration in one tenant’s environment should never impact another. With separate realms, you achieve strong tenant isolation at the identity layer. Each realm is a completely independent security domain. This means:
- User Separation: Alice from customer-a has no visibility into Bob from customer-b’s account, even if they share the same username format. Their user objects exist in distinct, non-overlapping namespaces.
- Configuration Independence: Each customer can have their own identity providers (SAML, OIDC), password policies, multi-factor authentication (MFA) requirements, token lifecycles, and custom attribute schemas. Customer-a might use Google as an IdP, while customer-b uses Okta, and neither needs to know about the other’s setup.
- Auditing and Compliance: Logs and audit trails are scoped to the realm, making it easier to demonstrate compliance for specific customers and to investigate incidents without affecting other tenants.
- Simplified Application Logic: Your application doesn’t need to manage tenant context for authentication and authorization. It simply directs users to the appropriate Keycloak realm based on the tenant they belong to. The Keycloak client configuration (
client_id) can even be realm-specific, further reinforcing this separation.
The "duplication" comes in because you’re creating identical client configurations, user federation providers, and potentially custom authenticators for each customer. This might seem inefficient at first glance, but it’s the price of true isolation. Imagine trying to achieve this with a single realm and a "tenant ID" attribute on every user and token – the complexity of authorization rules and the risk of data leakage would be immense.
The most surprising thing about this approach is how it fundamentally shifts the burden of tenant isolation from your application code to your identity provider infrastructure. You are essentially outsourcing the complex, security-critical task of keeping tenants apart to Keycloak, allowing your application to focus on its core business logic. This is a powerful pattern for achieving robust multi-tenancy without bogging down your application with cross-tenant access control logic.
You’ll next want to explore how to automate realm creation and management as your customer base grows.