Keycloak SSO Guide: OpenID Connect, SAML, and Identity Management

TL;DR — Quick Summary

Complete Keycloak guide: install with Docker or Kubernetes, configure realms, OpenID Connect and SAML clients, LDAP federation, RBAC, and high availability.

Keycloak is the leading open-source Identity and Access Management (IAM) solution — it delivers Single Sign-On (SSO), MFA, social login, LDAP/Active Directory federation, and fine-grained authorization using OpenID Connect, OAuth 2.0, and SAML 2.0. This guide covers everything from a production Docker Compose setup to realm configuration, RBAC, identity federation, and high availability clustering.

Prerequisites

• Docker 25+ and Docker Compose v2 (or a Kubernetes cluster for operator installs).
• PostgreSQL 15+ for production (embedded H2 is development-only).
• A reverse proxy (Nginx or Traefik) for TLS termination in production.
• Basic familiarity with OAuth 2.0 concepts (client, authorization code flow, tokens).

---

Keycloak Architecture

Keycloak organizes everything into realms — isolated security domains. Each realm contains:

Concept	Description
Realm	Isolated tenant. Owns users, clients, roles, groups, IdPs
Client	Application registered to use Keycloak for auth
User	Identity within the realm (local or federated)
Role	Permission label. Realm roles span all clients; client roles are scoped
Group	Collection of users with inherited role assignments
Identity Provider	External IdP (Google, GitHub, SAML, LDAP)
Authentication Flow	Configurable pipeline: browser login, OTP, WebAuthn

The master realm is the super-admin realm — use it only for managing other realms, never for application users.

---

Step 1: Install Keycloak with Docker Compose

This is the recommended production-ready starting point. Save as docker-compose.yml:

version: "3.9"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: changeme
      KC_HOSTNAME: auth.example.com
      KC_PROXY: edge          # TLS terminated at reverse proxy
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: adminpass
    ports:
      - "8080:8080"
    depends_on:
      - postgres

volumes:
  postgres_data:

docker compose up -d
# Access Admin Console at http://localhost:8080

For Kubernetes, use the official Keycloak Operator:

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/24.0.0/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/24.0.0/kubernetes/keycloak-operator.yml

---

Step 2: Realm Configuration

After logging in to the Admin Console:

1. Click the realm dropdown (top-left) → Create Realm.
2. Set a name (e.g., myapp), enable it, click Create.

Key realm settings to configure:

Setting	Recommended value
Display name	Your brand name
Login theme	keycloak (or custom)
Require SSL	external requests (production)
SSO Session Idle	30 minutes
Access Token Lifespan	5 minutes
Refresh Token Lifespan	30 minutes

Configure SMTP under Realm Settings → Email for password reset and verification emails.

---

Step 3: OpenID Connect Client Configuration

Go to Clients → Create client:

• Client type: OpenID Connect
• Client ID: myapp-client
• Client authentication: ON (confidential) for server-side apps; OFF (public) for SPAs/mobile
• Valid redirect URIs: https://myapp.example.com/callback
• Web origins: https://myapp.example.com (enables CORS)

Confidential vs Public Clients

Feature	Confidential	Public
Has client secret	Yes	No
Use case	Server-side (Node, .NET, Python)	SPA, mobile app
Auth code flow	With client secret	With PKCE
Risk if compromised	High — rotate secret	Low — secret-less

Protocol Mappers

Add mappers to include custom claims in tokens: Clients → your client → Client Scopes → Add mapper. Common mappers: User Attribute, Role, Group Membership, Audience.

---

Step 4: Role-Based Access Control (RBAC)

Realm Roles vs Client Roles

Realm roles apply across all clients in the realm. Client roles are scoped to a specific client:

# Create a realm role via kcadm.sh
kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password adminpass

kcadm.sh create roles -r myapp -s name=app-admin
kcadm.sh create roles -r myapp -s name=app-user

Groups and Role Mappings

1. Realm → Groups → Create group → name it Administrators.
2. Open the group → Role Mapping → Assign role → select app-admin.
3. Add users to the group — they inherit the role automatically.

Composite Roles

A composite role bundles other roles. Create a superuser realm role, then add app-admin and app-user as composites — any user with superuser gets both.

---

Step 5: Identity Federation

Social Login (Google, GitHub, Microsoft)

Identity Providers → Add provider → select Google:

1. Create an OAuth 2.0 app in Google Cloud Console.
2. Set Client ID and Client Secret from Google.
3. Set Redirect URI back to Keycloak: https://auth.example.com/realms/myapp/broker/google/endpoint.
4. Enable Trust Email if Google-verified emails should be auto-trusted.

LDAP / Active Directory Federation

User Federation → Add provider → LDAP:

Setting	Value
Vendor	Active Directory
Connection URL	ldap://ad.corp.example.com
Bind DN	CN=svc-keycloak,OU=ServiceAccounts,DC=corp,DC=example,DC=com
Users DN	OU=Users,DC=corp,DC=example,DC=com
Sync Mode	FORCE (attributes always overwritten from LDAP)

Run Synchronize all users to import AD users into Keycloak. LDAP group mapper syncs AD groups to Keycloak groups automatically.

---

Step 6: Authentication Flows and MFA

Browser Flow Customization

Authentication → Flows → browser → Duplicate to create a custom flow. Add OTP Form as REQUIRED after username/password to enforce TOTP for all users.

WebAuthn / Passkeys

Keycloak 22+ supports WebAuthn out of the box:

1. Authentication → Policies → WebAuthn Policy — set Relying Party ID to your domain.
2. Add WebAuthn Authenticator to your browser flow.
3. Users register their passkey on first login — no TOTP app needed.

Required Actions

Under Users → select user → Required User Actions, you can force:

• CONFIGURE_TOTP — forces OTP setup on next login.
• UPDATE_PASSWORD — forces password reset.
• VERIFY_EMAIL — sends verification email.

---

Fine-Grained Authorization (UMA 2.0)

For resource-level permissions, enable Authorization on a confidential client:

• Resources — define protected resources (e.g., /api/reports).
• Scopes — define actions (read, write, delete).
• Policies — rules based on roles, groups, JS scripts, or time.
• Permissions — bind resources+scopes to policies.

Clients query the Token Endpoint with grant_type=urn:ietf:params:oauth:grant-type:uma-ticket to get a Requesting Party Token (RPT) with permission claims.

---

High Availability Setup

For production clusters, run 2+ Keycloak nodes sharing PostgreSQL and an Infinispan distributed cache:

environment:
  KC_CACHE: ispn
  KC_CACHE_STACK: jdbc-ping   # auto-discovery via DB
  KC_DB: postgres
  KC_DB_URL: jdbc:postgresql://pgpool/keycloak  # pgBouncer/pgPool

Load balancer requirements:

• Enable sticky sessions (route by session cookie AUTH_SESSION_ID).
• Health check endpoint: GET /health/ready (returns 200 when node is ready).
• Drain connections gracefully — Keycloak replicates sessions across nodes.

---

Gotchas and Edge Cases

Issue	Cause	Fix
Tokens too large	Too many roles/groups in token	Use roles claim selectively; filter with mappers
CORS errors	Web origins not set	Add exact origin in client Web Origins field
LDAP sync fails	Bind DN lacks read permissions	Grant Read Members of a Group in AD
Redirect URI mismatch	Trailing slash or query string	Keycloak does exact match — add all URI variants
Clock skew errors	Server time drift	Sync NTP on all Keycloak and app nodes
Admin console 403	Wrong realm	Ensure you’re logged into master realm for realm management

---

Keycloak vs Alternatives

Feature	Keycloak	Authentik	Authelia	Auth0	Okta	FusionAuth
Open-source	Yes	Yes	Yes	No	No	Partial
Self-hosted	Yes	Yes	Yes	No	No	Yes
SAML 2.0	Yes	Yes	No	Yes	Yes	Yes
LDAP federation	Yes	Yes	No	Yes	Yes	Yes
Fine-grained authz	Yes (UMA)	No	No	Yes (paid)	Yes (paid)	Partial
Complexity	High	Medium	Low	Low	Low	Medium
Best for	Enterprise SSO	Modern web apps	Reverse proxy MFA	SaaS/startup	Enterprise	Mid-market

---

Troubleshooting

Problem	Solution
”Invalid redirect_uri”	Check client’s Valid Redirect URIs — must be exact match including trailing slash
”Client secret not valid”	Regenerate secret in Clients → Credentials → Regenerate
Login loop	Check that KC_HOSTNAME matches the actual URL; proxy header misconfiguration
Email not sending	Verify SMTP config in Realm Settings → Email → Test Connection
Users not synced from LDAP	Check bind credentials; run Synchronize Changed Users from User Federation

Summary

• Realms isolate tenants; always use a dedicated realm for applications.
• Confidential clients use client secrets; public clients use PKCE.
• Groups with role mappings scale RBAC — avoid assigning roles directly to users.
• LDAP sync with FORCE mode keeps AD attributes authoritative.
• For HA, use KC_CACHE=ispn with jdbc-ping — no ZooKeeper or Kubernetes required.
• Automate everything via kcadm.sh or the Admin REST API for GitOps workflows.

Related Articles

• Nginx Reverse Proxy with SSL
• Docker Compose Production Setup
• Traefik Reverse Proxy with Keycloak
• OpenLDAP Setup on Linux
• HashiCorp Vault Secrets Management