Realm Setup & Configuration

A realm is a tenant’s isolated identity space — its own users, clients, roles, identity providers, keys, and login flows. This chapter covers how to set one up and configure it.

Pick an isolation tier

See Architecture for the full model. In short:

Tier	Choose when
Organizations (shared realm)	Many small B2B customers, highest density, lightest isolation
Realm-per-tenant (pooled)	The default — strong isolation with own keys/users/flows
Dedicated silo (own KC + DB)	Enterprise / regulated / “give me my own instance”

The placement engine assigns the tier from your plan; you can request a dedicated silo or region pinning for residency.

Identity providers (SSO)

Keycloak brokers external IdPs and federates directories:

OIDC / SAML

Google, Microsoft Entra ID, Okta, Ping, or any standard OIDC/SAML provider as a login option.

Social login

Google/GitHub/etc. — and a lever to remove password hashing cost.

LDAP / AD federation

Federate an existing directory as a user source.

Authentication & MFA

• MFA: TOTP/OTP, WebAuthn/passkeys, and step-up authentication for sensitive actions.
• Brute-force protection: login-failure lockouts (counters live in Infinispan).
• Custom flows: conditional and scripted authenticators via the Authenticator SPI.
• See Advanced Security for adaptive auth and anomaly detection.

Custom domains

Put the realm on the customer’s own domain and keep issuer continuity:

1. Customer sets CNAME auth.customer.com → our edge.
2. We map the host → tenant → cell and set the realm’s frontendUrl.
3. TLS via ACM + SNI (DNS-validated). Tokens advertise the customer domain as issuer.

See Migration for the full mechanism.

AI-config console

Configure realms in plain English instead of clicking through the admin console:

How it works

The AI-config service translates a request like “turn on Google SSO and require MFA for admins” into Admin REST API calls, shows a dry-run diff of exactly what will change, and applies it only on your confirmation. It’s an accelerator over the standard API — every change is a normal, auditable Admin API operation.

Hardened defaults

New realms ship with sensible, secure defaults: strong password/OTP policy, brute-force protection on, short-lived access tokens with refresh, PKCE required for public clients, and audit event logging enabled (Analytics). You can tune any of it per realm.