How to override Keycloak's default login-register pages using React

1. Kickstart the Keycloak Theme (Keyclokify) Project

1
git clone https://github.com/keycloakify/keycloakify-starter
2

3
cd keycloakify-starter
4

5
yarn install
6
# You can use any package manager (npm, pnpm, etc.)
7
# If you do, delete the .yarn.lock file to avoid conflicts.

The following command is used to select which page you want to edit. When you run this command, there will be a list of pages you can select from.

1
npx keycloakify add-story
2

3
# Select login.ftl (for example).
4
# Always use `npx` to run CLI tools installed in your project.
5
# This is standard practice across all modern JS projects,
6
# do not try to adapt this command based on your package manager.

Select the page you would like to change here by navigating through arrow keys and pressing enter.

1
npm run storybook
2

3
# `npm run <script>`, `yarn <script>`, and `pnpm run <script>`
4
# are strictly equivalent. We use `npm run` here for
5
# consistency and because `npm` is always available.

After running this command, you should be able to see the following screen (depending on what story you selected)

You can see all the scenarios related to the login listed under the login.ftl story. If you change the styling via CSS, then all of those scenarios will change as well.

3. Style It Up with Custom CSS

• Create a CSS file in src/login/main.css
• Import it to KcPage.tsx
• Inspect the elements on the login page and get the CSS class with kc as a prefix.
• KC classes are for adding custom styles. You can write CSS for the KC classes and see the changes happening on the page in real-time.

Add the following CSS to add your custom company logo after the sign-in text. Likewise, we have so much flexibility when it comes to styling. You can add a custom span or div element in Kcpage.tsx. We can style with display : none to remove the elements we do not need. Actually, you can use an LLM to easily modify these styles and create the desired look you want, so do not worry about the CSS.

1
h1#kc-page-title::after {
2
    content: "";
3
    display: block;
4
    width: 150px;
5
    height: 150px;
6
    margin: 20px auto 0;
7
    background-image: url(../img/college-logo.png);
8
    background-size: contain;
9
    background-repeat: no-repeat;
10
    background-position: center;
11
}

4. Build the theme and generate the `.jar`

Now you need to output your project as a JAR file, which Keycloak understands.

1
npm run build-keycloak-theme

5. Deploy the JAR into Keycloak Providers

Keycloak providers are modular plugins that allow you to extend the server’s functionality, such as connecting to legacy user databases, adding custom authentication steps, or listening to login events without modifying the core source code.

They rely on a standard Java pattern called the Service Provider Interface (SPI), where you implement specific interfaces in your code and package them into a JAR file.

To “introduce” a provider, you simply place this JAR into Keycloak’s providers directory.

How to modify the docker-compose.yml to include the providers

Following is my docker-compose.yml ⁣I used to add provider jars into the Keycloak installation. After modifying the YML file, you need to rebuild and rerun the container.

Following is my docker-compose.yml file. See the line containing ./themes:/opt/keycloak/providers/ you should also add it and place the jar file inside the themes folder.

1
version: '3.7'
2

3
services:
4
  postgres:
5
    image: postgres:16.2
6
    volumes:
7
      - postgres_data:/var/lib/postgresql/data
8
    environment:
9
      POSTGRES_DB: keycloak_db
10
      POSTGRES_USER: keycloak_user
11
      POSTGRES_PASSWORD: keycloak_password
12
    ports:
13
      - 5432:5432
14
    networks:
15
      - keycloak_network
16

17
  keycloak:
18

19
    image: quay.io/keycloak/keycloak:26.0.4
20
    command: start-dev
21

22
    environment:
23
      KC_HOSTNAME: localhost
24
      KC_HOSTNAME_PORT: 8080
25
      KC_HTTP_ENABLED: true
26
      KC_HEALTH_ENABLED: true
27
      KC_HOSTNAME_STRICT_HTTPS: false
28
      KC_HOSTNAME_STRICT: false
29

30
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
31
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
32
      KC_DB: postgres
33
      KC_DB_URL: jdbc:postgresql://postgres/keycloak_db
34
      KC_DB_USERNAME: keycloak_user
35
      KC_DB_PASSWORD: keycloak_password
36
      KC_SPI_THEME_STATIC_MAX_AGE: -1
37
      KC_SPI_THEME_CACHE_THEMES: false
38
      KC_SPI_THEME_CACHE_TEMPLATES: false
39
    ports:
40
      - 8080:8080
41
    volumes:
42
      - ./themes:/opt/keycloak/providers/
43
    restart: unless-stopped
44
    depends_on:
45
      - postgres
46
    networks:
47
      - keycloak_network
48

49
volumes:
50
  postgres_data:
51
    driver: local
52

53
networks:
54
  keycloak_network:
55
    driver: bridge

5. Change the login theme via the admin console.

Realm Settings → Themes → Select keyclokify-starter in the dropdown. Thereafter, you will see the beautiful login page you created.

A few more issues I faced