Customizing the Keycloak login page

To add a new button with a custom redirect link to Keycloak’s login page, you need to modify the template.ftl file in your custom theme. The steps below provide a detailed guide on how to achieve this.

This guide is based on Keycloak version 21.1.0.

Creating a custom theme

  1. Directory structure

    1. Create a directory structure for your custom theme, as depicted below.

      Directory structure
      keycloak-theme/
├── themes/
    ├── custom-theme/
        ├── login/
            ├── template.ftl
            ├── messages_en.properties
            ├── theme.properties
            ├── resources/
                ├── css/
                ├── img/
                ├── js/

  2. Copying the default theme

    1. You can find the default theme files in the Keycloak server distribution under themes/keycloak/login.

    2. Copy the default theme files from the Keycloak distribution to your custom theme directory.

  3. Editing the template.ftl file

    1. Open the template.ftl file in the custom-theme/login directory. This file contains the HTML structure of the login page.

Modifying template.ftl to add a new button

  1. Locating the socialProviders section

    1. Locate the socialProviders section of the template.ftl file where the form is defined.

      <#nested "socialProviders">

  2. Adding the new button

    1. Add a new button element below the socialProviders section.

    2. Extend the button to contain a redirect link to the JCR fallback login: http://localhost:8080/magnoliaAuthor/.magnolia/jcrlogin.

    3. For example, you can add the following code.

      <#nested "socialProviders">

<div id="kc-custom-providers" class="${properties.customAdditionalLoginSectionClass!}">
  <hr/>
  <h4>Or login in with</h4>

  <a id="magnolia-default-login" class="${properties.customAdditionalLoginButtonClass!}" type="button"
      href="http://localhost:8080/magnoliaAuthor/.magnolia/jcrlogin">
    <span>Magnolia ID</span>
  </a>
</div>

<#if displayInfo>
...

  3. Adding new theme properties

    1. Add some new properties to the theme.properties file that are used in the example code above.

      ## Magnolia login
customAdditionalLoginSectionClass=kc-social-section kc-social-gray
customAdditionalLoginButtonClass=pf-c-button pf-m-control pf-m-block kc-social-item kc-social-gray

Configuring Keycloak to use the custom theme

  1. Updating the container

    1. Log into the container with its container ID.

      docker exec -it <CONTAINER_ID> bin/bash

    2. Create a directory for your theme in the container.

      mkdir /opt/keycloak/themes/custom-theme

    3. Copy the contents of the theme directory from your local machine to the new directory on the running container.

      docker cp custom-theme/. <CONTAINER_ID>:/opt/keycloak/themes/custom-theme

    4. Restart the container.

      docker restart <CONTAINER_ID>

  2. Starting Keycloak

    1. Start the Keycloak container with the updated configuration.

  3. Setting the custom theme

    1. Log into the Keycloak admin console.

    2. Go to Realm Settings → Themes.

    3. For the Login Theme dropdown, select custom-theme.

    4. Save the changes.

Verifying your changes

If necessary, restart the Keycloak container and navigate to the login page. You should see the new button with your custom redirect link.

Magnolia test realm login

Download the complete source code for the custom-theme.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the SSO module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules