Learn how to customize the Keycloak login page.

Prerequisites:

Knowledge of how to create a theme for Keycloak https://www.keycloak.org/docs/latest/server_development/#_themes

Introduction

For censhare WP, the login page of censhare Web and the censhare clients are managed in Keycloak. To customize the look and feel of these pages, create a custom theme in Keycloak. Themes can also be applied to the internal administration pages of Keycloak.

A typical theme extends a default keycloak theme and consists of:

  • HTML templates
  • stylesheets
  • messages
  • scripts
  • images
  • theme properties

Add a custom theme

Currently, only the censhare custom theme is supported. Further custom branding is not supported in this release.


Custom themes are not provided with standard Keycloak installation. The censhare theme is a custom theme which, in a compiled state, is represented by a number of static files.

Do the following:

  1. Create a new theme. For more information, see this Keycloak documentation.

  2. On the Keycloak server, perform the following checks to ensure that custom themes are enabled. If custom themes are already enabled on your Keycloak instance, you can skip this step:

    • The COMPOSE_FILE property must include a reference to sso.themes.yml with a colon as delimiter:

      COMPOSE_FILE=sso.base.yml:sso.themes.yml

    • The ARG_CENSHARE_SSO_THEME_CACHE_DISABLED property must be set to true:

      ARG_CENSHARE_SSO_THEME_CACHE_DISABLED=true

    • The path to the directory that stores the custom theme must be specified:

      ARG_CENSHARE_SSO_THEMES_PATH=/opt/censhare/authentication/dockerfiles/sso-server-themes

  3. Build and run the Keycloak server: change to the static resource server directory, and run the ./build.sh command.

  4. Add your custom theme to the directory configured in step 2.

  5. Open the Keycloak URL and log in with your administration credentials.

  6. At the top of the side navigation, select the censhare realm.

  7. Open the Realm settings and go to the Themes tab.

  8. In the Login Theme field, select your custom theme.

Instead of the realm, you can assign a custom theme to a specific client only: Select the desired client, and in the Settings tab, in the Login theme field, select the desired theme.

Result

You know how to create a custom theme for the Keycloak login page.