Keycloak Production Architecture

JGroups

Reliable group communication for Java applications

What is JGroups?

JGroups is a Java library for reliable messaging between processes in a cluster. It handles group membership (who's in the cluster), failure detection (who left), message ordering, and message delivery guarantees. Think of it as TCP but for groups of nodes instead of point-to-point.

Keycloak doesn't use JGroups directly — it uses Infinispan for caching, and Infinispan uses JGroups as its transport layer. So JGroups is the network plumbing underneath Keycloak's distributed caches.

How it works in Keycloak

When a Keycloak node starts, JGroups runs a discovery protocol to find other nodes and form a cluster. Once joined, JGroups handles:

• Cluster membership — detecting when nodes join or leave (including crashes)
• Message transport — sending cache updates between nodes (session created, session invalidated, realm config changed)
• Failure detection — heartbeat-based detection of unresponsive nodes, triggering Infinispan rebalancing
• Flow control — preventing fast senders from overwhelming slow receivers

Discovery protocols

The discovery protocol determines how nodes find each other on startup:

• KUBE_PING — queries the Kubernetes API for pods with matching labels. Requires RBAC permissions. Recommended for K8s.
• DNS_PING — resolves a DNS name (headless Service in K8s) to find peers. Simpler RBAC than KUBE_PING.
• TCPPING — static list of IP:port pairs. Works everywhere but requires manual config updates when nodes change.
• JDBC_PING — nodes register themselves in a shared database table. Useful for VM deployments where the DB is already shared.

Key configuration

Keycloak exposes JGroups config via environment variables:

# Kubernetes — use DNS_PING with headless service
KC_CACHE_STACK=kubernetes
# This sets: dns.query=keycloak-headless.<namespace>.svc.cluster.local

# VMs — use JDBC_PING (auto-discovers via shared DB)
KC_CACHE_STACK=jdbc-ping

# VMs — use TCPPING (static node list)
KC_CACHE_STACK=tcp
# Requires custom cache-ispn.xml with TCPPING initial_hosts

Ports & networking

• Port 7800 (TCP) — JGroups cluster communication. Must be open between all KC nodes.
• Additional ports 7801–7802 may be used for FD (failure detection) and state transfer.
• For cross-site (XSITE), a separate RELAY2 bridge channel connects Infinispan clusters across sites, also over JGroups.

In Kubernetes, these ports are handled automatically within the cluster network. On VMs, ensure firewall rules allow TCP 7800-7802 between all Keycloak hosts.

Encryption

JGroups traffic is unencrypted by default. For production, enable SYM_ENCRYPT (shared keystore) or ASYM_ENCRYPT (PKI-based). Keycloak's Quarkus distribution supports this via the cache-ispn.xml configuration file.

Infinispan

Distributed in-memory data grid for caching & state

What is Infinispan?

Infinispan is a distributed in-memory key/value data store written in Java. It provides caching, clustering, and data replication. Originally created by Red Hat (with a commercial version called Red Hat Data Grid), it's the backbone of Keycloak's session management and state distribution.

How Keycloak uses Infinispan

Keycloak embeds Infinispan to manage several types of cached data across the cluster:

• User sessions — active login sessions. Distributed cache (owners=2). Losing one node doesn't lose sessions.
• Authentication sessions — in-progress login flows. Short-lived. Lost if the owning node dies mid-login.
• Offline sessions — persistent refresh tokens surviving restarts. Distributed.
• Login failure counters — brute-force protection state. Distributed.
• Realm & client caches — configuration data. Replicated (full copy on every node) with local invalidation layers.
• Action tokens — email verification, password reset links. Distributed.

Embedded vs. External Infinispan

Embedded (default, single-site): Infinispan runs inside the Keycloak JVM process. No separate infrastructure needed. JGroups handles inter-node communication. This is sufficient for most single-datacenter deployments.

External (required for multi-site): A standalone Infinispan Server cluster runs separately from Keycloak. KC connects via the Hot Rod protocol. Required for XSITE (cross-site) replication because the Infinispan clusters at each site need to communicate independently of Keycloak.

Cache modes

• Distributed — data split across nodes with N owners (default 2). Scalable. Used for session data.
• Replicated — full copy on every node. Fast reads, expensive writes. Used for realm/client config.
• Local — not shared. Used as a near-cache layer in front of replicated/distributed caches.
• Invalidation — local caches that broadcast invalidation messages. Node re-reads from DB on miss.

Tuning for large deployments

<!-- cache-ispn.xml — increase owners for higher redundancy -->
<distributed-cache name="sessions" owners="3">
  <memory>
    <heap size="10000" eviction="COUNT"/>
  </memory>
</distributed-cache>

• owners — number of copies per entry. 2 is default. 3 for critical deployments. More owners = more memory + network overhead.
• Eviction — set memory bounds to prevent OOM. Evicted entries are re-read from DB (sessions) or trigger re-login (auth sessions).
• State transfer — when a node joins/leaves, Infinispan rebalances entries. This causes a brief CPU/memory spike.

Quarkus

Supersonic Subatomic Java framework

What is Quarkus?

Quarkus is a Java framework designed for cloud-native applications. It's built on established standards (CDI, JAX-RS, JPA) but optimized for fast startup, low memory, and container-first deployment. Created by Red Hat, it's the runtime that powers Keycloak since version 17.

Why Keycloak moved to Quarkus

Keycloak originally ran on Wildfly (formerly JBoss Application Server) — a full-featured Java EE application server. The move to Quarkus (completed in KC 17, Wildfly support dropped at KC 20) brought:

• Faster startup — Quarkus performs build-time optimization. Keycloak starts in 5–15 seconds vs. 30–90 seconds on Wildfly.
• Lower memory — roughly 50% less heap and metaspace usage for equivalent workloads.
• Simpler configuration — keycloak.conf or environment variables replace the complex standalone-ha.xml.
• Container-optimized — smaller images, better suited for K8s with predictable resource usage.
• Build-time augmentation — kc.sh build pre-compiles configuration, themes, and providers into an optimized runtime image.

The build step

Quarkus-based Keycloak has a distinct build phase that's different from traditional Java apps:

# Build phase — pre-compiles config, discovers providers
/opt/keycloak/bin/kc.sh build \
  --db=postgres \
  --features=docker,token-exchange

# Start phase — uses the optimized build output
/opt/keycloak/bin/kc.sh start \
  --hostname=keycloak.example.com \
  --db-url=jdbc:postgresql://db:5432/keycloak

The build step resolves providers, optimizes class loading, and locks in certain configuration. This is why Keycloak Dockerfiles have a two-stage pattern — build in one layer, run in the next.

Configuration model

All Keycloak configuration maps to environment variables or keycloak.conf:

• KC_DB → database vendor
• KC_HOSTNAME → public hostname
• KC_PROXY_HEADERS → proxy mode (xforwarded or forwarded)
• KC_CACHE_STACK → JGroups discovery protocol
• KC_LOG_LEVEL → logging verbosity

Build-time options (features, DB type, cache stack) require a rebuild. Runtime options (hostname, credentials, log level) can change on restart without rebuilding.

Liquibase

Java-based database schema migration and changelog tool

What is Liquibase?

Liquibase is an open-source database schema change management tool written in Java. It tracks, versions, and applies database schema changes (called changelogs) in a deterministic, repeatable way. Think of it as "Git for your database schema" — every change is recorded, ordered, and applied exactly once.

Liquibase supports multiple changelog formats (XML, YAML, JSON, SQL) and works with virtually every relational database. Keycloak uses XML-formatted changelogs bundled inside the Keycloak JAR.

How Keycloak uses Liquibase

Every time Keycloak starts, it checks whether the database schema is up to date. If a new version introduces schema changes, Keycloak runs the corresponding Liquibase changelogs automatically on startup. This is not optional — you cannot skip or defer migrations.

• Changelog execution — Keycloak bundles all migration changelogs inside its JARs. On startup, Liquibase compares what has been applied (tracked in the DB) against what exists in the changelog files, and executes any unapplied changesets.
• First-pod wins — in a multi-node cluster, the first pod to start acquires a Liquibase lock and runs the migration. All other pods wait for the lock to release before proceeding with their own startup. This is why the first pod in a rolling upgrade takes longer to become ready.
• Idempotent checks — Liquibase tracks each changeset by ID, author, and filepath. It will not re-run a changeset that has already been applied, even if you restart Keycloak multiple times.

Tracking tables

Liquibase creates two metadata tables in the Keycloak database:

• DATABASECHANGELOG — records every changeset that has been applied: ID, author, filename, date executed, checksum, execution status. This is how Liquibase knows what has already run.
• DATABASECHANGELOGLOCK — a single-row lock table that prevents multiple nodes from running migrations simultaneously. Contains a boolean LOCKED flag, the lock timestamp, and the identity of the node holding the lock.

-- Inspect applied changelogs
SELECT id, author, filename, dateexecuted, orderexecuted
FROM DATABASECHANGELOG
ORDER BY orderexecuted DESC
LIMIT 20;

-- Check lock status
SELECT * FROM DATABASECHANGELOGLOCK;

Forward-only migrations

This is the single most important thing to understand about Liquibase in Keycloak: migrations are forward-only. There is no kc.sh rollback command. Keycloak does not ship rollback changesets. Once a migration runs, the only way to undo it is to restore the database from a pre-upgrade backup.

This has critical implications for upgrade planning:

• Always take a consistent database backup immediately before upgrading — not a day-old scheduled backup.
• Stop all Keycloak nodes before taking the backup to ensure no writes are in flight.
• Test the upgrade against a copy of production data in staging first. This validates both the migration itself and its execution time.
• Large version jumps (e.g., v22 to v25) apply all intermediate changelogs sequentially. This can take minutes on large databases and carries cumulative risk.

When migrations fail

Migration failures are rare but high-impact. Common causes:

• Custom schema modifications — if someone manually altered Keycloak's tables (added columns, changed types, added constraints), a changelog may fail because the expected pre-condition doesn't match.
• Insufficient DB permissions — the Keycloak DB user needs DDL privileges (CREATE, ALTER, DROP on tables and indexes).
• Lock table stuck — if Keycloak was killed mid-migration (OOMKilled, node crash, manual kill), the lock row stays in a locked state. All subsequent startups will hang waiting for a lock that will never release.

-- Fix a stuck Liquibase lock (ONLY when you are certain no migration is running)
UPDATE DATABASECHANGELOGLOCK
SET LOCKED = FALSE, LOCKGRANTED = NULL, LOCKEDBY = NULL
WHERE ID = 1;

After clearing a stuck lock, investigate why the migration was interrupted. Check if any partial DDL was applied. Liquibase marks failed changesets — inspect DATABASECHANGELOG for entries with an error status. You may need to manually complete the failed changeset or restore from backup.

Operational tips

• Monitor first-pod startup time — during upgrades, the migration pod will take significantly longer. Set your Kubernetes startupProbe failureThreshold high enough to accommodate this (5+ minutes for large DBs).
• Never manually edit DATABASECHANGELOG unless you fully understand the consequences. Deleting rows will cause Liquibase to re-run those changesets, which will almost certainly fail on a non-empty database.
• Checksum validation — Liquibase stores an MD5 checksum for each changeset. If someone modifies a changelog file after it has been applied, Liquibase will fail with a checksum mismatch on next startup. This is a safety mechanism — don't override it.
• Migration duration — for databases with millions of rows in user/session tables, migrations involving schema changes on those tables can take several minutes. Plan maintenance windows accordingly.

OpenID Connect (OIDC)

Identity layer built on top of OAuth 2.0

What is OIDC?

OpenID Connect is an identity authentication protocol built as a layer on top of OAuth 2.0. Where OAuth 2.0 is an authorization framework (delegating access to resources), OIDC adds standardized identity — it answers "who is this user?" in a structured, verifiable way.

OIDC is the dominant modern authentication protocol for web, mobile, and API applications. It replaced older approaches (SAML for SPAs, custom token schemes, session cookies across domains) with a JSON/REST-based standard that works natively with JavaScript frontends and mobile apps.

Key flows

OIDC defines several grant types (flows) for different use cases:

• Authorization Code — the standard flow for web apps. User is redirected to Keycloak, authenticates, and is redirected back with an authorization code. The app exchanges the code for tokens server-side. Always use with PKCE (Proof Key for Code Exchange) — even for confidential clients, PKCE is now best practice.
• Client Credentials — machine-to-machine (M2M) authentication. No user involved. The client authenticates directly with its client ID and secret to get an access token. Used for service-to-service communication, batch jobs, and API integrations.
• Device Code — for input-constrained devices (smart TVs, CLI tools, IoT). The device displays a code, the user enters it on a separate device with a browser, and the device polls for the resulting token.
• Token Exchange — exchanging one token for another. Used for delegation scenarios (user A's token exchanged for a token allowing service B to act on behalf of A). Must be explicitly enabled in Keycloak (--features=token-exchange).

Deprecated flows: Implicit flow (tokens in URL fragment — insecure) and Resource Owner Password Credentials (ROPC — sends username/password directly to the app). Both are still supported in Keycloak but should not be used in new applications.

The three tokens

OIDC issues three types of tokens, each serving a distinct purpose:

• ID Token — contains identity claims about the authenticated user (sub, name, email, groups). Consumed by the client application to know who logged in. Short-lived (minutes). Never send the ID token to an API — it's for the client, not for resource servers.
• Access Token — authorizes API requests. Sent in the Authorization: Bearer header. Contains scopes and permissions. Resource servers validate this token (via signature verification or introspection). Short-lived (5–15 minutes recommended).
• Refresh Token — used to obtain new access tokens without re-authenticating the user. Longer-lived (30 minutes to hours). Stored securely by the client. Rotation is recommended — Keycloak supports refresh token rotation where each use invalidates the old token and issues a new one.

JWT structure and signing

Keycloak issues tokens as JSON Web Tokens (JWTs) — a compact, URL-safe format consisting of three Base64URL-encoded parts separated by dots:

header.payload.signature

# Header — algorithm and key ID
{"alg": "RS256", "typ": "JWT", "kid": "abc123"}

# Payload — claims (identity + authorization data)
{"sub": "user-uuid", "iss": "https://keycloak.example.com/realms/myrealm",
 "aud": "my-client", "exp": 1711234567, "iat": 1711234267,
 "realm_access": {"roles": ["admin", "user"]},
 "name": "Jane Doe", "email": "jane@example.com"}

# Signature — RS256 or ES256 over header+payload

• RS256 (RSA + SHA-256) — default in Keycloak. 2048-bit key. Widely supported. Produces larger tokens (~800+ bytes signature).
• ES256 (ECDSA + SHA-256) — smaller signatures, equivalent security. Produces smaller tokens. Good choice when token size matters (e.g., headers hitting size limits).

Resource servers validate tokens by fetching Keycloak's public key from the JWKS endpoint and verifying the signature locally. No network call to Keycloak is needed for each request — this is what makes JWT-based auth scalable.

OIDC vs. SAML

Both are SSO protocols, but they serve different eras and use cases:

• OIDC — JSON-based, REST-native, compact tokens (JWTs), works well with SPAs/mobile/APIs, modern.
• SAML 2.0 — XML-based, SOAP-era, verbose assertions, designed for server-rendered web apps, mature enterprise standard.
• When to use SAML — legacy enterprise apps that only support SAML (e.g., older ServiceNow, Salesforce classic, on-prem apps). Many SaaS providers support both but default to SAML for enterprise SSO.
• When to use OIDC — everything new. SPAs, mobile apps, microservices, APIs, any greenfield development.

Keycloak supports both protocols simultaneously. A single realm can have OIDC clients and SAML clients side by side, sharing the same user pool, sessions, and authentication flows.

Keycloak's well-known endpoint

Every OIDC-compliant provider publishes a discovery document at a standard URL:

https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration

This returns a JSON document containing all the endpoints a client needs: authorization endpoint, token endpoint, userinfo endpoint, JWKS URI, supported scopes, supported grant types, and more. Client libraries use this for auto-configuration — you typically only need to provide the issuer URL and the library discovers everything else.

The JWKS endpoint (/realms/{realm}/protocol/openid-connect/certs) publishes the realm's public signing keys. Resource servers fetch and cache these keys to validate token signatures. When Keycloak rotates keys, a new kid (key ID) appears in tokens, and clients re-fetch the JWKS on the next verification attempt.

Kerberos / SPNEGO

Network authentication protocol and Windows SSO mechanism

What is Kerberos?

Kerberos is a network authentication protocol that uses symmetric-key cryptography and a trusted third party (the Key Distribution Center, or KDC) to authenticate users and services to each other without transmitting passwords over the network. It was developed at MIT and is the default authentication protocol in Active Directory environments.

In enterprise environments, Kerberos is the mechanism behind Windows desktop SSO — users log into their workstation once (domain login) and are transparently authenticated to internal web applications without entering credentials again.

What is SPNEGO?

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is a negotiation wrapper that allows Kerberos to work over HTTP. Browsers and web servers use SPNEGO to negotiate which authentication mechanism to use — in practice, it almost always resolves to Kerberos.

The flow works like this:

• User's browser sends a request to the Keycloak login page.
• Keycloak responds with HTTP 401 and header WWW-Authenticate: Negotiate.
• The browser obtains a Kerberos service ticket for Keycloak's SPN from the KDC (using the user's existing TGT from their domain login).
• The browser resends the request with Authorization: Negotiate <base64-encoded-ticket>.
• Keycloak validates the ticket using the keytab file containing the service's secret key.
• If valid, the user is authenticated — no password prompt, no redirect, completely transparent.

How Kerberos authentication works (detailed)

Understanding the ticket-based flow helps with troubleshooting:

• TGT (Ticket-Granting Ticket) — when the user logs into their Windows workstation, the machine contacts the KDC (domain controller) and obtains a TGT. This TGT is cached in the user's credential cache and proves their identity to the KDC for subsequent requests.
• Service Ticket — when the user needs to access a Kerberos-protected service (like Keycloak), their machine presents the TGT to the KDC and requests a service ticket for the specific SPN. The KDC issues a ticket encrypted with the service's secret key.
• Validation — the service (Keycloak) decrypts the ticket using its keytab file, which contains the same secret key. If decryption succeeds and the ticket is not expired, the user is authenticated.

The entire flow happens without the user's password ever being sent to Keycloak or transmitted over the network after the initial domain login.

Requirements in Keycloak

Setting up Kerberos/SPNEGO in Keycloak requires careful preparation across multiple systems:

• SPN (Service Principal Name) — register in Active Directory: HTTP/keycloak.example.com@EXAMPLE.COM. The hostname must exactly match what users type in their browsers. Use setspn -A on the domain controller.
• Keytab file — generated from AD using ktpass (Windows) or msktutil (Linux). Contains the service's secret key. Mount as a file in the Keycloak container or place on the VM filesystem. Protect it like a private key.
• DNS (forward + reverse) — Kerberos is extremely DNS-sensitive. The hostname in the SPN must resolve via forward DNS to the correct IP, and that IP must reverse-resolve back to the same hostname. Mismatched DNS is the #1 cause of Kerberos failures.
• NTP synchronization — Kerberos has a default 5-minute clock skew tolerance. If the clocks on the client, KDC, and Keycloak server drift beyond this, tickets are rejected silently. NTP is non-negotiable.
• Keycloak configuration — configure an LDAP User Federation provider with Kerberos integration enabled. Specify the keytab path, the Kerberos realm (e.g., EXAMPLE.COM), and the server principal.

# Generate keytab on Windows domain controller
ktpass -princ HTTP/keycloak.example.com@EXAMPLE.COM \
  -mapuser keycloak_svc@EXAMPLE.COM \
  -pass * -crypto AES256-SHA1 \
  -ptype KRB5_NT_PRINCIPAL \
  -out keycloak.keytab

# Verify keytab on Linux
klist -kt keycloak.keytab
# Should show: HTTP/keycloak.example.com@EXAMPLE.COM

# Test ticket acquisition
kinit -kt keycloak.keytab HTTP/keycloak.example.com@EXAMPLE.COM
klist

Browser configuration

Browsers do not send Kerberos tickets by default — they must be configured to trust the Keycloak domain. This is typically managed via Group Policy in enterprise environments:

• Internet Explorer / Edge — add the Keycloak URL to the Local Intranet zone. Enable "Integrated Windows Authentication" in Internet Options > Advanced.
• Chrome — inherits IE settings on Windows. On Linux/macOS, set the --auth-server-allowlist flag or use policy: AuthServerAllowlist = "*.example.com".
• Firefox — set network.negotiate-auth.trusted-uris to https://keycloak.example.com in about:config, or deploy via Group Policy / policies.json.

Use Group Policy Objects (GPOs) to push browser settings to all domain-joined workstations. This ensures consistent Kerberos behavior without requiring user action.

Common failure causes

Kerberos troubleshooting follows a consistent pattern — these are the usual suspects, in order of frequency:

• DNS mismatch (#1) — the hostname in the URL doesn't match the SPN, or reverse DNS doesn't match forward DNS. Always verify with nslookup in both directions.
• Clock skew — clocks differ by more than 5 minutes between client, KDC, and Keycloak. Check with w32tm /query /status (Windows) or timedatectl (Linux).
• Missing or wrong SPN — duplicate SPNs in AD, SPN registered on the wrong account, or hostname casing mismatch. Check with setspn -Q HTTP/keycloak.example.com.
• Browser not configured — browser doesn't trust the domain, so it never attempts Negotiate auth. User sees a login form instead of transparent SSO.
• Keytab mismatch — keytab was regenerated (e.g., password reset on the service account) but not updated on the Keycloak server. The old keytab can't decrypt tickets encrypted with the new key.
• Encryption type mismatch — AD and Keycloak disagree on supported encryption types (e.g., AD only allows AES256 but the keytab was generated with RC4). Align encryption types in AD security policy and keytab generation.
• Firewall blocking KDC — the Keycloak server (or the user's workstation) cannot reach the KDC on port 88 (TCP/UDP). Kerberos requires direct connectivity to the domain controller.

Kerberos + OIDC: the bridge pattern

A common enterprise pattern: users authenticate to Keycloak via Kerberos/SPNEGO (transparent Windows SSO), and Keycloak issues OIDC tokens to the downstream application. This bridges the legacy Windows authentication world with modern OIDC-based apps. The application never needs to understand Kerberos — it only sees standard OIDC tokens.

SAML 2.0

Security Assertion Markup Language — the XML-based SSO standard that dominates enterprise identity federation

What is SAML?

SAML 2.0 (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between parties — specifically between an Identity Provider (IdP) and a Service Provider (SP). Published in 2005 by OASIS, it remains the dominant SSO protocol in enterprise environments, especially for web-based applications.

Keycloak can act as both a SAML IdP (authenticating users and issuing assertions to applications) and a SAML SP (federating identity from an upstream IdP like ADFS or Okta via identity brokering).

How the SAML flow works

The most common flow is the SP-initiated SSO using the HTTP POST binding:

1. User visits the application (SP). The app sees no session.
2. SP generates an AuthnRequest (XML) and redirects the user's browser to Keycloak (IdP)
3. Keycloak authenticates the user (login form, Kerberos, MFA, etc.)
4. Keycloak generates a SAML Response containing an Assertion — a signed XML document with the user's identity, attributes, and conditions
5. Keycloak POSTs the Response back to the SP's Assertion Consumer Service (ACS) URL via the user's browser
6. SP validates the XML signature, checks conditions (audience, timestamps), extracts user attributes, and creates a session

Key SAML concepts

• Assertion — the core payload. Contains authentication statements (who the user is, when they authenticated), attribute statements (email, groups, roles), and authorization decision statements (rarely used).
• Entity ID — a globally unique identifier for each party (IdP and SP). Usually a URL but doesn't have to resolve. Must match exactly between IdP and SP configurations.
• Metadata — XML document describing the entity's endpoints, certificates, supported bindings, and capabilities. Exchange metadata between IdP and SP to automate configuration.
• Bindings — how SAML messages are transported. HTTP-Redirect (for AuthnRequests via URL query params), HTTP-POST (for Responses via auto-submitting forms), and SOAP/Artifact (for back-channel communication).
• Name ID — the identifier for the user in the assertion. Can be email, username, persistent (opaque), or transient (random per session).
• Relay State — an opaque value passed through the flow to maintain the user's original destination URL after authentication.

Keycloak SAML configuration

# Keycloak SAML IdP metadata endpoint:
https://keycloak.example.com/realms/myrealm/protocol/saml/descriptor

# Key settings when creating a SAML client in Keycloak:
Client ID:            https://app.example.com/saml/metadata  (the SP Entity ID)
Root URL:             https://app.example.com
Valid Redirect URIs:  https://app.example.com/*
Master SAML URL:      https://app.example.com/saml/acs
Name ID Format:       email (or persistent, username, etc.)
Sign Assertions:      ON  (always)
Sign Documents:       ON
Encrypt Assertions:   OFF (unless the SP requires it)
Force POST Binding:   ON

SAML vs. OIDC — when to use which

OAuth 2.0

The authorization framework that underpins modern API security and delegated access

What is OAuth 2.0?

OAuth 2.0 is an authorization framework (RFC 6749) that enables applications to obtain limited access to user resources without exposing credentials. It was designed to solve a specific problem: how can a user grant a third-party application access to their data on another service, without sharing their password?

A critical distinction: OAuth 2.0 is about authorization (what can you access?), not authentication (who are you?). OIDC was built on top of OAuth 2.0 to add the authentication layer. Keycloak implements both.

Core roles

• Resource Owner — the user who owns the data (e.g., a GitLab user who owns their repositories)
• Client — the application requesting access (e.g., a CI tool that wants to read GitLab repos)
• Authorization Server — issues tokens after authenticating the user and obtaining consent (this is Keycloak)
• Resource Server — the API that hosts the protected resources (e.g., GitLab's API). Validates access tokens.

Grant types (flows)

• Authorization Code — the standard flow for web apps. User is redirected to Keycloak, authenticates, Keycloak returns an authorization code to the client, the client exchanges it for tokens via a back-channel call. Most secure for web apps.
• Authorization Code + PKCE — same flow but with Proof Key for Code Exchange. Required for public clients (SPAs, mobile apps) that can't safely store a client secret. PKCE prevents authorization code interception attacks.
• Client Credentials — machine-to-machine. No user involved. The client authenticates directly with its client ID and secret to get an access token. Used for service-to-service communication.
• Device Authorization — for devices with limited input (smart TVs, CLI tools). User authorizes on a separate device by entering a code displayed on the device.
• Token Exchange — exchange one token for another (e.g., impersonation, delegation). Keycloak supports this for advanced multi-service architectures.

Token types

• Access Token — short-lived (minutes). Presented to resource servers to authorize API requests. In Keycloak, this is a signed JWT containing claims about the user and their permissions.
• Refresh Token — longer-lived (hours/days). Used to obtain new access tokens without re-authenticating. Should be stored securely and is only sent to the authorization server, never to resource servers.
• ID Token — an OIDC addition (not part of core OAuth 2.0). A JWT containing user identity claims. Only consumed by the client application, not sent to resource servers.

Scopes and consent

Scopes define the boundaries of access a client is requesting. Standard scopes include openid, profile, email, roles. Custom scopes can be created in Keycloak to map to specific API permissions. When a client requests scopes, Keycloak can optionally show a consent screen asking the user to approve the requested access.

Keycloak OAuth 2.0 endpoints

# Discovery document (lists all endpoints):
https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

# Key endpoints:
Authorization: /realms/{realm}/protocol/openid-connect/auth
Token:         /realms/{realm}/protocol/openid-connect/token
UserInfo:      /realms/{realm}/protocol/openid-connect/userinfo
Introspect:    /realms/{realm}/protocol/openid-connect/token/introspect
Revoke:        /realms/{realm}/protocol/openid-connect/revoke
JWKS:          /realms/{realm}/protocol/openid-connect/certs

JSON Web Token (JWT)

The compact, self-contained token format that carries identity and authorization claims

What is a JWT?

A JSON Web Token (RFC 7519) is a compact, URL-safe way to represent claims between two parties. It consists of three Base64URL-encoded parts separated by dots: header.payload.signature. JWTs are the token format used by Keycloak for access tokens, ID tokens, and refresh tokens.

The key property of a JWT is that it is self-contained: the resource server can validate the token and extract user information without contacting the authorization server. This is what makes JWTs scalable — no back-channel token introspection needed for every API request.

JWT structure

# Header (algorithm + type)
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-from-keycloak-jwks"
}

# Payload (claims)
{
  "iss": "https://keycloak.example.com/realms/myrealm",
  "sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "aud": "my-app",
  "exp": 1711234567,
  "iat": 1711230967,
  "auth_time": 1711230960,
  "azp": "my-app",
  "scope": "openid profile email",
  "email": "user@example.com",
  "name": "Jane Smith",
  "preferred_username": "jsmith",
  "realm_access": {
    "roles": ["admin", "user"]
  },
  "resource_access": {
    "my-app": {
      "roles": ["app-admin"]
    }
  }
}

# Signature
RSASHA256(base64url(header) + "." + base64url(payload), privateKey)

Key claims

• iss (issuer) — who created the token. Must match the expected Keycloak realm URL.
• sub (subject) — unique user identifier. In Keycloak, this is the user's UUID.
• aud (audience) — who the token is intended for. Resource servers should reject tokens not addressed to them.
• exp (expiration) — Unix timestamp. Reject tokens past this time. No exceptions.
• iat (issued at) — when the token was created.
• azp (authorized party) — the client that requested the token.
• realm_access / resource_access — Keycloak-specific claims containing realm-level and client-level role mappings.

Token validation

Every resource server must validate JWTs before trusting them. The validation steps:

1. Verify the signature — fetch Keycloak's public keys from the JWKS endpoint (/realms/{realm}/protocol/openid-connect/certs), match the kid from the token header, verify the signature using the public key
2. Check expiration — reject if exp is in the past (allow a few seconds of clock skew)
3. Check issuer — iss must match your expected Keycloak realm URL exactly
4. Check audience — aud must include your service's client ID
5. Extract claims — read roles, scopes, user attributes as needed

Signing algorithms

• RS256 (RSA + SHA-256) — asymmetric. Keycloak signs with a private key, resource servers verify with the public key from JWKS. This is the default and recommended algorithm. Resource servers never need the private key.
• ES256 (ECDSA + SHA-256) — asymmetric, smaller keys and signatures than RSA. Good alternative if performance matters.
• HS256 (HMAC + SHA-256) — symmetric. Both parties share the same secret. Simpler but less secure for distributed systems — every service that validates tokens needs the secret, creating key distribution challenges.

JWT pitfalls

• JWTs can't be revoked — once issued, a JWT is valid until it expires. If a user is deactivated, their existing tokens still work. Mitigation: use short expiration times (5-15 minutes) and rely on refresh token revocation.
• Token size — JWTs with many roles/groups can become large (several KB). They're sent in every API request as a Bearer token. Watch for HTTP header size limits in proxies and load balancers.
• Don't store secrets in JWTs — the payload is Base64-encoded, not encrypted. Anyone can decode and read the claims. Never put passwords, API keys, or PII that shouldn't be visible to the client.
• Clock skew — if the issuer and validator clocks are out of sync, tokens may be rejected prematurely or accepted after expiry. Use NTP and allow 30-60 seconds of leeway.

Keycloak token customization

Keycloak allows extensive JWT customization via protocol mappers:

• User Attribute Mapper — add custom user attributes (department, employee ID) to the token
• Group Membership Mapper — include group paths in the token
• Audience Mapper — add additional audiences for multi-service architectures
• Hardcoded Claim Mapper — add static claims (environment, tenant ID)
• Script Mapper — custom JavaScript logic to compute claim values (since KC 18, scripts must be deployed as JAR providers — admin console upload is disabled for security)