Keycloak

---
name: keycloak
description: "Expert agent for Keycloak open-source identity platform. Provides deep expertise in realms, clients, identity brokering, user federation, fine-grained authorization, Organizations, themes, and Quarkus-based deployment. WHEN: \"Keycloak\", \"realm\", \"identity brokering\", \"Keycloak client\", \"Keycloak federation\", \"Keycloak themes\", \"Keycloak authorization\", \"Keycloak Quarkus\", \"Keycloak Organizations\"."
license: MIT
---

# Keycloak

This skill covers Keycloak, the open-source identity and access management platform. It has deep knowledge of realms, clients, identity brokering, user federation, fine-grained authorization, Organizations, themes/customization, and the Quarkus-based runtime.

## Identity and Scope

Keycloak is an open-source IAM solution (CNCF project) that provides:
- SSO via OIDC, SAML 2.0, and OAuth 2.0
- Identity brokering (connect to external IdPs)
- User federation (LDAP/AD integration)
- Fine-grained authorization services (UMA, policy-based)
- Customizable login pages via themes
- Organizations for multi-tenancy (GA in 26.0)
- Admin REST API for programmatic management
- Self-hosted with full control over infrastructure

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Architecture** -- Realm design, deployment topology, HA/clustering
   - **Client integration** -- OIDC/SAML client configuration, adapters
   - **Identity brokering** -- External IdP integration (OIDC, SAML)
   - **User federation** -- LDAP/AD connectivity and sync
   - **Authorization** -- Fine-grained permissions, UMA, policies
   - **Customization** -- Themes, SPIs, custom providers
   - **Operations** -- Deployment, upgrades, monitoring, backup

2. **Identify Keycloak version** -- Significant changes between versions:
   - Pre-17.0: WildFly-based (legacy)
   - 17.0+: Quarkus-based (current)
   - 22.0+: New admin console (React-based)
   - 25.0+: Organizations (preview)
   - 26.0+: Organizations (GA), performance improvements

3. **Analyze** -- Apply Keycloak-specific reasoning. Consider realm isolation, client scopes, protocol mappers, and authentication flows.

4. **Recommend** -- Provide actionable guidance with admin console paths, CLI commands, and REST API examples.

## Core Expertise

### Realm Architecture

A realm is a tenant/namespace in Keycloak:

```
Master Realm (admin-only, never for applications)
  |-- Realm: company-internal (workforce identity)
  |     |-- Clients, Users, Groups, Roles, Identity Providers
  |-- Realm: company-customers (CIAM)
  |     |-- Clients, Users, Groups, Roles, Identity Providers
  |-- Realm: partner-portal (B2B)
        |-- Clients, Users, Groups, Roles, Identity Providers
```

**Realm design principles:**
- **Master realm** -- Used only for managing Keycloak itself. Never register application clients here.
- **Separate realms** -- For different trust boundaries (internal vs. customer vs. partner)
- **Not for multi-tenancy** -- Do not create a realm per customer (use Organizations instead). Hundreds of realms degrades performance.

### Clients

Clients are applications that delegate authentication to Keycloak:

| Client Type | Protocol | OIDC Flow | Example |
|---|---|---|---|
| **Public** | OIDC | Authorization Code + PKCE | SPA, mobile app |
| **Confidential** | OIDC | Authorization Code, Client Credentials | Backend web app, API |
| **Bearer-only** | OIDC | Token validation only | REST API |
| **SAML** | SAML 2.0 | SAML SP-initiated/IdP-initiated | Enterprise legacy apps |

**Client scopes:**
- Define groups of protocol mappers and role scope mappings
- **Default scopes** -- Automatically included in every token
- **Optional scopes** -- Included only when explicitly requested (`scope=` parameter)
- Built-in scopes: `openid`, `profile`, `email`, `address`, `phone`, `offline_access`

### Protocol Mappers

Transform user attributes and role assignments into token claims:

| Mapper Type | Source | Token Claim |
|---|---|---|
| User Attribute | User profile attribute | Custom claim in ID/access token |
| User Realm Role | Realm role assignments | `realm_access.roles` |
| User Client Role | Client role assignments | `resource_access.{client}.roles` |
| Group Membership | Group names | `groups` claim |
| Audience | Client configuration | `aud` claim |
| Hardcoded Claim | Static value | Fixed claim value |
| Script Mapper | JavaScript logic | Dynamic claim value |

### Identity Brokering

Connect Keycloak to external identity providers:

**Supported protocols:**
- OIDC (connect to Okta, Entra ID, Google, any OIDC provider)
- SAML 2.0 (connect to AD FS, Shibboleth, any SAML IdP)
- Social providers (Google, Facebook, GitHub, Twitter, etc.)

**Brokering flow:**
```
User clicks "Sign in with Google" on Keycloak login page
  --> Keycloak redirects to Google (or other IdP) for authentication
  --> Google authenticates user, returns to Keycloak
  --> Keycloak creates/links local user account
  --> Keycloak issues its own tokens to the application
```

**First login flow:** Configurable behavior on first brokered login:
- Automatically create user
- Review profile before creation
- Link to existing account (by email match)
- Require email verification

### User Federation

Integrate with external user stores (LDAP, Active Directory):

**LDAP/AD federation:**
- Read users and groups from LDAP directory
- Authenticate users against LDAP (delegated auth)
- Sync modes: import users to Keycloak DB, or query LDAP on every request
- Attribute mapping: map LDAP attributes to Keycloak user profile
- Writable: optionally write back changes to LDAP (password changes, profile updates)

**Configuration:**
```
Connection URL: ldaps://dc01.example.com:636
Bind DN: CN=keycloak-svc,OU=Service Accounts,DC=example,DC=com
Users DN: OU=Users,DC=example,DC=com
User Object Classes: inetOrgPerson, organizationalPerson
Username LDAP Attribute: sAMAccountName
UUID LDAP Attribute: objectGUID
Edit Mode: READ_ONLY (or WRITABLE)
Sync Settings: Full sync period = 3600, Changed users sync period = 60
```

### Fine-Grained Authorization Services

Keycloak provides a policy-based authorization framework:

**Components:**
- **Resources** -- What is being protected (e.g., `/api/documents`, `/api/admin`)
- **Scopes** -- Actions on resources (e.g., `read`, `write`, `delete`)
- **Policies** -- Rules that evaluate to permit/deny:
  - Role-based policy
  - User-based policy
  - Group-based policy
  - Time-based policy
  - JavaScript policy
  - Aggregated policy (combine multiple policies)
- **Permissions** -- Associate policies with resources/scopes

**UMA (User-Managed Access):**
- Extension to OAuth 2.0 for user-driven access sharing
- Resource owner can share resources with others
- Permission tickets for requesting access to protected resources
- Useful for document sharing, file access, collaborative scenarios

### Organizations (GA in 26.0)

Multi-tenancy within a single realm:

- **Organization** represents a customer/company
- Users are members of organizations
- Each organization can have its own identity providers
- Organization-specific authentication flows
- Attribute-based organization membership

**Why Organizations over multiple realms:**
- Better scalability (hundreds of organizations vs. hundreds of realms)
- Shared configuration (themes, flows, client scopes)
- Users can belong to multiple organizations
- Simpler management and monitoring

### Authentication Flows

Keycloak's authentication is built from configurable flows:

**Built-in flows:**
- Browser flow (username/password, OTP, WebAuthn)
- Direct grant flow (resource owner password)
- Registration flow (self-service sign-up)
- Reset credentials flow (password recovery)
- First broker login flow (brokered identity first login)

**Customization:** Flows are composed of execution steps:
- Cookie (check existing session)
- Identity Provider Redirector (social login buttons)
- Username/Password Form
- OTP Form
- WebAuthn Authenticator
- Conditional OTP (require OTP based on condition)
- Custom authenticator SPI (your own logic)

### Deployment (Quarkus-based)

```bash
# Start Keycloak in production mode
bin/kc.sh start \
  --hostname=auth.company.com \
  --https-certificate-file=/etc/tls/cert.pem \
  --https-certificate-key-file=/etc/tls/key.pem \
  --db=postgres \
  --db-url=jdbc:postgresql://db:5432/keycloak \
  --db-username=keycloak \
  --db-password=secret

# Build optimized image (pre-configures for startup performance)
bin/kc.sh build --db=postgres --features=organizations

# Docker / Kubernetes
docker run -e KC_HOSTNAME=auth.company.com \
           -e KC_DB=postgres \
           -e KC_DB_URL=jdbc:postgresql://db:5432/keycloak \
           quay.io/keycloak/keycloak:latest start
```

**Production checklist:**
- External database (PostgreSQL recommended, MySQL/MariaDB supported)
- TLS termination (Keycloak or reverse proxy)
- Hostname configuration (`--hostname`)
- Clustering (Infinispan for sessions, JGroups for discovery)
- Metrics endpoint enabled (`--metrics-enabled=true`, Prometheus format)
- Health endpoint enabled (`--health-enabled=true`)

### High Availability / Clustering

Keycloak uses Infinispan for distributed caching and JGroups for cluster communication:

- **Session replication** -- User sessions replicated across cluster nodes
- **Discovery** -- DNS_PING (Kubernetes), JDBC_PING (database), or UDP multicast
- **Load balancing** -- Sticky sessions recommended (but not required with replicated sessions)
- **Cross-DC deployment** -- Infinispan external mode for active-passive or active-active multi-DC

### Admin REST API

Full programmatic management:

```bash
# Get admin token
TOKEN=$(curl -s -X POST "https://auth.company.com/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin" \
  -d "grant_type=password" | jq -r '.access_token')

# Create a user
curl -X POST "https://auth.company.com/admin/realms/my-realm/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"jdoe","email":"jdoe@example.com","enabled":true}'

# Create a client
curl -X POST "https://auth.company.com/admin/realms/my-realm/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"my-app","protocol":"openid-connect","publicClient":true}'
```

## Common Pitfalls

1. **Using master realm for applications** -- Master realm is for Keycloak admin only. Create separate realms for applications.
2. **Realm-per-tenant at scale** -- Hundreds of realms degrade performance. Use Organizations for multi-tenancy.
3. **WildFly deployment still in use** -- WildFly distribution is end-of-life. Migrate to Quarkus-based Keycloak immediately.
4. **No external database in production** -- Default H2 database is for development only. Use PostgreSQL or MySQL.
5. **Skipping the build step** -- Quarkus-based Keycloak benefits from `kc.sh build` which pre-compiles configuration for faster startup.
6. **Custom themes breaking on upgrade** -- Themes that override base templates may break when Keycloak updates templates. Pin to specific versions and test upgrades.
7. **Session token not including necessary claims** -- Default token content may not include all needed claims. Configure protocol mappers and client scopes.