Themes ​

The whole authentication and registration experience along with the email sent can be customized in Keycloak through a custom extension. Examples are available on official keycloak source base or on our github.

Getting started, the easy way ​

Theme builder ​

As a Cloud-IAM customer with an active paid subscription, you have access to our Custom Theme Builder, a simple and convenient way to personalize the default Keycloak login theme to reflect your organization's branding.

While full customization capabilities are not yet available, the Theme Builder offers a range of useful options that allow you to:

• Change the background style, image, color, gradients, ...
• Add your company logo and a favicon
• Customize accent and secondary colors
• Modify the shape of buttons

These options are typically sufficient for basic branding needs, helping you create a login page that aligns visually with your company’s identity.

Please note that the Theme Builder is not intended for advanced or highly customized use cases. However, for most organizations, it provides a quick and effective way to enhance the look and feel of the login experience with minimal effort.

Using the theme builder ​

In the Cloud-IAM Console, you can access the Custom Theme Generator from the Customization section within your deployment menu.

Since Keycloak supports theming on a per-realm basis, Cloud-IAM enables you to create and manage multiple themes, allowing you to tailor the login experience for each realm individually.

Custom Theme Generator ​

The Custom Theme Generator provides a WYSIWYG editor that allows you to preview and customize your theme.

Features ​

• Preview multiple pages
• Toggle between light and dark mode
• Adjust settings to match your organization’s identity
  • Configure the accent colors
  • Control the background appearance
    • Set a background color
    • Set a background image
    • Set a custom CSS background property to achieve effects such as gradients
  • Upload resources for the brand logo and favicon
  • Adjust the shapes of elements

Once you're ready ​

1. Save your changes.
2. Click Deploy to install your latest changes on the deployment. A restart is triggered, but services remain available during the process.

Configuring the theme in Keycloak ​

After restarting the deployment:

1. Open the Keycloak Admin Console.
2. Go to Realm Settings → Themes tab.
3. In the Login Theme dropdown, select the theme you created using the Theme Generator.
4. Click Save.

Your custom theme is now applied to your realm. Make sure the theme appears as expected in the login interface.

Getting started, the advanced way ​

In case you need more customization, split the login screen into multiple steps, add more text, review the workflow, ... our theme builder will not be enough.

In this case, you will need to extend the default Keycloak theme.

You can either rely on the Keycloakify project that offer an advanced customization through React. Follow the instructions, generate your custom theme jar file, and simply upload it on your deployment.

For even more advanced needs, write your own theme from scratch and write Freemarker. At Cloud-IAM, we maintain a custom theme for our needs, and we have open-sourced it.

A good start could be to clone this theme and use it as a basis.

• 👥 First clone this example repository
• Then edit the names in ./pom.xml to match your company (these lines)
• Rename the directory cloud-iam-redesign in src/main/resources/theme/ with the same name you will put line 3 in src/main/resources/META-INF/keycloak-themes.json (this line)
• put inside src/main/resources/theme/{YOUR_DIRECTORY_NAME}/login your theme files — or update the files to match your theme —. Be sure to check that you have a themes.properties file (like this one) in src/main/resources/theme/{YOUR_DIRECTORY_NAME}/login/theme.properties
• ⏩ run ./build.sh command in the root folder (same folder as pom.xml). If you don't have maven installed, please check this tutorial.
• last step 🥁🥁 take the .jar file from ./target folder and upload it on your Cloud-IAM keycloak deployment thanks to the "Upload .jar file" button based on Cloud-IAM custom extension support.

Your Keycloak cluster will be automatically redeployed without downtime to enable your theme.

Connect to your Keycloak console to activate your login theme to the realms of your choice.

Getting started with Cloud-IAM ​

If you do not wish to do it yourself, or need more assistance, please check our consulting services.

Troubleshooting ​

Theme is not listed in Keycloak ​

Double-check the packaging of your extension. Make sure the jar hierarchy looks like themes/my-company/login, themes/<my-theme>/email.

Ensure also that the file META-INF/keycloak-themes.json is present and contains the appropirated values:

{
    "themes": [
        {
            "name": "my-company",
            "types": [
                "email",
                "login"
            ]
        }
    ]
}

{
    "themes": [
        {
            "name": "my-company",
            "types": [
                "email",
                "login"
            ]
        }
    ]
}

I have redeployed my theme but I cannot see the latest changes ​

Cloud-IAM do not add any additional cache layer and your changes should be reflected.

Most of the time, this issue occurs because the theme is deployed multiple times on the Keycloak server. If multiple jars contain a file META-INF/keycloak-themes.json referencing the same theme name, Keycloak will probably not show your latest version because it will load only one jar file and ignore the others. Unfortunately, this is not deterministic in Keycloak.

To prevent this kind of issue, you should either

• REPLACE the theme in version N-1 with the new version by using the Replace button in the console or the PUT API
• add a version in your theme name. In this case, remember that the theme name must be reflected in your package that must contain a directory themes/my-company-1.2/login

Theme resources are cached for 30 days in user's browsers how to handle it? ​

Cloud-IAM follows best web-performance practices. When rolling out a custom Keycloak theme leveraging cache burst with your favorite web bundler (e.g. webpack or parceljs that does it out of the box) is the best way to handle cache invalidation and keep great web performance through asset caching.

Local testing for faster feedback ​

Even if the developer experience is one of our concern, the most efficient way to develop a custom extension remain to work locally.

During the development phase which is often highly iterative, Cloud-IAM recommend using a local version of Keycloak by using for instance a docker container:

docker run --rm -v $HOME/projects/acme/extensions/keycloak-theme/target/:/opt/keycloak/providers/ \
           -p 8080:8080 -e KC_HTTP_RELATIVE_PATH=/auth \
           -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
           quay.io/keycloak/keycloak:22.0.3 start-dev

docker run --rm -v $HOME/projects/acme/extensions/keycloak-theme/target/:/opt/keycloak/providers/ \
           -p 8080:8080 -e KC_HTTP_RELATIVE_PATH=/auth \
           -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
           quay.io/keycloak/keycloak:22.0.3 start-dev

This loads the extension in a very similar environment that the one provided by Cloud-IAM.