Removal of Account console v1 breaks Keycloakify

[Joseph Garrone]

Dear Keycloak Development Team,

I hope this message finds you well. My name is Joseph Garrone, and I am writing to you as the lead developer of Keycloakify, a project that assists in creating Keycloak themes.

Keycloakify is currently sustained by regular contributions from CloudIAM and was generously supported by a previous donation from Corsair. Our tool has been well-received by its users, and while I lack concrete data to support this, I believe Keycloakify may play an important role in the Keycloak community's theme creation.

The recent removal of the Account console v1, while well-communicated in advance, presents significant challenges to Keycloakify users. Previously, our tool offered a streamlined experience for developing account themes based on v1. With its removal, it's no longer possible to create account theme with Keycloakify.

In the past, Keycloakify users have enjoyed a quick setup through our starter project, real-time theme modifications using Storybook (example), and the ability to create a test Keycloak container via a simple command. The culmination of this process was the generation of a .jar file that could be easily integrated into their Keycloak servers.

While we acknowledge that it was on us to anticipate this change, the removal of Account console v1 has left many teams unable to upgrade to Keycloak 22.

We initially selected Account console v1 due to the coherent development experience it offered for creating both login and account themes. With v2, this experience seems to differ significantly.

Understanding that this is a big ask, I am reaching out to inquire whether a temporary reintroduction of Account console v1 would be possible. This would provide us with much-needed time to develop an alternative solution.

Ideally, if Account console v1 could be retained without active maintenance except the provision of needed FTL context, it would enable us to continue supporting our users.

Keycloakify is the result of significant collective engineering effort, and we hope to maintain its relevance within the community, even extending it to work with Vue, Angular and Svelt. We understand the challenges involved and sincerely appreciate your consideration.

For further information on how Keycloakify operates, I invite you to refer to this discussion.

Thank you for taking the time to consider our request. We greatly appreciate your ongoing work on Keycloak, and look forward to your response.

Warm Regards,

--
Joseph Garrone

https://github.com/garronej

[Garth]

+1 for Keycloakify. We have many customers that use it for their login and account themes.

@garrone Is it not possible to change Keycloakify to build a standalone theme with the "old" v1 account theme code and package the whole thing as a new theme? Or is there some other part that is missing (e.g. the Java code that prepared the pages). I haven't looked into it too much, so feel free to tell me you've already looked into this.

On Wed, Aug 2, 2023, at 7:58 AM, Joseph Garrone wrote:
> Dear Keycloak Development Team,
>
> I hope this message finds you well. My name is Joseph Garrone, and I am
> writing to you as the lead developer of Keycloakify

> <https://keycloakify.dev/>, a project that assists in creating Keycloak

> themes.
>
> Keycloakify is currently sustained by regular contributions from

> CloudIAM <https://www.cloud-iam.com/> and was generously supported by a
> previous donation from Corsair <https://www.corsair.com/fr/fr>. Our

> tool has been well-received by its users, and while I lack concrete
> data to support this, I believe Keycloakify may play an important role
> in the Keycloak community's theme creation.
>
> The recent removal of the Account console v1, while well-communicated
> in advance, presents significant challenges to Keycloakify users.
> Previously, our tool offered a streamlined experience for developing
> account themes based on v1. With its removal, it's no longer possible
> to create account theme with Keycloakify.
>
> In the past, Keycloakify users have enjoyed a quick setup through our

> starter project <https://github.com/keycloakify/keycloakify-starter>,

> real-time theme modifications using Storybook (example

> <https://storybook.keycloakify.dev/?path=/story/account-account-ftl--default>),

> and the ability to create a test Keycloak container via a simple

> command <https://youtu.be/WMyGZNHQkjU?t=200>. The culmination of this

> process was the generation of a .jar file that could be easily
> integrated into their Keycloak servers.
>
> While we acknowledge that it was on us to anticipate this change, the
> removal of Account console v1 has left many teams unable to upgrade to
> Keycloak 22.
>
> We initially selected Account console v1 due to the coherent
> development experience it offered for creating both login and account
> themes. With v2, this experience seems to differ significantly.
>
> Understanding that this is a big ask, I am reaching out to inquire
> whether a temporary reintroduction of Account console v1 would be
> possible. This would provide us with much-needed time to develop an
> alternative solution.
>
> Ideally, if Account console v1 could be retained without active
> maintenance except the provision of needed FTL context, it would enable
> us to continue supporting our users.
>
> Keycloakify is the result of significant collective engineering effort,
> and we hope to maintain its relevance within the community, even
> extending it to work with Vue, Angular and Svelt. We understand the
> challenges involved and sincerely appreciate your consideration.
>
> For further information on how Keycloakify operates, I invite you to
> refer to this discussion

> <https://github.com/keycloakify/keycloakify/discussions/346#discussioncomment-5889791>.

>
> Thank you for taking the time to consider our request. We greatly
> appreciate your ongoing work on Keycloak, and look forward to your
> response.
>
> Warm Regards,
>
> --
> Joseph Garrone
> https://github.com/garronej
>

> --
> You received this message because you are subscribed to the Google
> Groups "Keycloak Dev" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to keycloak-dev...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/keycloak-dev/ab86239f-6645-458b-af81-9a6855fad28an%40googlegroups.com
> <https://groups.google.com/d/msgid/keycloak-dev/ab86239f-6645-458b-af81-9a6855fad28an%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Joseph Garrone]

Hello Garh,  

Thank you very much for taking the time to atttest to the usage of Keycloakify.  

> Or is there some other part that is missing (e.g. the Java code that prepared the pages).  

Yes, this unfortunately. 😢  

Best regards,  

[Garth]

Too bad.

For some of my extensions, I have bundled REST extensions with themes. You’d have to make changes to the endpoint paths, and you would be responsible for maintaining it, but I think it is possible to include the “old” code.

> https://groups.google.com/d/msgid/keycloak-dev/7600ec93-bbe7-46c8-bf6c-f98f77bf678dn%40googlegroups.com
> <https://groups.google.com/d/msgid/keycloak-dev/7600ec93-bbe7-46c8-bf6c-f98f77bf678dn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Joseph Garrone]

> For some of my extensions, I have bundled REST extensions with themes.  

I'm unclear on what you're conveying here; could you provide more details?

Your statement sparked an interesting thought. Would it be feasible to distribute the Java code of the Account Console v1 as a Keycloak plugin? This plugin could potentially be included within the JAR produced by Keycloakify. Does this concept sound reasonable, or is it flawed?

I would greatly appreciate hearing the Keycloak team's perspective on this matter, as well as their overall opinion of Keycloakify.

[Garth]

Yes, that's the idea.

For example, in this extension (https://github.com/p2-inc/phasetwo-admin-portal) I create a theme and a `RealmResourceProvider` implementation together in one JAR. As long as the resource is in your `META-INF/services/org.keycloak.services.resource.RealmResourceProviderFactory` file, it will also get loaded as an extensions.

> https://groups.google.com/d/msgid/keycloak-dev/e6d8699c-7195-426b-abf1-62c7d841e34dn%40googlegroups.com
> <https://groups.google.com/d/msgid/keycloak-dev/e6d8699c-7195-426b-abf1-62c7d841e34dn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Garth]

A quick look at the diffs indicate that it's not the java that changed, but the absence of the old "base" and "keycloak" account themes that you are using as the base in your theme.properties. Might be sufficient to just pull those in (if you were actually extending them).

> https://groups.google.com/d/msgid/keycloak-dev/c5b2c45d-68c5-4281-9070-ad034bdac87e%40app.fastmail.com.

[Stan Silvert]

We could probably restore the base theme for the account console if that helps.  It only consists of ftl files and properties files.

Let me know if that will help and I'll see if there are any objects to putting that back into the build.  This would be only for the account console.  Not for the admin console.

To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/37953bb2-969c-4227-b925-bd480550c571%40app.fastmail.com.

[Garth]

I went over the code more, and it looks like it's the whole `FreeMarkerAccountProvider` also (and all the dependent classes), so a big thing to pull back in. I'm going to see if it's possible to create an extension that brings back what they need.

>> >> an email to keycloak-dev...@googlegroups.com <mailto:keycloak-dev%2Bunsu...@googlegroups.com>.

>> >> To view this discussion on the web visit
>> >> https://groups.google.com/d/msgid/keycloak-dev/e6d8699c-7195-426b-abf1-62c7d841e34dn%40googlegroups.com
>> >> <https://groups.google.com/d/msgid/keycloak-dev/e6d8699c-7195-426b-abf1-62c7d841e34dn%40googlegroups.com?utm_medium=email&utm_source=footer>.
>> >
>> > --
>> > You received this message because you are subscribed to the Google
>> > Groups "Keycloak Dev" group.
>> > To unsubscribe from this group and stop receiving emails from it, send

>> > an email to keycloak-dev...@googlegroups.com <mailto:keycloak-dev%2Bunsu...@googlegroups.com>.

>> > To view this discussion on the web visit
>> > https://groups.google.com/d/msgid/keycloak-dev/c5b2c45d-68c5-4281-9070-ad034bdac87e%40app.fastmail.com.
>>
>> --
>> You received this message because you are subscribed to the Google Groups "Keycloak Dev" group.

>> To unsubscribe from this group and stop receiving emails from it, send an email to keycloak-dev...@googlegroups.com <mailto:keycloak-dev%2Bunsu...@googlegroups.com>.

[Garth]

Hi Stan,

Thank you for the willingness to look at this. I've spent some time talking this over with Joseph, and I think there is a good solution.

We built a prototype of what would be required to build the v1 account console as an extension. A working example is available here: https://github.com/xgp/keycloak-account-v1

Everything works *except* allowing it to be served on the `/account` path. Because the [AccountLoader](https://github.com/keycloak/keycloak/blob/21.1.2/services/src/main/java/org/keycloak/services/resources/account/AccountLoader.java#L85C1-L91C1) code removed the mechanism of loading a different JAX-RS resource depending on account theme, there is no longer a way to serve it from the same path. However, it's really just that one point that is preventing the extension from being served as an alternate account console. Furthermore, this provides a good extension point that could allow great flexibility in how extension authors built their own account themes.

I suggest the following changes to maintain support for alternate approaches to the account console:

1. Create a new `Spi` that provides an `AccountResourceProvider`.
2. The `AccountResourceProvider` would be a simple interface with two methods:
```
public interface AccountResourceProvider extends Provider {
  /** Return true if this should be used with the given theme. */
  boolean useWithTheme(Theme theme);

  /** Returns a JAX-RS resource instance. */
  Object getResource();
}
```
3. Update the `AccountLoader` code to check if the provider should be used with the `Theme`:
```
...
        Theme theme = getTheme(session);
        UriInfo uriInfo = session.getContext().getUri();
        AccountResourceProvider accountResourceProvider = session.getProvider(AccountResourceProvider.class); //new

        if (request.getHttpMethod().equals(HttpMethod.OPTIONS)) {
            return new CorsPreflightService(request);
        } else if ((accepts.contains(MediaType.APPLICATION_JSON_TYPE) || MediaType.APPLICATION_JSON_TYPE.equals(content)) && !uriInfo.getPath().endsWith("keycloak.json")) {
            return getAccountRestService(client, null);
        } else if (accountResourceProvider != null && accountResourceProvider.useWithTheme(theme)) { //new
            return accountResourceProvider.getResource(); //new
        } else if (Profile.isFeatureEnabled(Profile.Feature.ACCOUNT2) || Profile.isFeatureEnabled(Profile.Feature.ACCOUNT3)) {
            AccountConsole console = new AccountConsole(session, client, theme);
            console.init();
            return console;
        } else {
            throw new NotFoundException();
        }
...
```

Let me know if this sounds good, and I'll take care of the changes and PR.

There are a lot of people using Keycloakify for a consistent development experience between login and account themes. This is a great example of a community extension that has met a real need and provided growth to the ecosystem.

Thanks for considering this.

[Stan Silvert]

Looks good to me.  I would support a PR for this.

Please create an enhancement issue and reference this discussion.  

Then create a PR with a simple test and reference the issue as per our contribution guidelines.  See https://github.com/keycloak/keycloak/blob/main/CONTRIBUTING.md

To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/39d3bf10-6fac-41d6-8b3c-5830b04d4f73n%40googlegroups.com.

[Stan Silvert]

On Thu, Aug 3, 2023 at 2:51 PM Stan Silvert <ssil...@redhat.com> wrote:

Looks good to me.  I would support a PR for this.

Please create an enhancement issue and reference this discussion.  

Then create a PR with a simple test and reference the issue as per our contribution guidelines.  See https://github.com/keycloak/keycloak/blob/main/CONTRIBUTING.md

On second thought, maybe a quickstart would be better than a test.  I think either is sufficient.  

https://github.com/keycloak/keycloak-quickstarts

[Garth]

Perfect. I'll submit it in the next few days. Thanks again.

>> To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/39d3bf10-6fac-41d6-8b3c-5830b04d4f73n%40googlegroups.com <https://groups.google.com/d/msgid/keycloak-dev/39d3bf10-6fac-41d6-8b3c-5830b04d4f73n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Joseph Garrone]

Fantastic! Thanks a lot @Garth and @Stan!