User Profile is a Keycloak feature that enables to define, from the admin console, what information you want to collect on your users in the register page and to validate inputs on the frontend, in realtime!

NOTE: User profile is only available in Keycloak 15 and it's a beta feature that needs to be enabled when launching keycloak and enabled in the console.

Keycloakify, in register-user-profile.ftl, provides frontend validation out of the box.

For implementing your own register-user-profile.ftl page, you can use import { useFormValidationSlice } from "keycloakify";. Find usage example here.

As for right now it's not possible to define a pattern for the password from the admin console. You can however pass validators for it to the useFormValidationSlice function.

Seeing the result live

When building your page you want to see the result of your edit live.

To acheave that with Keycloakify simply eddit:

 import { getKcContext } from "keycloakify";

 const { kcContext } = getKcContext({
+    "mockPageId": "login.ftl"
 });

See the getKcContext() call in the keycloakify-demo-app project.

See the getKcContext() call in the keycloakify-demo-app#look_and_feel project.

then if you run yarn start you will see your login page display. Dont forget to remove mockPageId before releasing 😉.

Testing in a real Keycloak instance

Once you are done developping you want to test in an actual Keycloak instance to see if everything is working as expected.

Please refer to the related instruction printed on the console when running yarn keycloak in your project.

Introduced in v4.8.0

It is now possible to customize the emails sent to your users to confirm their email address ect. Just run npx create-keycloak-email-directory, it will create a keycloak_email directory at the root of your project. This directory should be tracked by Git (yarn add -A) You can start hacking the default template. When npx build-keycloak-theme (yarn keycloak) is run, if the directory keycloak_email exists at the root of your project, it will be bundled into your .jar file and you will be able to select it in the Keycloak administration pages.

On the console will be printed all the instructions about how to load the generated theme in Keycloak

How to import the theme in Keycloak

Specific instruction on how to proceed will be printed in the console with yarn keycloak.

In Keycloakify you can't directly eddit the messages_xx.properties files, the way to go it to reproduce ( don't forget to ).

Some pages still have the default theme. Why?

This project only support out of the box the most common user facing pages of Keycloak login.

To see the complete list of pages that Keycloak provide you can download the base theme with the following command

npx -p keycloakify download-builtin-keycloak-theme

Most Keycloakify component are based on the base theme of Keycloak v11.0.3 ().

are the pages currently implemented by this module.

I have established that a page that I need isn't supported out of the box by Keycloakify, now what?

process.env.PUBLIC_URL not supported.

You won't be able to . (This isn't recommended anyway).

@font-face importing fonts from the src/ dir

If you are building the theme with this limitation doesn't apply, you can import fonts however you see fit.

Example of setup that won't work

• We have a fonts/ directory in src/

• We import the font like this in a .scss a file.

Possible workarounds

• If it is possible, use Google Fonts or any other font provider.

login and email only

As of now Keycloakify only enable you to create a theme that covers the Login pages and the emails. Acount and Admin Console aren't supported yet.

Many organizations have a requirement that when a new user logs in for the first time, they need to agree to the terms and conditions of the website.

First you need to enable the required action on the Keycloak server admin console:

By default when your users reach the login pages all scripts, images and stylesheet are downloaded from the Keycloak server. If you are specifically building a theme to integrate with an app or a website that allows users to browse unauthenticated before logging in, you will get a significant performance boost if you jump through those hoops:

• Provide the url of your app in the homepage field of package.json. or in a public/CNAME file. .

• Build the theme using npx build-keycloak-theme --external-assets

• Enable on the server hosting your app. .

• Make sure not to build your app and the keycloak theme separately (run yarn keycloak only once in your CI) and remember to update the Keycloak theme every time you update your app.

• Be mindful that if your app is down your login pages are down as well.

Checkout a complete setup

Supported Keycloak version

Supported React frameworks

Utility that needs to be installed

• mvn (Maven), rm, mkdir, curl, unzip.

• docker must be up and running when running start_keycloak_testing_container.sh

If you ever encounter one of these errors:

FTL stack trace ("~" means nesting-related):
        - Failed at: #local value = object[key]  [in template "login.ftl" in macro "ftl_object_to_js_code_declaring_an_object" at line 70, column 21]
        - Reached through: @compress  [in template "login.ftl" in macro "ftl_object_to_js_code_declaring_an_object" at line 36, column 5]
        - Reached through: @ftl_object_to_js_code_declaring_an_object object=value depth=(dep...  [in template "login.ftl" in macro "ftl_object_to_js_code_declaring_an_object" at line 81, column 27]
        - Reached through: @compress  [in template "login.ftl" in macro "ftl_object_to_js_code_declaring_an_object" at line 36, column 5]
        - Reached through: @ftl_object_to_js_code_declaring_an_object object=(.data_model) de...  [in template "login.ftl" at line 163, column 43]

It's just noise, they can be safely ignored. You can, however, and are encouraged to, report any that you would spot. Just open an issue about it and I will release a patched version of Keycloakify in the better delays.

If, before logging in, a user has selected a specific language you don't want it to be reset to default when the user gets redirected to the login or register pages.

Same goes for the dark mode, you don't want, if the user had it enabled to show the login page with light themes.

The problem is that you are probably using localStorage to persist theses values across reload but, as the Keycloak pages are not served on the same domain that the rest of your app you won't be able to carry over states using localStorage.

The only reliable solution is to inject parameters into the URL before redirecting to Keycloak. We integrate with keycloak-js, by providing you a way to tell keycloak-js that you would like to inject some search parameters before redirecting.

The method also works with @react-keycloak/web (use the initOptions).

You can implement your own mechanism to pass the states in the URL and restore it on the other side but we recommend using powerhooks/useGlobalState from the library powerhooks that provide an elegant way to handle states such as isDarkModeEnabled.

Let's modify the example from the official keycloak-js documentation to enables the relevant states of our app to be injected in the URL before redirecting.

Let's say we have a boolean state isDarkModeEnabled that define if the dark theme should be enabled.

useIsDarkModeEnabled.ts

import { createUseGlobalState } from "powerhooks/useGlobalState";

export const { useIsDarkModeEnabled, $isDarkModeEnabled } = createUseGlobalState({
	"name": "isDarkModeEnabled",
  //If we don't have a previous state stored in local storage nor an URL query param
  //that explicitly set the state, we initialize using the browser preferred color scheme.
	"initialState": ()=> (
		window.matchMedia &&
		window.matchMedia("(prefers-color-scheme: dark)").matches
	),
  //Do use localStorage to persist across reloads.
	"doPersistAcrossReloads": true
});

Now let's see how we would use this state in our react app.

MyComponent.tsx

import { useIsDarkModeEnabled } from "./useIsDarkModeEnabled";

export function MyComponent(){

  const { isDarkModeEnabled, setIsDarkModeEnabled }= useIsDarkModeEnabled();

  return (
    <div>
      <p>The dark mode is currently: {isDarkModeEnabled?"enabled":"disabled"}</p>
      <button onClick={()=> setIsDarkModeEnabled(!isDarkModeEnabled)}>
        Click to toggle dark mode
      <button>
    </dvi>
  );

}

We can also update the state and track it's updates outside of react:

import { $isDarkModeEnabled } from "./useIsDarkModeEnabled";

//After 4 seconds, enable dark mode
setTimeout(
  ()=>{
      //This triggers re-renders of all the components that uses the state.
      //(the assignation has side effect)
      $isDarkModeEnabled.current = true;

  },
  4000
);

//Print something in the console anytime the state changes:  

$isDarkModeEnabled.subscribe(isDarkModeEnabled=> {
  console.log(`idDarkModeEnabled changed, new value: ${isDarkModeEnabled}`);
});

Now let's see how we would carry our isDarkModeEnabled to our login theme.

import keycloak_js from "keycloak-js";
import { injectGlobalStatesInSearchParams } from "powerhooks/useGlobalState";
import { createKeycloakAdapter } from "keycloakify";
import { addParamToUrl } from "powerhooks/tools/urlSearchParams";

//...

const keycloakInstance = keycloak_js({
    "url": "http://keycloak-server/auth",
    "realm": "myrealm",
    "clientId": "myapp",
});

keycloakInstance.init({
    "onLoad": "check-sso",
    "silentCheckSsoRedirectUri": window.location.origin + "/silent-check-sso.html",
    "adapter": createKeycloakAdapter({
        "transformUrlBeforeRedirect": url=>
            [url]
                //This will append &ui_locales=fr at on the login page url we are about to 
                //redirect to. 
                //This will tell keycloak that the login should be in french. 
                //Replace "fr" by any KcLanguageTag you have enabled on your Keycloak server.
                .map(url => addParamToUrl({ url, "name": "ui_locales", "value": "fr" }).newUrl)
                //This will make sure our isDarkModeEnabled and other global states
                //created with powerhooks/useGlobalState are restored on the other side. 
                .map(injectGlobalStatesInSearchParams)
                [0],
        keycloakInstance,
    }),
});

//...

If you really want to go the extra miles and avoid having the white flash of the blank html before the js bundle have been evaluated here is a snippet that you can place in your public/index.html if you are using powerhooks/useGlobalState.

Adding support for a new page

Here is an example of a good PR that adds support for a page.

If you need to edit the i18n resources it should be done here (and not in the src/lib/i18n/generated_kcMessages dir).

The keycloakify components are a plain React translation of the default theme that comes with Keycloak v11.0.3.

You can download the FTL/CSS source files the components are based on with the following command:

npx -p keycloakify download-builtin-keycloak-theme

then select version 11.0.3 (Video demo).

Testing your changes in the demo app (or in your project)

Let's assume you have made some change to the keycloakify codebase and you want to test those changes before submitting a PR.

Assuming you have cloned keycloakify in ~/github/keycloakify this is how you would proceed.

cd ~/github # Navigate to the dir where you have the keycloakify project
git clone https://github.com/garronej/keycloakify-demo-app
cd keycloakify
yarn 
yarn build
yarn link_in_test_app
npx tsc -w #This will start the compilation of Keycloakify in watch mode
           #You will be able to perform changes on the keycloakify code
           #and see them apply live in the keycloakify-demo-app

Open a new terminal window

cd ~/github
cd keycloakify-demo-app
yarn start

Now you are able to test your local version of Keycloakify in the test app and make sure everything works as expected.

Heads over the development instruction if you are not already familiar with the process of testing your Keycloakify themes: