Configuration Options

On this page different configuration options are listed you can use with Keycloakify.

--project

This option is for Monorepos. More specifically, monorepo system that works with a single package.json at the root of the project.

You can run every subcommand of the keycloakify CLI tool from the root of your Keycloakify project using the --project (or -p) option. Example with the build command:

npx keycloakify build -p <path>

<path> would be typically something like packages/keycloak-theme

keycloakVersionTargets

Targetting Specific Keycloak Versions

environmentVariables

Accessing Server Environment Variables

themeName

This is the name that will appear in the select input of the Keycloak Admin UI that let's you select the theme.

Here the theme name is "my-react-app"

By default it's package.json["name"]

Vite

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
      themeName: "my-custom-name"
    })
  ],
})

Webpack

package.json

{
    "keycloakify": {
        "themeName": "my-custom-name"
    }
}

The theme name is also in kcContext.themeName

Providing an array enables you to implement theme variant. See:

Theme Variants

themeVersion

In a Keycloak Docker Container

postBuild

Only available in Vite projects, not in Webpack

The postBuild hook is called just before Keycloakify bundles the themes resources into the jar.

This gives you the ability to implement some custom transformation.

Let's say, for example, we have a big material-icons in our public directory and those icons are used in the main app but not in the Keycloak theme. We can use the postBuild hook to make sure that those icons are not bundled in the generated jar files.

vite.config.ts

import * as fs from "fs/promises";
import * as path from "path";

export default defineConfig({
    plugins: [
        react(),
        keycloakify({
            postBuild: async (buildContext) => {
                await fs.rm(
                    path.join(
                        "theme",
                        buildContext.themeNames[0], // keycloakify-starter
                        "login", // Note: We assume we only have an login theme, if we had an account theme we would have to remove it there as well.
                        "resources",
                        "dist", // Your Vite dist/ or Webpack build/ is here.
                        "material-icons"
                    ),
                    { recursive: true }
                );
            }
        })
    ]
});

When this function is invoked the current working directory (process.cwd()) is the root of the directory of the files about to be archived.

You can get an idea of how is structured the files inside the jar by extracting it manually:

mkdir dist_keycloak/extracted
cd dist_keycloak/extracted
jar -xf ../keycloak-theme-for-kc-25-and-above.jar

Overview of the content of the jar extracted

Debugging

Note that the script is executed in a different thread. console.log() won't work. If you want to debug you can write your logs into a file.

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [
        react(),
        keycloakify({
            accountThemeImplementation: "Single-Page",
            postBuild: async (buildContext) => {

                const fs = await import("fs");
                const path = await import("path");

                const logFilePath = path.join(buildContext.projectDirPath, "postBuildLog.txt");

                fs.rmSync(logFilePath, { force: true });

                const log= (msg: string) => {
                    fs.appendFileSync(
                        logFilePath,
                        Buffer.from(msg + "\n", "utf8")
                    );
                };

                // This will be logged into postBuildLog.txt at the root of your project.
                log("Hello World");

            }
        })
    ]
});

XDG_CACHE_HOME

If this environnement variable is defined this cache directory will be used instead of the default node_modules/.cache/keycloakify example:

export XDG_CACHE_HOME=/home/runner/.cache/yarn
npx keycloakify build
# /home/runner/.cache/yarn/keycloakify will contain various resources

This option is mainly useful if you need to be able to build your theme offline, in a context with network restriction polices.

The Keycloakify caches the default Keycloak theme resources to avoid having to download them over and over.

kcContextExclusionsFtl

Keycloakify shifts page generation from the backend to the client. To achieve this, Keycloakify creates a global kcContext object, which holds the necessary information for generating HTML pages.

This object contains no sensitive data—only the information that the Keycloak team considers essential for rendering the various login pages. Additionally, if you have custom plugins, such as keycloak-email-whitelisting, they may introduce additional values into this object.

A typical kcContext for the register.ftl page

If you'd like to prevent some values of the FreeMarker context from being forwarded to the client you can do it with the kcContextExclusionsFtl option.

Let's say in this example that we would like to exclude:

• kcContext.keycloakifyVersion

• kcContext.realm.actionTokenGeneratedByUserLifespanMinutes in the register.ftl page

• kcContext.realm.idpVerifyAccountLinkActionTokenLifespanMinutes in the register.ftl page

This is how you would do it:

Vite

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [
        react(),
        keycloakify({
            // ...
            kcContextExclusionsFtl: `
                <#if (
                    key == "keycloakifyVersion" &&
                    areSamePath(path, []) 
                )>
                    <#continue>
                </#if>
                <#if (
                    xKeycloakify.pageId == "register.ftl" &&
                    [
                        "actionTokenGeneratedByUserLifespanMinutes", 
                        "idpVerifyAccountLinkActionTokenLifespanMinutes"
                    ]?seq_contains(key) &&
                    areSamePath(path, ["realm"]
                )>
                    <#continue>
                </#if>
            `
        })
    ]
});

You can also provide a path to a .ftl file instead of inlining the ftl code in your vite.config.ts file.

Webpack

kcContextExclusions.ftl

<#if (
    key == "keycloakifyVersion" &&
    areSamePath(path, []) 
)>
    <#continue>
</#if>
<#if (
    xKeycloakify.pageId == "register.ftl" &&
    [
        "actionTokenGeneratedByUserLifespanMinutes", 
        "idpVerifyAccountLinkActionTokenLifespanMinutes"
    ]?seq_contains(key) &&
    areSamePath(path, ["realm"]
)>
    <#continue>
</#if>

package.json

{
    "keycloakify": {
        // ...
        "kcContextExclusionsFtl": "./kcContextExclusions.ftl"
    }
}

The code that you provide will be injected here.

For more detailed example you can refer to this section of the code that defines the the default exclusions:

keycloakify/src/bin/keycloakify/generateFtl/kcContextDeclarationTemplate.ftl at 0879ddba7c3e12ea5ffd0cbefd97fa9b8cf63f7e · keycloakify/keycloakifyGitHub

More advanced modification of the kcContext

If you feel limited by this option you can take ownership of the FreeMarker template that generates the kcContext. Do do this using the wonderfull patch-package.

yarn add --dev patch-package

And edit the FreeMarker template that generates the KcContext in:

node_modules/keycloakify/src/bin/keycloakify/generateFtl/kcContextDeclarationTemplate.ftl

You can then create a diff for your changes by running:

npx patch-package keycloakify

Then add a postinstall script to your package.json:

package.json

{
    "name": "keycloakify-starter",
    "scripts": {
        "postinstall": "patch-package",
        "dev": "vite",

keycloakifyBuildDirPath

This option enables you to configure in which directory the .jar files should be created.

Vite

By default it's ./dist_keycloak

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
      keycloakifyBuildDirPath: "./keycloak-theme-dist"
    })
  ],
})

Webpack

By default it's ./build_keycloak

package.json

"keycloakify": {
    "keycloakifyBuildDirPath": "./keycloak-theme-jars"
}

groupId

Configure the groupId that will appear in the pom.xml file.

Vite

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
      groupId: "dev.keycloakify.demo-app-advanced.keycloak"
    })
  ],
})

Webpack

package.json

{
    "keycloakify": {
        "groupId": "dev.keycloakify.demo-app-advanced.keycloak"
    }
}

By default it's the package.json homepage field at reverse with .keycloak at the end.

You can overwrite this using an environment variable:

KEYCLOAKIFY_GROUP_ID="com.your-company.your-project.keycloak" npx keycloakify

artifactId

NOTE: For changing the name of the jar file that is generated by Keycloakify see this option instead: keycloakVersionTargets.

Configure the artifactId that will appear in the pom.xml file.

Vite

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
      artifactId: "keycloakify-advanced-starter-keycloak-theme"
    })
  ],
})

Webpack

package.json

{
    "keycloakify": {
        "artifactId": "keycloakify-advanced-starter-keycloak-theme"
    }
}

By default it's <themeName>-keycloak-theme See, keycloak.themeName option.

You can overwrite this using an environment variable:

KEYCLOAKIFY_ARTIFACT_ID="my-cool-theme" npx keycloakify build

Webpack specific options

In this sub folder are listed the few build options that are only relevant in Webpack project.

Be aware, theses are not preferences, they have to reflect your webpack configuration!

projectBuildDirPath

In the Create React App setup, when you run yarn build, a build/ directory is generated. If, in your setup it's an other directory you can use this option:a

package.json

"keycloakify": {
  "projectBuildDirPath": "a/b/c"
}

By default it's build.

staticDirPathInProjectBuildDirPath

In the Creact React App setup, when you run yarn build, a build/ directory is generated. I this directory there's a static directory/. If, in your setup it's an other directory you can use this option:

package.json

"keycloakify": {
    "staticDirPathInProjectBuildDirPath": "a/b/c"
}

By default it's static.

publicDirPath

To enable to test your theme locally, in storybook or with yarn start Keycloakify copies the default theme resources, primarily constituted of PatternFly, the CSS framework used for the default theme.

This option allows you to customize what's the public directory in your case. By default it's public/ but in angular for example it's src/assets/.

package.json

"keycloakify": {
  "publicDirPath": "./public"
}

By default it is ~/public

You can also use the PUBLIC_DIR_PATH environnement variable. Example:

npx PUBLIC_DIR_PATH=./src/assets keycloakify copy-keycloak-resources-to-public