[keycloak-user] Identity First authentication flow and trick for extension specific theme resources

[Thomas Darimont]

Hello Keycloak-Users,

I made some progress with a Google-like Identity First authentication flow
and found some interesting tricks that I wanted to share.

In my keycloak-extension-playground repository, I added an example
extension which supports a multi-step Identity first authentication
mechanism as Google and others provide.
See:
https://github.com/thomasdarimont/keycloak-extension-playground/tree/master/auth-identity-first-extension

The authentication flow works as follows:
Instead of asking for username AND password on the login screen I only ask
for the username. A password is then asked in a consecutive step.
This enables additional user-specific authentication steps.
You can find a short demo-gif in this tweet:
https://twitter.com/thomasdarimont/status/1146552622943559682

- The example features two authenticators 'SelectUserAuthenticatorForm' and
'PasswordAuthenticatorForm'.
  SelectUserAuthenticatorForm: Shows a form to enter the username (or
email) and provides a mechanism for resolving a user based on the given
username.
  PasswordAuthenticatorForm: Based on the selected user, a password form is
shown
- The forms are sent asynchronously via AJAX without reloading the login
page
- The authentication process can be aborted/restarted via by clicking
'cancel' on the password form

Now comes a nice trick, I learned while I was looking for a way to ship
custom extension specific js/css/img resources with an authenticator
without(!) having to customize a realm login theme.
As you might now, one can have authenticator/extension specific templates
that are shipped in the extension jar within the 'theme-resources/template'
folder.
This works fine if you can do everything in an .ftl template, but falls
short, when you need extension specific css/js/img.
However, if you also ship a CUSTOM extension specific theme within the
extension, then one can access resources provided by this theme!

In my case:
I created a theme folder with a login theme, named like the extension:
  extension: auth-identity-first-extension
  theme-name: auth-identity-first-extension-theme
The resulting folder structure looks like this:

auth-identity-first-extension/src/main/resources/theme/auth-identity-first-extension-theme/login/resources
The 'resources' folder contains sub-folders for 'js' and 'css' resources
combined with a META-INF/keycloak-themes.json descriptor.

See:
https://github.com/thomasdarimont/keycloak-extension-playground/tree/master/auth-identity-first-extension/src/main/resources/theme/auth-identity-first-extension-theme/login/resources

auth-identity-first-extension/src/main/resources/META-INF/keycloak-themes.json:
    { "themes": [
        {
        "name": "auth-identity-first-extension-theme",
        "types": [ "login"]
        }
    ]}


This allows to refer to the extension specific theme resources from within
a template, e.g. in the 'select-user-form.ftl' template this looks like:
        <link rel="stylesheet"
href="${url.resourcesPath}/../auth-identity-first-extension-theme/css/identity-first.css">
        <script
src="${url.resourcesPath}/../auth-identity-first-extension-theme/js/identity-first.js"
defer></script>

We effectively define a custom theme within the extension jar just for the
sake of exposing extension specific resources.
I know that this feels a bit like a hack (because it is), but seems to work
quite well ;-)

Note that the extension specific theme also shows up within the realm theme
selection, but you can ignore this.

I hope that's useful for you too :)

Cheers,
Thomas