Activating your Theme in Keycloak
Last updated
Last updated
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
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 2553c38272fc76efba8f88c9add6de5ce696ba9d
yarn
yarn build-keycloak-theme
docker run \
-p 8080:8080 \
--name my-keycloak \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin \
-v "./dist_keycloak/keycloak-theme-for-kc-22-and-above.jar":/opt/keycloak/providers/keycloak-theme.jar \
quay.io/keycloak/keycloak:25.0.4 \
start-devHere 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 2553c38272fc76efba8f88c9add6de5ce696ba9d
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:latest as builder
WORKDIR /opt/keycloak
COPY --from=keycloakify_jar_builder /opt/app/dist_keycloak/keycloak-theme-for-kc-22-and-above.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-themeIn 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"]
Create docker-compose.yml for keycloak
build custom theme from keycloakify and get .jar copy and put it some where in same docker-compose.yml directory
in docker-compose.yml for example .jar is in themes
volumes:
- ./themes:/opt/keycloak/providers/^^^ this volums .jar in themes in to opt/keycloak/providers/ in docker container
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:25.0.2
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
KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
KEYCLOAK_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: bridgeIf you use Bitnami's Keycloak Helm chart you can leverage the initContainers parameter to load your theme.
apiVersion: v2
name: keycloak
version: 1.0.0
dependencies:
- name: keycloak
version: 21.4.1 # Keycloak 24
repository: oci://registry-1.docker.io/bitnamichartsHere we only list the relevant values:
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
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-dirRead 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!
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.
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.
