Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

Introduction — One Minor Every Quarter, and This Time It's 26.7
The SCIM API — a Four-Year-Old Issue Reaches Core (Preview)
Multi-Cluster v2 — No More External Infinispan (Preview)
Organizations — Multi-Tenancy Delegation Gets Practical
What's Easy to Trip Over in the Upgrade
Deprecation Radar — What to Turn Off or Migrate Off of Now
Other Standards Experiments — One Paragraph Each
So, When Do You Upgrade, and What Do You Turn On
Closing
References

Introduction — One Minor Every Quarter, and This Time It's 26.7

Keycloak has been shipping minors roughly every three months lately. By GitHub release dates, 26.5.0 landed on January 6, 2026, 26.6.0 on April 8, and 26.7.0 on July 9. Most minors are worth a quick skim of the release notes and nothing more, but this one has more for an operator to snag on — two long-awaited features (SCIM, multi-cluster without an external cache) landed in preview, and the breaking/notable list in the upgrade guide is unusually long.

This post is an operations-focused read built by cross-checking the official release notes against the repository's original adoc files (release notes, upgrade guide), plus Profile.java, which is where feature flags are actually defined. If Keycloak 26's architecture itself is new to you, read the Keycloak 26 architecture deep dive first.

The SCIM API — a Four-Year-Old Issue Reaches Core (Preview)

SCIM (System for Cross-domain Identity Management) is a protocol for reading and writing identity resources like users and groups across systems through a standard REST API (schema in RFC 7643, protocol in RFC 7644). It's taken for granted in commercial IdPs like Okta or Entra ID, but Keycloak core has never had it. The SCIM support request opened in August 2022 has racked up 300 reactions and is still open; in the meantime the gap has been filled by third-party extensions like scim-for-keycloak.

That gap has now started to close in core. Tracing the timeline through the code tells the story: the scim-api feature flag was quietly added to Profile.java as experimental in 26.6.0 (the 26.6.0 release notes don't mention it at all), and it was promoted to preview in 26.7.0. It's off by default, so you need --features=scim-api to turn it on, and even after that it has to be toggled per realm in the realm settings.

Per the SCIM chapter of the admin guide, the scope of the implementation is:

Full create/read/update/PATCH/delete for users and groups, plus group membership management
The complete SCIM filter syntax and pagination
Custom schema extension via the Enterprise User extension (RFC 7643 §4.3) and User Profile attribute mapping
A schema discovery endpoint

Endpoints are exposed per realm.

/realms/<realm-name>/scim/v2/ServiceProviderConfig
/realms/<realm-name>/scim/v2/ResourceTypes
/realms/<realm-name>/scim/v2/Schemas
/realms/<realm-name>/scim/v2/Users
/realms/<realm-name>/scim/v2/Groups

No new authorization model was built for this — it reuses the same realm-management roles as the Admin REST API. Writing users needs manage-users, reading needs view-users, and searching needs query-users/query-groups — if you already have a service account for the Admin API, SCIM works with no extra setup. Only confidential clients are allowed to call it; public clients are rejected.

One design choice worth noting is the protection of admin resources. SCIM clients typically run with broad management privileges, so the docs explicitly guard against a compromised provisioning client deleting admin accounts or pushing users into admin groups — SCIM lookups of users or groups that carry management roles return only a minimal representation (roughly id, schemas, userName), and writes to them are rejected with a 403. Admin accounts can still only be touched through the Admin console and the Admin REST API.

To be honest about the limits: what landed is only the direction where Keycloak becomes the SCIM server. That covers inbound provisioning — an HR system or identity governance platform pushing users into and out of Keycloak. Going the other way, Keycloak acting as a SCIM client to federate users in from an external SCIM provider is still tracked in a separate, still-open issue, and the docs only list federation from an external SCIM service provider and push-based real-time events as future-release plans. Outbound provisioning — Keycloak pushing changes to downstream apps — is also out of scope here; that remains extension territory. And preview is preview: it's unsupported, and the final shape can still change.

Multi-Cluster v2 — No More External Infinispan (Preview)

Until now, Keycloak's multi-site HA (v1) required standing up and operating a separate external Infinispan (Data Grid) cluster for cross-site session replication, on top of vendor-specific fencing infrastructure for automatic failover — the setup covered in the Keycloak HA clustering guide. If you've operated it, you know the cost of babysitting a second distributed system — the cache cluster — just to keep an auth server highly available isn't small.

26.7's multi-cluster v2 strips out that external dependency entirely. The architecture changes like this:

Keycloak instances connect directly across clusters using an embedded Infinispan cache.
A synchronously replicated database becomes the single source of truth. This is why the feature flag is named stateless — per its definition in Profile.java, authentication sessions, action tokens, and login-failure data are stored in the DB so that multiple clusters can be tied together through the database alone.
Cross-site cache invalidation is handled with a DB-based outbox pattern.
The load balancer detects site outages without external fencing.

That description alone might sound like it covers geographic DR too, but the official guide pins down the constraints, and carrying them over verbatim:

It's built only for a single region, or an environment with equivalently low latency. A synchronously replicated, highly available database is mandatory, and the read/write/commit latency from the cluster to the DB should be under 5ms and must be under 10ms. Don't expect cross-continent active-active DR.
The configuration the team regularly tests (vendor-measured) is two single-AZ OpenShift (ROSA HCP) clusters in the same AWS region, plus Aurora PostgreSQL 17.5 with a cross-AZ synchronous replication leader, plus AWS Global Accelerator, tested at a load of 1 million users and 300 requests per second. Anything beyond that scale is explicitly left for you to validate yourself.
Depending on the failure scenario, downtime of several minutes is possible, and manual intervention may be needed depending on the DB vendor. Node-failure detection is under a minute by default.

One more thing from an operations angle — in Profile.java this feature is declared with FeatureUpdatePolicy.SHUTDOWN. That means toggling the flag on or off can't be rolled out gradually; it requires a full cluster shutdown. This isn't the kind of feature you slot into an already-running production system without downtime.

To sum up, v2 is "region-local multi-cluster availability with the external Infinispan operations removed," not "two data centers far apart." What you get in exchange is clear, though — one fewer distributed system to manage, and no more requirement to be locked into a specific environment like Kubernetes or AWS. If your load fits inside the tested envelope and your organization can run the DB with synchronous replication, it's a trade worth making against v1's operational complexity.

A side note: at tag time, the original release notes had an inconsistency — labeling this feature preview in the highlights but experimental in the body heading (it's been cleaned up to preview on the main branch), while Profile.java in code had it as PREVIEW from the start. When the release notes and the code disagree, trust the code.

Organizations — Multi-Tenancy Delegation Gets Practical

As covered in designing SSO for multi-tenant SaaS, Keycloak's Organizations feature manages multiple tenants (organizations) within a single realm. Until now, though, managing an organization required the high-privilege manage-realm role — effectively handing a tenant admin full realm management rights, which made "delegation" a bit of a stretch.

26.7 fixes that.

Three dedicated realm management roles were added: manage-organizations (full read/write on organizations), view-organizations (read-only), and query-organizations (list/search only) — the same pattern as the existing query-users/query-clients roles. manage-realm still implies organization management for backward compatibility.
Organizations are now a first-class resource type under Fine-Grained Admin Permissions. You can create a delegated admin scoped to a single organization, and when FGAP is enabled, organization member lookups also honor user-level permissions and only return members the caller is allowed to see.
Realm/client roles can now be mapped onto organization groups. Attaching a role to an organization group once propagates it into every member's realm_access/resource_access claims automatically, and enabling the relevant option on the Organization Group Membership protocol mapper lets you nest that into the organization claim per organization. In short: manage roles at the group level instead of attaching them per member for tenants with hundreds of people.

There's a breaking change bundled in too. The organization member list API now returns the brief representation by default. If you need the full user representation, you have to request it explicitly with a query parameter.

GET /admin/realms/{realm}/organizations/{id}/members?briefRepresentation=false

The email/firstName/lastName filters on the organization invitation list also changed from partial match to case-insensitive exact match — use the search parameter if you need partial matching. If you have automation depending on these APIs, check first whether the response shape and filter behavior changed under you.

What's Easy to Trip Over in the Upgrade

Here's what I picked out of this release's upgrade guide as things an operator is actually likely to hit. See the full upgrade guide for the complete list.

PostgreSQL asynchronous commit is now on by default. Transactions that only touch volatile tables — persisted user sessions, client sessions, login failures, events — are now handled with PostgreSQL's async commit (logout still forces synchronous commit). It's a performance-motivated change, but you need to understand exactly what it means: per the PostgreSQL docs, asynchronous commit returns success before the WAL is flushed to disk, and if the server crashes, commits in that window are lost. The loss window is at most three times wal_writer_delay (200ms by default). Nothing gets corrupted — what disappears is at most the last well-under-a-second of session/event writes, and from the user's perspective it just means logging back in. Worth calling out, though, is that the events table is included — that means a login event right before a crash could be missing from the audit log, so if you're in an environment with strict audit requirements, decide whether to opt out with --spi-connections-jpa--quarkus--async-commit=false.

X.509 client authentication gets a CA Subject DN option, and it's effectively mandatory now. If you're authenticating clients with mTLS, the admin console now enforces specifying the subject DN of the trust-anchor CA. Existing configurations keep working for now, but starting with the next major, server-side validation kicks in and creates/updates/imports without this option will be rejected. The option that let you match certificates by regex instead of an exact DN is also deprecated alongside this. If you're passing certificates through headers behind a TLS-terminating proxy, double-check that the truststore is set up to validate the client certificate chain.

The self-registration flow changes. If a realm has self-registration and Verify Email enabled together, the password field is now gone from the registration form by default. Users register with just a profile, and after their email is verified, they set a password (or OTP, or passkey). This flips the old order of creating credentials before the email is even verified — it's a change that touches the registration UX and every bit of documentation and screenshots along with it. There's a switch to restore the old behavior, but it's marked deprecated.

The rest, compressed into a list:

The shutdown timeout went from 1 second to 10 seconds, and shutdown now waits for the distributed cache rebalance to finish before going down. Align this with your orchestrator's termination grace period (e.g. terminationGracePeriodSeconds). Adjustable via the shutdown-timeout option.
Newly generated client secrets are now always 86 characters (to guarantee enough entropy for HS512). Existing secrets are untouched, but if wherever you store secrets has a max-length constraint, you'll need to raise it.
The session cookie hash moved from SHA-256 to SHA-384, and the default size for newly generated aes-generated keys went from 128 bits to 256 bits (both for CNSA 2.0 alignment; existing sessions and existing realms are unaffected).
The view-system admin role, which was deprecated the moment it was introduced in 26.5.4, has been removed for security reasons. Server-wide info lookups are now restricted to holders of manage-realm in the master realm.
FreeMarker's default moved to 2.3.32. Custom login themes that lean on legacy directives or internal access like ?api must be tested after upgrading. Button placement in the login theme has also changed.
DPoP is now rejected in implicit/hybrid flows. Because the sender-constrained model doesn't hold up in flows where the access token goes out over the front channel, that combination is now an error.
The Admin REST API no longer includes service accounts when looking up a user by ID, and an Identity Provider's alias can no longer be changed once created.
Authorization Services' resource URI template validation got stricter. Patterns that never actually worked to begin with, like a wildcard in the middle of a path, are now rejected at create/update time, so the guide even ships a pre-check query for auditing your resources' uris fields before you upgrade.

Deprecation Radar — What to Turn Off or Migrate Off of Now

Identity Brokering API V1 is deprecated. Its replacement, V2, switches from attaching a broker role to a user to per-client authorization (a switch that allows fetching external tokens, plus an IdP allow-list), only allows confidential clients, and uses POST with standard JSON responses. V2 is supported in this release but disabled by default, and V1 is still enabled by default — a future release will remove V1 and make V2 the default, so if you have applications pulling external IdP tokens, now's the time to start moving to V2.
The Twitter Identity Broker is slated for removal, because it depends on the legacy OAuth 1.0a endpoints. Migrate by configuring a generic OAuth v2 IdP against X's OAuth 2.0 endpoints, and if you don't use it, you can disable it now with --features-disabled=twitter-broker.
The Bearer-only switch on OIDC clients is deprecated. It's already gone from the console and only configurable via REST, and even that path is slated to be closed off. You can achieve the same goal with a grantless OIDC client.
The Require Discoverable Credential option in the WebAuthn policy is deprecated. The new Discoverable Credential option directly supports the WebAuthn spec's residentKey values (required/preferred/discouraged) — the preferred value, which a forced yes/no couldn't express, matters for compatibility with passkey providers like iCloud Keychain, Google Password Manager, and 1Password. Where the passkey ecosystem stands right now is covered in the rundown on passkey credential exchange.
SHA-1 will be fully removed in Keycloak 27. Citing NIST's SHA-1 retirement plan (full retirement by 2030), the upgrade guide treats SHA-1 as already retired within Keycloak and directs you to move to SHA-2/SHA-3 now. If you're still using SHA-1 for a SAML signing algorithm or in an older integration, clean it up before 27 ships.

Other Standards Experiments — One Paragraph Each

This release has an unusually large number of experimental-tagged standards implementations. All are off by default, and keep in mind experimental is a stage earlier than preview as you skim these.

Shared Signals Framework sender (ssf): pushes security events — logout, credential changes, account disablement — to downstream consumers in near real time as signed SETs (RFC 8417). It supports the CAEP 1.0 and RISC 1.0 profiles, both push (RFC 8935) and poll (RFC 8936) delivery, and is designed with a durable outbox so no events are lost across restarts. It targets the classic gap where a session doesn't get invalidated until the next token refresh.
AuthZEN Evaluation API (authzen): implements the PDP role from OpenID AuthZEN 1.0. Send it a subject/resource/action and it returns permit/deny using your existing Authorization Services policies. Both single and batch evaluation are supported.
Identity Assertion JWT Grant (identity-assertion-jwt): a partial implementation of the ID-JAG draft, which lets you obtain a token without re-authenticating when crossing auth servers between organizations. Only the receiving side is implemented right now, so the full flow doesn't work yet.
Token exchange delegation (token-exchange-delegation): for delegation scenarios where a gateway acts on a user's behalf downstream — delegation-parameterized scopes require user consent and are re-evaluated on every refresh. For background on token exchange, see RFC 8693 token exchange and delegation.
Admin API v2 (client-admin-api:v2): client management is the first resource in a new admin API built with strict validation and an accurate OpenAPI spec. The Operator uses it to declaratively manage clients via the KeycloakOIDCClient/KeycloakSAMLClient custom resources. It's the start of an answer to the long-standing complaint about the existing Admin REST API's loose validation and inaccurate spec.

The one thing promoted from preview to fully supported is step-up authentication for SAML clients — the authentication-context requirement that used to be OIDC-only is now open to SAML SPs as well.

So, When Do You Upgrade, and What Do You Turn On

Here's how I'd call it.

The upgrade itself is a minor release, and everything on the list above is manageable, so there's no reason to hold off. Before you go, though, put five or so things on a checklist: adding the X.509 CA Subject DN, the client secret length constraint, testing custom themes, deciding whether to opt out of async commit, and the self-registration flow change.
The SCIM preview is worth turning on in staging. If your organization has been writing provisioning scripts against the Admin REST API, this direction — standard protocol, the existing permission model, plus admin protection — is the right long-term call. Production dependency should wait until preview is promoted to supported, though, and design around the fact that Keycloak acting as the client (external SCIM federation, downstream push) doesn't exist yet.
Multi-cluster v2 is a real simplification if you're tired of running v1 (external Infinispan) and your organization can meet the single-region-plus-synchronously-replicated-DB bar. If geographic DR is a requirement, on the other hand, this feature isn't the answer — the sub-10ms DB latency requirement draws that line clearly. Factor the full-shutdown requirement for toggling it on and off into your planning too.
The three organization management roles aren't preview — they're the quiet, solid win of this release. If you've been handing tenant admins manage-realm, clawing that back right now and scoping them down to manage-organizations or narrower is the single most concrete security improvement available in this upgrade.

Closing

Looking only at the headline items (SCIM, multi-cluster v2), Keycloak 26.7 reads like a preview showcase, but the direction underneath is consistent — it absorbs gaps that third-party extensions and external infrastructure used to fill into core standard implementations (SCIM, SSF, AuthZEN), splits apart high-privilege roles (the organization management roles, removing view-system), and tightens up old looseness (X.509 CA DN, URI template validation, the SHA-1 retirement notice). For anyone self-hosting an IdP, it's a welcome direction, and the only price is a longer upgrade guide. Don't just skim the release notes — walking through the upgrade guide as a checklist once is worth the time.