Skip to main content

Keycloak24 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.

  • If the KOBIL AST Header to Session authenticator is included in any authentication flow, it triggers an AST verification call, which may cause blockers in subsequent authenticators within the flow.

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.

  • Migration to IDP-5.1.0 cannot be done as a rolling update as it comes with a major update of underlying Keycloak, which does not support such. 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.

  • Ensure to switch off Display client on screen when creating a client for a miniapp from Smart-Dashboard. If enabled, the client name will be visible on the console screen.

note

For those migrating from KC19 to KC23, please follow the necessary migration steps. Refer to the previous migration document for more detailed information: keycloak23 migration documentation

Core Highlights​

  • Keycloak has been upgraded from version 23.0.4 to 24.0.5.

  • Introduced an Import Localization tab under Kobil Settings. Users can select a language from the default list supported by Keycloak, import a localization JSON file, and verify it in the Localization tab.

  • Added support to prevent the removal of root user attributes (e.g: username, email, first name, last name) when updating user attributes via the Update user API, even if not all attributes are provided. Also, read-only attributes cannot be modified via the Kobil Extensions API.

  • The status field in the response body for the DELETE USER FROM GROUP API has been updated. Previously, it returned Success, but it is now correctly updated to return OK for successful executions. The updated response body is mentioned below

    • Endpoint: /realms/{tenantId}/v3_user/{userId}/group
    • Method: DELETE
    • Response Body:

      • Status code: 200

          {

          "message": "User group removed successfully",

          "status": "OK",

          "subSystem": 5

          }

  • Renamed authenticators from BDDK to KSSIDP:

    • KOBIL - BDDK Register Password → KOBIL - KSSIDP Register Password
    • KOBIL - BDDK Change Password → KOBIL - KSSIDP Change Password
    • KOBIL - BDDK Forgot Password → KOBIL - KSSIDP Forgot Password

  • **keycloak-metrics-spi**library is integrated as a project dependency and will be retrieved from KOBIL Nexus.

Removed and Deprecated features`​

  • Deprecated the KOBIL Login authenticator in version 5.1.0, which provided 1FA authentication with the Kobilv2 theme and SSMS support. Since multiple 1FA authenticators are available in the IDP for username/password authentication, this authenticator is no longer necessary.

  • Deprecated the KOBIL Create SSMS User, Account - KOBIL Manage Devices, KOBIL mTAN Confirmation authenticators in version 5.1.0.

  • Removed the unused authenticator configuration for Display User Identity Attribute set to First and Last Name from the KOBIL Change Email authenticator.

  • Removed all the legacy cloud connector code and SSMS-based authenticators from previous versions.

  • Removed the kobil-module-dependencies strategy to simplify version management. All transitive dependencies are assembled into the outermost JARs for services and extensions.