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

Let me help you step by step:

• 👥 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.

If you do not wish to do it yourself, 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"
            ]
        }
    ]
}

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 versions

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

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