Skip to content

Add custom Keycloak theme

Description

Closes #37 (closed)

Everyone likes branding so adding an Arch Linux based custom theme to Keycloak will make people happy enough to forget their daily troubles 😄.

Acceptance Criteria

The Keycloak theme resembles the Arch Linux website in terms of coloring scheme and aesthetics.

issue_37_custom_theme_sample_coloring

Breakdown

  • There are four sections that can be customized: login, account, admin console and email.

  • The following color palette is used throughout the custom theme:

issue_37_custom_theme_sample_palette

  • The custom theme (archtheme) is a modification of the existing default theme (keycloak)

  • Type of change

  • Visual change (non-breaking change which modifies the appearance of a component)

Additional info

  • When extending a theme we can override individual resources (templates, stylesheets, etc.). If we decide to override HTML templates bear in mind that we may need to update our custom template when upgrading to a new release.

  • While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources directly from the themes directory without restarting Keycloak. We need to remember to re-enable caching in production as it will significantly impact performance (currently development is only taking place on my local machine but added for clarity).

    ./standalone/configuration/standalone.xml
    
    <theme>
        <staticMaxAge>-1</staticMaxAge>
        <cacheThemes>false</cacheThemes>
        <cacheTemplates>false</cacheTemplates>
        ...
    </theme>
  • Do not put anything except characters in the theme name or it'll break (currently set as archtheme).

  • Once custom theme is complete, Ansible will be used to copy the theme under the Keycloak theme directory

  • With the exception of the Ansible playbook (provided to test the changes locally) all files are committed in the same directory structure that Keycloak expects the themes to be in so that we know where to copy the files on the actual server (only modified files will be committed).

How Has This Been Tested?

Using a Keycloak Docker image to spin up a local instance via Ansible to test the theme in an iterative manner. The local instance is set to use the default "keycloak" theme and the modified files (css, templates, images etc) are copied over to essentially override the default theme. An Ansible playbook is provided in the theme folder to facilitate local development.

  • Test Configuration:
    • OS: Arch Linux
    • Ansible: 2.9.11
    • Docker: 19.03.12-ce, build 48a66213fe

Progress (section will keep being updated)

  • Login Theme

image

image

image

  • Admin Theme

image

  • Email Theme

No changes to the messages content is necessary

Edited by Ira ¯\_(ツ)_/¯

Merge request reports