Skip to main content

Keycloak26 Migration

Pre-requisites​

  • In version 5.X.X, IDP continues to support PostgreSQL and Oracle databases while phasing out support for MS SQL and MySQL.

  • The following versions of Dart Wrapper are required for token exchange functionality compatibility in IDP5:

    • Master Controller: 162.1.0 or later
    • MC Dart Wrapper: 72.2.0 or later
    • MC iOS Wrapper: 166.2.0 or later
    • MC Android Wrapper: 159.2.0 or later

  • The SCP Connector version should be 1.8.0 or later to ensure the successful migration of identity user changes in SCP and MPay services for IDP version 5 or higher.

  • Migration to IDP-5.3.0 cannot be done as a rolling update as it comes with a major update of the underlying Keycloak, which does not support such.

    • To deploy a version 5.x.x:
      • Scale down pods to 0
      • Update the image
      • Scale replicas back up one by one

  • Please follow the required migration steps for those migrating from KC24 to KC26.

    • Refer to the previous migration details here: Keycloak24 Migration

Breaking Changes​

  • Metrics and health endpoints are now exposed only through a default management port 9000.

    • Any configuration, monitoring, or probe using the main Keycloak port must be updated
    • Health/metrics access through the standard server port is no longer supported

  • The default password hashing algorithm has been changed in the upgraded Keycloak base.

    • Credentials hashed with the new version may not be compatible with older versions
    • Rollback to a previous Keycloak version is unsafe

Core Highlights​

  • Keycloak has been upgraded from version 24.0.5 to 26.4.7

  • Introduced the Unlink All Devices feature into the Core IDP standard image:

    • Ensures a 1-to-1 device-to-user relationship
    • When a new device is activated, all previously linked devices are automatically unlinked

  • Introduced a multitenant theme provider:

    • Loads themes per realm
    • Supports uploading, updating, and deleting custom themes through a new KOBIL Theme API
    • Themes are stored in the database
    • Synchronized across pods through cluster events
    • Restored to the filesystem on startup for consistent multi-tenant branding

  • Introduced enhanced audit-event processing with Kafka event publishing for:

    • Activation failures
    • Successful logins
    • Login/link failures
    • Invalid password attempts
    • OTP failures
    • Along with RiskBits events enabling audit-event–based monitoring and forming the foundation for Grafana dashboards powered by Elasticsearch data

  • Introduced Infinispan cache–driven Server-Sent Events (SSE) for QR and TMS flows:

    • Replacing socket communication
    • Removing the IDP Async Helper module

  • Introduced a new /sse/qrTms/subscribe/{trxId} endpoint:

    • Implemented server-side SSE logic to validate transactions
    • Manage live connections with TTL and heartbeat
    • Stream Infinispan cache–driven status updates to connected clients

  • Introduced a third Outbox table with 24-hour rotation:

    • Distributing events across daily tables
    • Reducing read/write contention
    • Minimizing index bloat
    • Improving overall processing performance

Configuration Notes​

  • In newer versions, the sub claim in token is provided via the basic client scope.
    • When using partial import flows:
      • Ensure that the basic client scope is configured as a default client scope for the relevant clients
      • Ensures that the sub claim is included in access tokens

Removed​

  • The qr/{sessionId}/callback endpoint is no longer deprecated and has been reintroduced as an internal endpoint:
    • internal/qr/{sessionId}/callback
    • Used to support SSE-based QR and TMS flows