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

Taking full control of how the KcContext is generated

If you feel limited by this option you can take ownership of the FreeMarker template that generates the kcContext. Let's see how it can be done through an example. Some values, like for example the realm attributes (kcContext.realm.attributes) are explicitely excluded from the KcContext.

In the following video we explore how to include them back.

Note that in the video we includes all the realm attributes. We might want to expose only a specific set of values. For this we could do:

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

-    ) || (
-        key == "attributes" &&
-        areSamePath(path, ["realm"])
-    ) || (
+    ) || (
+        areSamePath(path, ["realm", "attributes"]) &&
+        !["myFirstAttribute", "mySecondAttribute"]?seq_contains(key)
+    ) || (

We could also chose to include only the realm attributes with a specific prefix, for example theme_:

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

-    ) || (
-        key == "attributes" &&
-        areSamePath(path, ["realm"])
-    ) || (
+    ) || (
+        areSamePath(path, ["realm", "attributes"]) &&
+        !key?starts_with("theme_")
+    ) || (

Setting up patch-package

As explained in the video:

Add patch-package add dev dependency

yarn add --dev patch-package

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",
    ...
}

Commit the patch/ directory that have been created by patch-package.