Info about custom pages

[giovannilondero]

Hi,

I read the docs and discussions, but I couldn't find information about custom pages. I apologise if there already is something and I missed it.

I get that extra pages are to customize Keycloak pages that are not supported by default in Keycloakify, but what about custom pages?
How can we add them with Keycloakify? Should we follow a specific structure? How to link them (both internal and external)?

Not an expert in Keykloakify or Keycloak at all.

Context: I need to add a page that explains how to remove account / user data, and I would like to use KC because the app is native and I don't have another server in place.

I think it would be enough to get a few lines about this topic in docs, like "create a file here like this, link it like that, then do whatever you want like any other react app"

Thanks

[garronej]

Hello @giovannilondero,

As long as the Keycloak server is not involved and you're juste displaying content you're free to implement this with React as you would do in any application.

Keep in mind that a Keycloakify theme is a React app after all.

You can very well do a button to swap the content on click or open a modal.

[garronej]

I believe you grasp the main concept, but there seems to be some confusion regarding where the actual processing occurs.

When Keycloak renders the .ftl templates, its only role is to declare the script that will initialize the window.kcContext; beyond that, all operations are conducted on the frontend.

Developing a Keycloak extension to add the page you mentioned might not be the best approach. This would necessitate writing Java code for server-side routing, etc., and packaging this Java code into your theme's .jar file. Moreover, you would still need to develop the client-side page using Keycloakify.

Creating a client-side page would be significantly easier. There would be no discernible difference for the user, and implementation would be straightforward. Considering it's a React app, manipulating the DOM is what react is about. Simply render what you wish to display, eliminating the need for server involvement. Maybe what would help would be to think of your Keycloak theme as an SPA rather than templated html.

[giovannilondero]

Sorry if I'm being pedantic, but I want to make sure I'll choose the best solution for my problem. And thank you for your time.

I don't intend to develop a Keycloak extension, but I also can't see how a SPA could easily solve my problem.
Ok, I could even link to the login (or any other EXISTING page) with a specific param and then redirect on frontend to a specific page and do whatever I want there, but still, it's just frontend and looks really bad to me.

For example I cannot link to, say, https://domain/auth/realms/myrealm/some-custom-path?ui_locales=en&redirect_uri=my_redirectt&client_id=my_client because it's not present on KC and wouldn't be served, but I should link to https://domain/auth/realms/myrealm/protocol/openid-connect/auth?ui_locales=en&redirect_uri=my_redirectt&client_id=my_client&SOMEPARAMS=true and then manage it all on frontend

[giovannilondero]

I can find other people with concerns:

• https://keycloak.discourse.group/t/after-creating-the-extra-pages-ftl-on-keycloakify-advance-starter-kit-how-do-i-navigate-to-them/18334
• https://www.reddit.com/r/KeyCloak/comments/11nrju4/adding_a_custom_public_page_ftl_or_html_to/ (where you answered but didn't provide a proper solution Keycloakify)

I guess this same issue will emerge from time to time because it's not really clear.

Maybe it doesn't help to see we can add a MyExtraPage1 whose content is whatever we want, but it's not clear how to create those pages and how to link to them.

---

I would even write down docs for this, but I'm feeling so dumb like I'm missing something obvious to understand it 100%

[garronej]

Here are some clarifications that may reshape your understanding:

• It appears you're under the impression that you can directly navigate users to a specific Keycloak page. However, this isn't possible. What you can actually do is append a custom query parameter to your requests.
• The concept of "pages" should be reconsidered. In reality, every page delivers the same Single Page Application (SPA), constructed entirely on the client side. Thus, the differentiation between pages is an illusion.
• The existence of my-extra-page.ftl might seem misleading. This feature isn't designed to facilitate the implementation of custom content, as it's expected you're capable of doing that independently. Rather, it's intended for specialized scenarios, such as if your organization utilizes a unique biometric sensor and has developed an additional authentication step through a custom Java plugin. In such instances, you would need to create a theme for a page that doesn't exist in the standard Keycloak framework. That's where my-extra-page.ftl comes into play, catering to very specific use cases. It's also useful for adding support for built-in pages not yet covered by Keycloakify, a function that was particularly valuable a few months back but has since seen diminished necessity as most pages are now supported.

To achieve what you're aiming for, refer to this snippet:
https://github.com/keycloakify/keycloakify-starter/blob/4529ae8727489b8cdd6197ac512041ced14a4c62/src/App/App.tsx#L51-L54
If you wish to display your "custom page," you would execute:

login({ extraQueryParams: { my_custom_param: "explain-how-to-remove-account" } })

Next, capture the parameter on the receiving end and utilize it to present the desired content:
https://github.com/keycloakify/keycloakify-starter/blob/4529ae8727489b8cdd6197ac512041ced14a4c62/src/keycloak-theme/login/pages/Login.tsx#L9-L13

I regret that there isn't a more straightforward solution, but this limitation stems from the nature of OIDC.

[giovannilondero]

Ohh I see. It's way clearer now, I had to hear that it isn't possible to navigate users to a specific page and that OIDC has specific limitations. I appreciate the examples too.

Thank you @garronej !