Keycloak Upgrade 26.7.x to 26.8.x #55008

cgurtshaw · 2026-11-10T17:30:38Z

cgurtshaw
Nov 10, 2026

PR #52401 ("Multi-IdP for orgs: Data Model") moves org↔IdP linking from a single IDENTITY_PROVIDER.ORGANIZATION_ID column to a many-to-many ORG_IDENTITY_PROVIDER join table. The data migration (JpaUpdate26_8_0_DomainIdpRoutingMigration) is additive and looks correct, but the final changeset in the same file, 26.8.0-drop-idp-organization-id in model/jpa/src/main/resources/META-INF/jpa-changelog-26.8.0.xml, drops the column outright:

 <changeSet author="keycloak" id="26.8.0-drop-idp-organization-id">
     <dropIndex tableName="IDENTITY_PROVIDER" indexName="IDX_IDP_REALM_ORG"/>
     <dropIndex tableName="IDENTITY_PROVIDER" indexName="IDX_IDP_FOR_LOGIN"/>
     <dropColumn tableName="IDENTITY_PROVIDER" columnName="ORGANIZATION_ID"/>
     ...
 </changeSet>

The IdentityProviderEntity in 26.7.x maps that column as a plain eager @Column field, so Hibernate includes it in the generated SELECT for every IdentityProviderEntity load. As a result, the instant a 26.8.0+ node runs this migration against a DB that any 26.7.x node is still connected to, every identity-provider read on that 26.7.x node starts failing, including normal (non-org) brokered logins.

Reproduction
Minimal repro, no custom extensions involved:

Start Keycloak 26.7.2 against a fresh Postgres DB, create a plain OIDC identity provider.
Start Keycloak 26.8.1 against the same DB (no restart of the 26.7.2 node). Startup logs show the migration running (Migrating older model to 26.8.0).
On the still-running 26.7.2 node, trigger a real login via kc_idp_hint= (after the realm cache naturally reloads/evicts — e.g. via POST /admin/realms/{realm}/clear-realm-cache, simulating normal cache turnover). The login fails with the built-in error page ("Unexpected error when handling authentication request to identity provider"), and the server log shows:

org.keycloak.models.ModelException: Database operation failed
Caused by: org.postgresql.util.PSQLException: ERROR: column ipe1_0.organization_id does not exist at org.keycloak.models.jpa.JpaIdentityProviderStorageProvider.getEntityById(JpaIdentityProviderStorageProvider.java:518)

This means any deployment that does a linear/rolling traffic shift, or any form of blue-green cutover where old and new versions can briefly share the same database, has a hard outage window the moment the new version's migration runs — with no way to roll the application back out of it (the schema change isn't undone by reverting app versions).

Questions

Was this intentional? i.e., is a full offline/maintenance-window cutover the expected and only supported path across the 26.7.x → 26.8.x boundary, with in-place/rolling upgrades explicitly unsupported for this release?
If not intentional: would the project consider an expand/contract split for migrations like this going forward? i.e., land the additive schema changes and data migration in one release, and defer the actual dropColumn/dropIndex to a later release once no supported upgrade path can run the two versions concurrently? In this specific case it looks like the fix would have been as simple as moving the 26.8.0-drop-idp-organization-id changeset into the next version's changelog, since 26.8.0's own entity mapping already stops reading that column.
Is there existing guidance (anywhere in CONTRIBUTING.md or the upgrade guide) for contributors on how destructive schema changes to core, frequently-read tables should be sequenced across releases? If not, would a written guideline here be welcome, to help reviewers catch this class of issue earlier?

Navigation Menu

Repository navigation

Keycloak Upgrade 26.7.x to 26.8.x #55008

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Keycloak Upgrade 26.7.x to 26.8.x #55008

Uh oh!

cgurtshaw Nov 10, 2026

Replies: 0 comments

cgurtshaw
Nov 10, 2026