Compatibility with future keycloak version and security considerations #346
Replies: 3 comments 1 reply
-
Hi @jnachtigall, Thank you for reaching out! Your questions are perfectly valid, and I am happy to provide more insight.
This isn't entirely clear. @lordvlad has been consistently contributing for some time now. Additionally, @willwill96 has shown to be quite involved in the project and demonstrates an in-depth understanding.
Even if I were to stop maintaining Keycloakify (which I don't plan on doing), it's highly unlikely that Keycloak would release a new version that breaks Keycloakify themes. This would mean that they would break every other theme, whether Keycloakify-based or not. However, this is merely speculation. What I can say for certain is that I'm firmly committed to maintaining and growing Keycloakify for the foreseeable future.
Yes, this part of the documentation is outdated and can be misleading. We ensure that Keycloakify generates themes compatible with the latest Keycloak version. We use Keycloakify as a side project of Onyxia Datalab and always maintain up-to-date Keycloak versions. If anything goes wrong after upgrading Keycloak, we'll be among the first to know. In fact, Keycloakify consists of two things:
The Keycloakify community and I are very prompt in reacting to security vulnerabilities. It happened once, and we had a patch released before Keycloak did. To be fully honest, the vulnerability was on the Keycloak side, but it wasn't exploitable with the default theme. If there is a theme-related security patch on the Keycloak side, we'll be sure to apply it to Keycloakify swiftly.
They certainly are! Thank you for your valuable feedback. I'll make sure to update the documentation accordingly. |
Beta Was this translation helpful? Give feedback.
-
Hi @garronej, thanks for the answer. Much appreciated. I hope things can better explained in the documentation so it easier to understand.
Good point. Related to this is another point that made it hard for me to estimate the afford needed to keep a keycloakify based theme up to date (if in case the keycloakify upstream projects would go unmaintained): How does a Keycloakify/React based theme work technically under the hood? That is, how does the communication work between Keycloakify server and the Theme? I looked into the files (mainly So a chapter like "How does Keycloakify work technically?" (or maybe rather "How does the generated React theme work with regards to Keycloak backend server?") in the documentation would really have helped me. FWIW, I did not use the CSS only theming approach while evaluating but rather my own React components (which are based on MUI but that's different for each project). That is, the using https://github.com/keycloakify/keycloakify-starter/ version 3 (it was some weeks ago) |
Beta Was this translation helpful? Give feedback.
-
Let me clarify how Keycloak and JavaScript communicate in a more comprehensive manner: FreeMarker (.ftl) is a templating language, similar to PHP. Keycloak processes the template whenever a request is made. For instance, here, you can see a global Keycloakify moves the page generation from the backend to the frontend, making the FTL context available to JavaScript. A simple way to achieve this is shown in the keycloak-theme-vuejs project, where all known FTL variables are manually listed page by page and transformed into a global JavaScript object. The core Keycloak theme also implements this strategy for their latest React-based theme. However, this approach requires a lot of manual work and is tightly coupled to a specific Keycloak version. If Keycloak introduces a new variable, it won't be visible unless manually added. Additionally, custom Keycloak plugins adding custom variables may cause issues, and if a variable is removed, the template may crash. Keycloakify takes a more generic approach by using a generic FTL function that converts FTL objects into JSON format. It passes the Here, you can see some context-specific code. This is to avoid log pollution when errors occur, even when using Regarding functions, specific handling is necessary since we cannot invoke functions without knowing their required parameters ahead of time. However, the only functions present are well-known ones like Keycloak also implements strategies for bundling assets and ensuring they are served and resolved correctly within Keycloak. While you don't need to understand the precise workings to make a decision, you can refer to @willwill96's video for some insights: https://youtu.be/x3ux2JM1Bxk To answer your question about whether Keycloakify relies on a stable API or internal Keycloak functions: Keycloakify doesn't depend on any Keycloak API (for the login theme see update). Instead, it translates the FTL context into a JavaScript object (kcContext), making minimal assumptions about the FTL context. This explanation should help clarify things and reassure you that Keycloakify is relatively future-proof regarding upcoming Keycloak updates, even if maintenance were to cease. June 2024 update: Regarding the account theme, the account team decided to use React and implemented something entirely different from the login theme with account v2 and v3. This system isn't extendable, meaning that if you want to customize the account theme, you'll need to copy their entire project and modify it manually. Moreover, you'll have to learn something completely new since the knowledge gained from the login theme doesn't apply here. Due to these complications, we chose to stick with account-v1, even though it was removed from Keycloak. This decision allows for a more convenient experience, maintaining consistent principles for both login and account themes. To achieve this, we submitted a pull request to Keycloak (thanks to @xgp), which was merged. This PR enabled us to take ownership of the Java code for the account theme. Keycloakify now bundles the account-v1 within the JAR file: Keycloak Account v1. Currently, the account-v1 is exactly as it was when removed from Keycloak in version 19. However, we plan to update it to mirror the current account theme's look. I haven't had time to do this yet, but it's on our agenda. Additionally, you are correct that we should add more mount points. This is also why we need to build multiple JARs for different Keycloak versions. Since the account theme relies on internal Keycloak APIs that can change at any time, we need to update the Java code accordingly. We can add support for new Keycloak versions as needed. To handle this, use the keycloakVersionTargets build option. This way, if a new range is added, you'll receive a helpful type error notification. For more information, visit: Targeting Specific Keycloak Versions. |
Beta Was this translation helpful? Give feedback.
-
The selling points of Keycloakify are pretty obvious - especially if one uses React anyway for the frontend - and well explained on https://www.keycloakify.dev/
While evaluation theming solutions for Keycloak I came across a few issues. Some these issues might be considered downsides/cons. Maybe those point could be clarified in the documentation or website. I hope I can give some feedback here.
1. Support for future keycloak version?
Obviously Keycloakify has more or less one maintainer. What happens if keycloakify gets unmaintained while Keycloak keeps releasing new versions. How much work would it be to keep my keycloakify based theme then?
Also https://docs.keycloakify.dev/readme-1#see-versions-keycloakify-have-been-tested-with says
Version 11 is pretty old. I always try to use the most recent version which is 21.1.1 So this gives the impression as if Keycloakify would be based on a pretty old Keycloak version?
I am not sure if the documentation is misleading here and could be improved and clarified (that my main reason for opening this issue/discussion).
2. Security considerations
Related to this the question might be raised what happens if there is, for instance a (security) hot fix release, for the official Keycloak theme. If I base my work on the official Keycloak Theming then will it be "more secure" than using Keycloakify (which is based on Keycloak v11 and would be lots of work in case it becomes unmaintained.)
I hope my points are well received. I am honestly not sure if they are really valid. Maybe the documentation could be improved regarding maintenance work, future compatibility or security considerations regarding keycloakify based themes?
Beta Was this translation helpful? Give feedback.
All reactions