Skip to main content

Keycloak23 Migration

caution

  • Database Backward Compatibility is not supported on downgrading Keycloak from higher to lower version. Before upgrading Keycloak, make sure you have a database backup.

  • IDP 5.x.x exclusively supports only AST-based features and does not support SSMS. Therefore, all custom IDP features related to SSMS have been removed.

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 compatibility of token exchange functionality 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 successful migration of identity user changes in SCP and MPay services for IDP 5 or higher versions.

  • Keycloak, by default does not support rolling updates during major version upgrades. To deploy a version 5.x.x, the pods need to be scaled down to 0, the image should be updated, and then the replicas can be scaled back up one by one.

  • A new environment variable AST_SCOPE_CLIENTS has been introduced to automate the addition of the scope ast containing the AST Token mapper to all the clients mentioned in this variable when a new tenant is created. (Eg: AST_SCOPE_CLIENTS= ClientID1, ClientID2). Clients that require AST Claims to be part of the IDP token (AST Client Id and MLoA based ACR and AMR in the token and Response data in Token Endpoint) require this scope.

Breaking Changes​

  • As part of our API standardization efforts, we have updated the URL structures, Request formats, and Response body formats for several APIs. These changes also involve the deprecation of SSMS-based features and the removal of customizations from the core Keycloak image, impacting the Keycloak Admin APIs. To ensure compatibility with the latest specifications, please refer to the updated API documentation available at the IDP Services API and Keycloak Open source APIs link.

  • restrictTokenExchange realm setting has been removed. To ensure proper token exchange, set token exchange policies between source and target clients, and disable full scope allowed in the target client and assign specific roles. Customers using token exchange with restrictTokenExchange set to false (default) must now establish these policies for correct functionality.

  • As the number of tenants in an environment increases, time taken for tenant migration from IDP 4 to 5 significantly increases resulting in transaction timeout issue. The Quarkus transaction timeout is set to 1 hour currently
    (-Dquarkus.transaction-manager-default-transaction-timeout=3600). For environments with huge number of tenants, the transaction timeout should be increased by adding -Dquarkus.transaction-manager.default-transaction-timeout=<value_in_seconds>. Additionally, the kubernetes pod startup probe should be without these adjustments, pods may be killed and restarted repeatedly during the migration process. Benchmarking shows that migrating 10 tenants takes an average of 5 minutes and 60 tenants takes an average of 30 minutes.

Core Highlights​

  • Upgraded Keycloak 19.0.3 to Keycloak 23.0.4.

  • OTP BruteForce functionality has been renamed to Resend OTP BruteForce.

  • Server Info page can be accessed only in Master realm and has been enhanced to display both IDP-Core and Custom IDP versions.

  • A new theme Kobil-admin has been introduced to accommodate custom tabs in the Admin UI and added support to set it as the default admin theme for all realms.

  • All custom features, such as Settings, Resend OTP BruteForce, SMS, Schedulers, Risk Bits, and Claims, are now conveniently integrated under the KOBIL tab for seamless access.

    Kc23

  • Authenticators

    • QR and TMS authenticators have been upgraded to KOBIL QR V2 and KOBIL AST TMS V2, introducing enhanced performance through IDP-Socket instead of long polling. Additionally, option to select a device to send TMS has been added to Kobil V3 theme of Kobil TMS V2 authenticator.

Features Removed​

  • Schedulers exclusively compatible with SSMS, including the Connector Events Scheduler, Dead User Event Scheduler, and Dead Event Cleaner Scheduler, have been removed.

  • Partial import json cannot be directly used in realm import.

  • Support tool has been removed.

  • JWT Bearer grant type is not currently supported in this version. (Will be introduced in the upcoming version).

  • Custom Event types are no longer supported in IDP 5.X.X.

  • Kobil Client Policy used for user validation based on specific conditions, has been removed.

  • Key Providers such as AWS KMS, IBM KeyProtect, and IBM HSM has been removed .

  • Following authenticators have been removed, as they exclusively support SSMS.

    • Account - KOBIL Change Email
    • Account - KOBIL Change Password
    • Account - KOBIL Change Phone
    • Account - KOBIL Change Username
    • Account - KOBIL Manage Devices

  • kobil, kobil-ast, and kobilv2 themes have been removed in Account and Admin themes.

  • Support for Retarus email provider has been removed.

  • Support for copy-features and share-features functionalities which allows the sub-realms to copy/share certain settings from the master realm has been removed.