I Customized the Keycloak Admin Console UI to Add Custom Pages

Introduction

I received a requirement to customize the Keycloak Admin Console UI by adding a completely new section inside the existing Admin Console.

Initially, I did not have prior experience with customizing the Keycloak Admin Console or extending its existing frontend architecture.

Before starting the implementation, I explored different possible approaches. I reviewed GitHub discussions related to Keycloak Admin Console customization and explored available technical resources, documentation, and videos to understand the overall architecture.

I also explored Keycloakify, which is a popular approach for customizing Keycloak themes and user-facing interfaces. This helped me understand how Keycloak UI customization works from a theme perspective.

However, my requirement was different because I needed to customize the Admin Console itself by adding new pages and navigation inside the existing administrator interface.

Although resources were unavailable, I could not find a complete end-to-end solution that explained exactly how to extend the Keycloak Admin Console with custom sections and pages.

Because of this, I decided to explore the Keycloak source code directly and understand how the Admin Console is internally implemented.

Exploring the Keycloak Open Source Repository

Because Keycloak is an open-source project, I cloned the complete Keycloak repository locally and started analyzing the internal implementation.

The main objective was to understand:

• Where the Admin Console frontend code exists.
• How pages and routes are created.
• How navigation items are registered.
• How frontend changes are integrated with the Keycloak server.
• How the Admin Console can be customized safely without affecting existing functionality.

This source-code exploration became the foundation for implementing my customization.

Understanding the Keycloak Folder Structure and Run locally

During the source-code exploration, I discovered that the Keycloak frontend applications are organized inside the js directory.

The js folder contains multiple frontend applications and shared packages.

The high-level structure looks like this:

js/

├── apps/

│   ├── admin-ui

│   ├── account-ui

│   ├── keycloak-server

└── themes/

The apps directory contains different frontend applications used by different parts of Keycloak.

For my requirement, the most important application was:

js/apps/admin-ui

because this folder contains the complete React-based implementation of the Keycloak Admin Console UI.

Since my goal was to add new pages and navigation inside the administrator interface, my complete focus became the admin-ui application.

For faster development, I separated the process into two parts:

1. Running the Admin UI application.
2. Running the Keycloak server with Admin UI development mode enabled.

Running the Admin UI Application

First, I moved into the Admin UI application:

cd js/apps/admin-ui

Then I installed the required dependencies:

pnpm install

After installing dependencies, I started the Admin Console frontend:

pnpm dev

The Admin UI application started successfully on:

http://localhost:5174

At this point, the Admin Console frontend was running independently in development mode.

This allowed me to:

• Modify React components.
• Add new routes.
• Create new pages.
• Test UI changes immediately.
• Debug frontend-related issues quickly.

Running the Keycloak Server in Admin Development Mode

After starting the Admin UI, I moved to the Keycloak server application:

cd js/apps/keycloak-server

Then I started the Keycloak server using:

pnpm start --admin-dev

The --admin-dev option tells Keycloak to use the locally running Admin UI application.

This creates a development workflow like:

 Browser

   |

(localhost:8080)

Now whenever I changed frontend code inside:

js/apps/admin-ui

the changes were immediately reflected in the running Keycloak Admin Console.

This local setup was extremely useful because it allowed quick testing and iteration without rebuilding the complete Keycloak distribution every time.

A new Permission Management tab inside the Admin Console.

Custom Permission Management tab integrated into Keycloak Admin Console

Final Result

After completing the implementation, I successfully customized the Keycloak Admin Console UI.

The final result included:

✅ A new Permission Management tab inside the Admin Console.

✅ A dedicated route structure.

✅ A Permission List page.

✅ A Create Permission page.

✅ Custom business-specific modifications.

✅ Complete integration with the existing Keycloak Admin Console experience.

The customized pages behaved like native Keycloak pages instead of a separate external application.

Packaging the Customized Keycloak Build

After completing the customization, the changes could be packaged through the Keycloak build process.

The generated JAR contains the required modifications and integrations, allowing the customized Keycloak server to run with the updated Admin Console UI.

This packaging process makes it possible to distribute and deploy the customized Keycloak version while keeping the changes integrated with the existing Keycloak architecture.