Configure custom themes

Keycloak provides theme support for web pages and emails. This allows customizing the look and feel of end-user facing pages so they can be integrated with your applications.

The intended approach to configure a custom themes is to bundle the themes in a container image and copy it to the correct location as an init container.

Creating custom themes

A theme can provide one or more types to customize different aspects of Keycloak. A theme consists of: HTML templates, images, message bundles, stylesheets, scripts and theme properties.

Follow the official guide on how to create a custom theme

Once you have created your custom theme, you’ll need to package it into a container image.

FROM docker.io/library/busybox

COPY theme /theme

RUN \
  chmod -R +r /theme

USER 1001:0

Deploying custom themes

With the theme accessible in a container image we can deploy it using an init container. In combination with an emptyDir volume that’s shared with the Keycloak container, we copy the theme over to the right place where Keycloak will pick it up automatically.

parameters:
  keycloak:
    extraInitContainers:
      theme-provider:
        image: company/keycloak-themes:v1.0.0
        imagePullPolicy: IfNotPresent
        command:
          - sh
        args:
          - -c
          - |
            echo "Copying theme..."
            cp -R /themes/* /target/
        volumeMounts:
          - name: themes
            mountPath: /target
        ## Hardening
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
              - ALL
        ## Hardening end

    extraVolumes:
      themes:
        emptyDir: {}

    extraVolumeMounts:
      theme-company:
        name: themes
        mountPath: /opt/keycloak/themes/company
        subPath: company
        readOnly: true
      theme-other:
        name: themes
        readOnly: true
        mountPath: /opt/keycloak/themes/other-theme
        subPath: other-theme
        readOnly: true

    # Change the theme for the welcome page or default theme with extraEnvs
    # Theme name is the same as the folder in mountPath
    extraEnv:
      KC_SPI_THEME_WELCOME_THEME:
        value: 'company'

Note that simply mounting the "themes" volume to /opt/keycloak/themes will overwrite the default Keycloak themes.

See the official deploy guide for a more detailed look into deploying themes.