how-to-use.md

😄 👨💻 Quick start

{% hint style="success" %} It's a good idea to first read this quick start section to understand the basic of how Keycloakify works.

However, we recommend you start hacking from the demo setup instead of setting up Keycloakify from scratch. {% endhint %}

{% hint style="warning" %} Save yourself some time, have quick look at the requirements page. (Windows users in particular) {% endhint %}

yarn add keycloakify @emotion/react

package.json

"scripts": {
    "keycloak": "yarn build && build-keycloak-theme",
}

yarn keycloak # generates the keycloak-theme.jar

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

{% tabs %} {% tab title="CSS Only customization" %} The first approach is to only customize the style of the default Keycloak login theme by providing your own class names.

{% hint style="info" %} 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). {% endhint %}

src/index.tsx

import { KcApp, defaultKcProps, getKcContext } from "keycloakify";
//We assume the file contains: ".my-class { color: red; }"
import "./index.css";

const { kcContext } = getKcContext();

if( kcContex === undefined ){
    throw new Error(
        "This app is a Keycloak theme" +
        "It isn't meant to be deployed outside of Keycloak"
    );
}

reactDom.render(
    <KcApp
        kcContext={kcContext}
        {...{
            ...defaultKcProps,
            "kcHeaderWrapperClass": "my-class",
        }}
    />,
    document.getElementById("root"),
);

The above snippet of code assumes you are in a react project wich only purpose is to be a Keycloak theme.

But if you want to make your keycloak theme an integral part of a preexisting React app you would apply the following modification to the above snipet:

+import { App } from "<you know where";
 import { KcApp, defaultKcProps, getKcContext } from "keycloakify";
 import "./index.css";

 const { kcContext } = getKcContext();

-if( kcContex === undefined ){
-    throw new Error(
-        "This app is a Keycloak theme" +
-        "It isn't meant to be deployed outside of Keycloak"
-    );
-}

 reactDom.render(
+    kcContext === undefined ?
+        <App /> :
         <KcApp
             kcContext={kcContext}
             {...{
                 ...defaultKcProps,
                 "kcHeaderWrapperClass": myClassName,
             }}
         />,
     document.getElementById("root"),
);

Real world example

To give you an idea of what you can already achieve by only customizing the style the style,

Here is the code that produces:

{% endtab %}

{% tab title="Component level customization" %} If you want to go beyond only customizing the CSS you can re-implement some of the pages or even add new ones.

If you want to go this way checkout the demo setup provided here. If you prefer a real life example you can checkout onyxia-web's source. The web app is in production here.

Main takeaways are:

• You must declare your custom pages in the package.json. example
• (TS only) You must declare theses page in the type argument of the getter function for the kcContext in order to have the correct typings. example
• (TS only) If you use Keycloak plugins that defines non standard .ftl values (Like for example this plugin that define authorizedMailDomains in register.ftl) you should declare theses value to get the type. example
• You should provide sample data for all the non standard value if you want to be able to debug the page outside of keycloak. example {% endtab %} {% endtabs %}