Keycloak Quarkus: The New Era of Identity and Access Management
The world of identity and access management is constantly evolving, and staying ahead of the curve is essential for ensuring the security of your applications and infrastructure. Keycloak has long been a trusted and widely used open-source solution for securing applications and services, but the introduction of Keycloak Quarkus brings about a new era in this space. This blog post will explore the transition from WildFly to Quarkus, discuss the benefits of the Keycloak Quarkus distribution, and provide guidance on migrating to this new platform.
The Transition from WildFly to Quarkus
A Brief Overview of Keycloak and WildFly
Keycloak is an open-source Identity and Access Management (IAM) solution that provides a comprehensive set of features to secure applications and services. It handles user authentication, single sign-on, authorization, and user management, among other essential tasks. WildFly, formerly known as JBoss AS, has been the application server powering Keycloak for years. However, as the technology landscape evolves, the need for a more efficient, flexible, and lightweight solution has become apparent.
The Rise of Quarkus in Keycloak 17
Quarkus, a Kubernetes-native Java framework designed for building lightweight, high-performance applications, has emerged as the ideal platform for the next generation of Keycloak. With Keycloak 17, Quarkus has become the default distribution, and the legacy WildFly distribution has been deprecated. Quarkus offers numerous advantages over WildFly, such as faster startup times, improved performance, and seamless integration with Kubernetes and OpenShift.
Deprecating WildFly: Timeline and Considerations
While the WildFly-powered distribution will remain available until June 2022, it is highly recommended to begin migrating to the Quarkus distribution as soon as possible. This transition is essential to take advantage of the new features and improvements introduced with Keycloak Quarkus. However, it is crucial to be aware that the migration process involves a number of breaking changes and requires a thorough understanding of the new distribution’s configuration and deployment process.
Benefits of Keycloak Quarkus Distribution
Faster Startup Times and Improved Performance
One of the most notable benefits of the Keycloak Quarkus distribution is its significantly faster startup times compared to the WildFly distribution. This is due to Quarkus’s ability to optimize the runtime through a process known as augmentation. The result is an immutable container that can be launched more quickly, improving the overall performance and responsiveness of your Keycloak instance.
Simplified Configuration and Management
The Keycloak Quarkus distribution introduces a streamlined configuration process that replaces the complex XML files used in the WildFly distribution. The new configuration approach utilizes a simple file, CLI arguments, and environment variables, making it much easier to configure and manage your Keycloak instance. However, this change means that automatic migration of configurations from the previous distribution is not possible, requiring manual configuration adjustments during the migration process.
Enhanced Kubernetes and OpenShift Integration
Quarkus is designed with Kubernetes and OpenShift in mind, and as a result, the Keycloak Quarkus distribution offers improved integration with these platforms. This is achieved through the introduction of a new operator and Custom Resource Definitions (CRDs) specifically designed for Kubernetes and OpenShift. Migrating to the Quarkus distribution will enable you to leverage these features and simplify the deployment and management of Keycloak on these platforms.
Migrating to Keycloak Quarkus Distribution
Preparing for the Migration
Before starting the migration process, it is essential to familiarize yourself with the new Server Guides that detail how to install and configure the Keycloak Quarkus distribution. Understanding the differences between the WildFly and Quarkus distributions will help you make informed decisions and avoid potential issues during the migration process.
Migrating Configuration
The first step in migrating to the Keycloak Quarkus distribution is to identify the configuration changes you have made in your WildFly distribution and apply them to the new Quarkus distribution. Be aware that the Quarkus distribution is more opinionated when it comes to configuration, aiming to provide better defaults and reduce the need for manual adjustments. However, if you encounter configuration limitations, you can raise a discussion on GitHub Discussions or, as a last resort, directly modify the conf/quarkus.properties file.
Adapting to the Quarkus Framework
Unlike WildFly, which is an application server, Quarkus is a framework for building applications. This fundamental difference means that features such as hot deployment and runtime configuration changes are no longer supported in the Quarkus distribution. Instead, Quarkus offers a separate build step to optimize the runtime, which should be incorporated into your Keycloak installation process, either through continuous integration (CI) or by creating a custom container image based on the base Keycloak image.
Changes in Keycloak Quarkus Distribution
The Keycloak Quarkus distribution no longer includes the add-user-keycloak.sh script to create initial users. Instead, you can set the KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD environment variables to create an initial admin user upon first startup. To create additional users, you can use the kcadm.sh (Linux) or kcadm.bat (Windows) command line tool.
Default Context Path Modification
The default context path has changed in the Keycloak Quarkus distribution, with the /auth portion removed. If you wish to retain the /auth context path, you can use the http-relative-path build option, like so:
Migrating Custom Providers
Migrating custom providers in the Keycloak Quarkus distribution involves copying them to the providers directory instead of the standalone/deployments directory used in the WildFly distribution. Keep in mind that there is no separate classpath for custom providers in the Quarkus distribution, so you may need to exercise caution when including additional dependencies.
The Quarkus distribution does not support automatic discovery or hot-deployment of custom providers. As a result, you will need to perform a build or restart the server with the auto-build feature after modifying providers or dependencies in the providers directory. Furthermore, if your custom providers use APIs from WildFly or JavaEE, you may need to make additional changes to ensure compatibility with the Quarkus distribution.
Transitioning to the Keycloak Quarkus Operator for Kubernetes and OpenShift
Understanding the New Operator and CRDs
To deploy the Keycloak Quarkus distribution on Kubernetes and OpenShift, you must use the new Keycloak Operator designed specifically for the Quarkus distribution. The old Operator does not support the new distribution, and a direct migration path is not available. Instead, you’ll create a new Custom Resource (CR) to establish a new Keycloak deployment based on the Quarkus distribution.
Coexistence of Old and New Operators
Both the old and new Operators can coexist within the same namespace since they utilize different API Groups and Versions in their Custom Resource Definitions (CRDs). The apiVersion for the old Operator is keycloak.org/v1alpha1, while the new Operator uses k8s.keycloak.org/v2alpha1. When using kubectl commands with both CRDs installed in the cluster, ensure you use fully qualified names, including the API Group. For example:
Realm Import in the New Operator
The new Keycloak Quarkus Operator no longer directly supports Client, User, and Realm CRDs. Instead, it provides a single CRD for performing a Realm import. By using this new CR, you can import Users, Clients, and other elements through the encompassing Realm.
Tips for a Successful Migration to Keycloak Quarkus
Plan Your Migration
Take the time to plan your migration thoroughly. Familiarize yourself with the new Keycloak Quarkus distribution, its configuration options, and the differences between the WildFly and Quarkus distributions. Create a detailed migration plan to avoid potential issues during the transition process.
Test Your Migration in a Staging Environment
Before migrating your production environment, test the migration process in a staging environment. This will help you identify and address any issues before they impact your production setup. Testing in a staging environment also allows you to refine your migration plan and ensure a smoother transition to the Keycloak Quarkus distribution.
Ensure Custom Provider Compatibility
Review your custom providers to ensure compatibility with the Keycloak Quarkus distribution. Make any necessary modifications to your custom providers to account for changes in APIs and the removal of JavaEE support. Testing your custom providers in a staging environment will help ensure a seamless migration to the new distribution.
Seek Assistance if Necessary
If you encounter difficulties or have questions during the migration process, don’t hesitate to seek assistance from the Keycloak community. Engage in discussions on GitHub or consult the Keycloak documentation to find solutions to common migration challenges.
Embracing the Benefits of Keycloak Quarkus
Improved Performance and Resource Efficiency
With the migration to the Keycloak Quarkus distribution, you’ll experience improved performance and resource efficiency, thanks to Quarkus’ optimizations. Faster startup times and a reduced memory footprint are among the key benefits of this transition.
Simplified Configuration Management
The new Keycloak Quarkus distribution introduces a simpler configuration file, making it easier to manage and customize your Keycloak instance. This streamlined approach replaces the complicated XML files and CLI tools associated with the WildFly distribution, resulting in a more user-friendly configuration experience.
Greater Flexibility and Scalability
Keycloak Quarkus offers greater flexibility and scalability, as it is designed to work seamlessly with containerized environments and cloud-native architectures. This makes it an ideal choice for modern applications that require agile deployment and scaling capabilities.
A Future-Proof Identity and Access Management Solution
By migrating to the Keycloak Quarkus distribution, you’re ensuring that your identity and access management solution remains up-to-date with the latest advancements and best practices. This future-proofing helps to maintain the security and reliability of your authentication and authorization systems.
Conclusion
The migration from Keycloak WildFly to the Keycloak Quarkus distribution represents a significant change in the way you configure, deploy, and manage your Keycloak instance. While this transition may require some adaptation and effort, the benefits of improved performance, simplified configuration, and enhanced flexibility make it a worthwhile investment.
By following the migration steps and best practices outlined in this blog post, you can ensure a smooth and successful transition to the Keycloak Quarkus distribution. With the right planning, testing, and support from the Keycloak community, you can embrace the advantages of this powerful and efficient identity and access management solution.
