Custom Themes with Keycloak 17

Extending the server
1

Hey,

i wanted to upgrade my local development Keycloak instance to version 17, but can’t get the custom themes to work when started in dev mode. I deploy my custom themes with docker-compose by mounting the theme via a volume into the container. This works flawlessly in version 16, but when using the new Quarkus edition the mounted theme directory is ignored. Does anyone have similar problems?

Thanks!

Update
Found the problem. I used the wrong path. The jboss image is using a different directory structure.

With the jboss image:

/opt/jboss/keycloak/themes/custom-theme/

With the official image from quay.io:

/opt/keycloak/themes/custom-theme/

2

There is a README file in this directory explaining the available options - I also struggled finding documentation about it:

Themes are used to configure the look and feel of login pages and the account management console.

Custom themes packaged in a JAR file should be deployed to the `${kc.home.dir}/providers` directory. After that, run
the `build` command to install them before starting the server.

You are also able to create your custom themes in this directory, directly. Themes within this directory do not require
the `build` command to be installed.

When running the server in development mode using `start-dev`, themes are not cached so that you can easily work on them without a need to restart
the server when making changes.

See the theme section in the [Server Developer Guide](https://www.keycloak.org/docs/latest/server_development/#_themes) for more details about how to create custom themes.

Overriding the built-in templates
---------------------------------

While creating custom themes, especially when overriding templates, it may be useful to use the built-in templates as
a reference. These can be found within the theme directory of `../lib/lib/main/org.keycloak.keycloak-themes-17.0.0.jar`, which can be opened using any
standard ZIP archive tool.
1 Like
3

You need to package it as a jar for the Quarkus/17 version.

See the README in /opt/keycloak/themes/README.md:

Custom themes packaged in a JAR file should be deployed to the ${kc.home.dir}/providers directory. After that, run
the build command to install them before starting the server.

This project will build a jar in the correct format, if you need to see how the packaged result it laid out. GitHub - p2-inc/keycloak-theme-template: Starter for building a Keycloak theme

4

There‘s no need to package a theme as a jar, I just use regular directory structures, like I did already with KC legacy, and it works flawelessly. Of course you have to use the proper path, but no need for a jar for custom themes.

2 Likes
5

Thanks. I just assumed from the new docs that it had to be a jar.

6

Unfortunately, I could not make it work. Here is what I tried:

In the folder ./themes/mytheme, there are the following files:

./META-INF/keycloak-themes.json
./theme/mytheme/login/theme.properties

With the content of the keycloa-themes.json file:

{
    "themes": [{
        "name" : "mytheme",
        "types": [ "login" ]
    }]
}

And the theme.properties content:

parent=base
import=common/keycloak
...

When I start the server, the new theme is not available for selection on the user interface.

» bin/kc.sh start-dev

Any hint is highly appreciated :slight_smile:, Thanks.

7

You can extend themes for different parts of Keycloak but assuming that you’re modifying login related content your theme content would go:

/opt/keycloak/themes/THEME_NAME/login

The THEME_NAME directory is empty except for the login subdirectory. Inside the login subdirectory, you’ll have something like:

-rw-r--r-- 1 keycloak 1000 1181 Apr 14 13:12 login.ftl
drwxr-xr-x 2 keycloak 1000    3 Apr  1 07:32 messages
drwxr-xr-x 6 keycloak 1000    6 Apr  1 07:32 resources
-rw-r--r-- 1 keycloak 1000 8045 Apr  1 10:23 template.ftl
-rw-r--r-- 1 keycloak 1000  661 Mar 31 14:23 theme.properties

The contents will depend on what you have chosen to override from the default Keycloak theme. Also make sure your theme directory is readable by Keycloak. For container deployments that means UID 1000 (which is the keycloak user inside the container)