Activating your Theme in Keycloak

Now that you have your theme as a .jar file, let's see how you can import it in Keycloak so that it appears in the dropdown list for selecting a theme in the Keycloak Admin console.

To configure your Theme in the Keycloak server follow the specific instruction depending on the way your Keycloak is deployed

Takes the following instructions with a grain of salt. They are contributed by the comunity and might not be up to date. They'll give you an idea of how it's suposed to be done but you'd be better of looking for the official documentation on how to load keycloak extentions.

cd ~/github
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter
# Just to make sure these instructions remain relevant in the future
# We pin the version of the starter we are using.  
git checkout c6511feee3d9471f6ea67bc5176e28150ab951ef
yarn
yarn build-keycloak-theme

docker run \
    -p 8080:8080 \
    --name my-keycloak \
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
    -v "./dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar":/opt/keycloak/providers/keycloak-theme.jar \
    quay.io/keycloak/keycloak:26.0.4 \
    start-dev

Here we use "start-dev" but in production use "start --optimized"

Let's see how you would go about creating a Keycloak Docker image with your theme available.

cd ~/github
mkdir docker-keycloak-with-theme
cd docker-keycloak-with-theme
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter
# Just to make sure these instructions remain relevant in the future
# We pin the version of the starter we are using.  
git checkout c6511feee3d9471f6ea67bc5176e28150ab951ef
cd ..

cat << EOF > ./Dockerfile
FROM node:18 as keycloakify_jar_builder
RUN apt-get update && \
    apt-get install -y openjdk-17-jdk && \
    apt-get install -y maven;
COPY ./keycloakify-starter/package.json ./keycloakify-starter/yarn.lock /opt/app/
WORKDIR /opt/app
RUN yarn install --frozen-lockfile
COPY ./keycloakify-starter/ /opt/app/
RUN yarn build-keycloak-theme

FROM quay.io/keycloak/keycloak:26.0.4 as builder
WORKDIR /opt/keycloak
COPY --from=keycloakify_jar_builder /opt/app/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:latest
COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]
EOF

docker build -t docker-keycloak-with-theme .
docker run \
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
    -p 8080:8080 \
    docker-keycloak-with-theme

In this Docker file we use ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"] but in production use ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start", "--optimized"]

Let's assume that you have the following directory structure:

./docker-compose.yaml
./themes/keycloak-theme-for-kc-all-other-versions.jar # This is the file generated in `dist_keycloak` when running `yarn build-keycloak-theme`

docker-compose.yaml

version: '3.7'

services:
  postgres:
    image: postgres:16.2
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 5432:5432
    networks:
      - keycloak_network

  keycloak:

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

    environment:
      KC_HOSTNAME: ${KEYCLOAK_HOSTNAME}
      KC_HOSTNAME_PORT: 8080
      KC_HTTP_ENABLED: true
      KC_HEALTH_ENABLED: true
      KC_HOSTNAME_STRICT_HTTPS: false
      KC_HOSTNAME_STRICT: false
      
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/${POSTGRES_DB}
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 8080:8080
    volumes: 
      - ./themes:/opt/keycloak/providers/
    restart: unless-stopped
    depends_on:
      - postgres
    networks:
      - keycloak_network

volumes:
  postgres_data:
    driver: local

networks:
  keycloak_network:
    driver: bridge

If you use Bitnami's Keycloak Helm chart you can leverage the initContainers parameter to load your theme.

Chart.yaml

apiVersion: v2
name: keycloak
version: 1.0.0
dependencies:
  - name: keycloak
    version: 21.4.1 # Keycloak 24
    repository: oci://registry-1.docker.io/bitnamicharts

Here we only list the relevant values:

values.yaml

keycloak:
  initContainers: |
    - name: realm-ext-provider
      image: curlimages/curl
      imagePullPolicy: IfNotPresent
      command:
        - sh
      args:
        - -c
        - |
          # Replace USER and PROJECT.    
          curl -L -f -S -o /extensions/keycloakify-starter.jar https://github.com/USER/PROJECT/releases/latest/download/keycloak-theme-for-kc-24.jar

      volumeMounts:
        - name: extensions
          mountPath: /extensions

  extraVolumeMounts: |
    - name: extensions
      mountPath: /opt/bitnami/keycloak/providers

  extraVolumes: |
    - name: extensions
      emptyDir: {}

If you are using Bitnami's Keycloak Helm chart version 24.0.5 and up, you have to mount /emptydir/app-providers-dir. Detail at How to add custom provider

values.yaml

keycloak:
  initContainers: |
    - name: keycloak-plugin
      image: curlimages/curl
      imagePullPolicy: IfNotPresent
      command:
        - sh
      args:
        - -c
        - |
          # Replace USER and PROJECT.    
          curl -L -f -S -o /extensions/keycloakify-starter.jar https://github.com/USER/PROJECT/releases/latest/download/keycloak-theme-for-kc-24.jar

      volumeMounts:
        - name: empty-dir
          mountPath: /emptydir

  extraVolumeMounts:
    - mountPath: /opt/bitnami/keycloak/providers
      name: empty-dir
      subPath: app-providers-dir
    
  extraVolumes:
    - emptyDir: {}
      name: empty-dir

Read this section of the starter project readme to learn how to get GitHub Action to publish your theme's JAR as assets of your GitHub release.

What you need to know is that your keycloak-theme.jar should be placed in the provider directory of your Keycloak (e.g: /opt/keycloak/providers) After that you should run bin/kc.sh build (e.g: bash /opt/keycloak/bin/kc.sh build)

Then you can start your Keycloak server, your theme should be available in it!

If you are utilizing a Keycloak instance managed by Cloud-IAM, importing themes and extensions is quite straightforward.

Uploading custom JAR files is only available with paid plans.

If you decide to subscribe, please consider using the code keycloakify5.

This code will provide you with a 5% discount, and we will also receive 5%, which greatly supports our project!

Enabeling globally on your realm

In any scenario, you should never use the Keycloak reserved realm (master) for your application. Instead it is recommended to create one.

The first option is to enable your themes at the realm level, which means that every application that uses this realm will get this theme applied.

Select your realm at the top left corner
-> Realm settings
-> "Themes" tab

Here you'll be able to select your login, account and email theme.

Enabling a theme for a specific client

The login theme can be applied at the client level. You typically have one Keycloak client per web application. Setting the login theme at the client level means that each application of your realm can have different login/register pages. This comes in handy if you're implementing Theme Variants.

To enable a login theme on one of your clients:

Select your realm in the top left corner
-> Clients
-> Select your client in the list
-> Scroll down to "Login Theme" and select your theme.

The account theme can only be enabled at the realm level; however, accessing the account pages requires authentication. If you don't want your user to inadvertently come across the default login theme when navigating to the account pages after their session has expired, you might want to enable your login theme on the "account-console" client.

Select your realm in the top left corner
-> Clients
-> Select "account console"
-> Scroll down to "Login Theme" and select one of your login theme.

Last updated 3 days ago