Upgrade Keycloak from 8 to 24: A Complete Guide!

Imagine managing an identity management system with 25,000 users, with 3 social logins, an LDAP directory, and 500 application clients. Now, add some more complexity with a custom Service Provider Interface (SPI) and a custom login & signup pages. Then, you get asked to smoothly upgrade Keycloak from version 8 to version 24, leveraging latest features, enhanced security, and improved performance? Is it possible? Let’s find out.

Upgrading Keycloak isn’t just about staying current—it’s about making sure you get the latest advancements to optimize your identity and access management (IAM) framework.

Each version of Keycloak introduces critical enhancements, security patches, and new functionalities that can improve how you manage user authentication and authorization.

Furthermore, support for new standards are added in later versions. Not upgrading leaves you open to potential security risks.

In this series, we’ll walk you through each step of the migration journey, ensuring you understand the impact on every facet of your system—from user experience to backend performance.

In this first blog post, we’ll lay the groundwork for our migration journey from Keycloak version 8 to 24. We’ll outline the methodology, perform load testing before and after each migration, and closely track the status of all dependencies. By meticulously documenting each step, you’ll gain a comprehensive blueprint for upgrading your own Keycloak setup.

I will document the scripts used for the migration work in github.

Setting the Stage

To ensure a thorough and systematic migration process, our methodology includes:

Initial Setup

  • Users: 25,000 active users
  • Integrations:
    • 3 social logins (e.g., Google, Facebook, Twitter)
    • 1 LDAP directory to simulate enterprise users
  • Clients: 500 applications relying on Keycloak for authentication
  • Customizations:
    • 1 custom SPI
    • 1 custom theme for login and signup


  • Client Application: Represents a mobile app or a website requiring user authentication.
  • Backend Applications:
    • Application 1: Handles sensitive data and has restricted resources.
    • Application 2: Manages user profiles and preferences, also with restricted resources.

Load Testing

We’ll conduct load testing before and after each migration to measure performance changes among the golden metrics:

  • Load Testing Tools: Gatling
  • Metrics:
    • Response time
    • Throughput
    • Error rate
    • Resource utilization (CPU, memory)

Migration Steps

For each migration step, we’ll:

  • Document the migration process.
  • Upgrade Keycloak to the next version.
  • Track changes and impacts on:
    • User experience
    • Social logins
    • LDAP integration
    • Custom SPI functionality
    • Custom themes
    • Client and backend applications
  • Perform load testing.

Tracking Dependencies

We’ll meticulously monitor the impact of each migration on all dependencies, ensuring that:

  • Social Logins: Continue to work seamlessly with updated protocols and endpoints.
  • LDAP Integration: Still able to use the protocol without any error.
  • Custom SPI: Maintains functionality without breaking changes.
  • Custom Themes: Render correctly without any styling issues and allows the users to signup and login.
  • Client and Backend Applications: Maintain their authentication and authorization flows without interruption.

Starting the Journey

In this first migration step, we’ll upgrade from Keycloak version 8 to version 9. This initial step will set the foundation for the entire migration journey. We’ll begin by:

  1. Preparing the Environment: Backup current configurations and databases, set up a staging environment mirroring production.
  2. Upgrading to Version 9: Follow Keycloak’s official upgrade documentation.
  3. Testing: Run comprehensive tests to ensure everything is working as expected.
  4. Documenting: Record any issues encountered and how they were resolved.

Stay tuned for the detailed step-by-step process in our next post, where we’ll upgrade Keycloak from 8 to 9, sharing insights, challenges, and successes along the way.

You can follow the work on github HERE.

Leave a Comment