Table of Contents
- Base Installation
- Prerequisites
- Installation of Keycloak
- Running Keycloak in a Container
- Configuration of Keycloak
- Configuration of the Olvid Plugin
- Upgrading
- Additional Configuration
- Configuration of an External IdP
- Using LDAP User Federation
- x509 Client Certificates Authentication
- Configure Olvid via an MDM
- Using the management console
- How to use the Console
- Misc.
- Changelog
Running Keycloak in a Container
This guide gives the steps to run Keycloak with the Olvid Plugin in a container. This guide uses docker-compose
to run the container, but you may of course use other container orchestration platforms like Kubernetes.
You should also make sure that the container will be able to connect to the Olvid server. Only the https://server.olvid.io/keycloakQuery
URL needs to be accessible, but you should take this into consideration when configuring your container’s network.
1. Download the Keycloak + Olvid bundle
The Olvid Plugin is bundled with a complete Keycloak (Quarkus version) distribution. The bundle can be downloaded from:
You may check that the SHA-256 hash of the bundle is 15b5ed5567cdc97899e650893e4ebaeb30ebd3548bc79b161d70cb05c88ab798
.
2. Build the container
In order to run Olvid in a container, you must first build the container image. Here we assume that a reverse proxy will be used to handle SSL/TLS and the container can listen in plain HTTP, on the default Keycloak HTTP port: 8080
.
The Dockerfile
below is based on the official Keycloak docker. In the same folder as the bundle tar you downloaded (please make sure you have only one bundle in this folder, if upgrading, remember to delete the old bundle), create a Dockerfile
containing:
FROM registry.access.redhat.com/ubi8-minimal AS build-env
ENV KEYCLOAK_VERSION keycloak_olvid
ARG KEYCLOAK_DIST=keycloak*.tar.gz
RUN microdnf install -y tar gzip
RUN cd /tmp/
RUN mkdir keycloak
ADD $KEYCLOAK_DIST /tmp/keycloak/
RUN mv /tmp/keycloak/keycloak_olvid* /opt/keycloak && mkdir -p /opt/keycloak/data
RUN chmod -R g+rwX /opt/keycloak
FROM registry.access.redhat.com/ubi8-minimal
ENV LANG en_US.UTF-8
COPY --from=build-env --chown=1000:0 /opt/keycloak /opt/keycloak
RUN chmod 777 /opt/keycloak/bin/kc.sh
RUN microdnf update -y && \
microdnf install -y --nodocs java-17-openjdk-headless glibc-langpack-en && microdnf clean all && rm -rf /var/cache/yum/* && \
echo "keycloak:x:0:root" >> /etc/group && \
echo "keycloak:x:1000:0:keycloak user:/opt/keycloak:/sbin/nologin" >> /etc/passwd
USER 1000
EXPOSE 8080
ENTRYPOINT [ "/opt/keycloak/bin/kc.sh" ]
Now run:
> docker build --tag keycloak-olvid .
This builds a container named keycloak-olvid
that can be used in docker-compose
.
3. Run the container
You may want to have a look at the official documentation to see all the options when running Keycloak in a container:
Here is a sample docker-compose.yaml
file that can be adapted to your needs. This one uses PostgreSQL, but you may also use other databases supported by the container. The elements in red need to be modified.
KC_DB_URL
is the database URL and database name (here we assume the database will be namedkeycloak
).- If using another database than PostgresSQL, or using a non-standard PostgreSQL port, remember to change the
KC_DB_PORT
. KC_DB_PASSWORD
is the password of thekeycloak
user in your database. This user must have full access to thekeycloak
database.KEYCLOAK_ADMIN_PASSWORD
is the password of the Keycloak administration consoleadmin
that you will need to configure Keycloak.
version: '3'
services:
keycloak:
image: keycloak-olvid
environment:
KC_DB_URL: jdbc:postgresql://postgres/keycloak
KC_DB_PORT: 5432
KC_DB_DATABASE: keycloak
KC_DB_USER: keycloak
KC_DB_PASSWORD: password
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: password
KC_HTTP_ENABLED: "true"
KC_HTTPS_ENABLED: "false"
KC_PROXY: edge
KC_HOSTNAME_STRICT: "false"
KC_HOSTNAME_STRICT_HTTPS: "false"
KC_HTTP_RELATIVE_PATH: /auth
ports:
- 8080:8080
entrypoint: ["/bin/sh", "-c", "/opt/keycloak/bin/kc.sh build --db postgres && /opt/keycloak/bin/kc.sh start --optimized"]
In this example, Keycloak runs in plain HTTP in “edge” proxy mode, meaning that it should be placed behind a reverse proxy taking care of the TLS encryption. It can still be accessed in plain HTTP on the internal IP address it is running at.
You may start your Keycloak instance by running:
> docker-compose up -d --build
Once the container is running, you may access its logs (to check for error messages) with the command:
> docker-compose logs -f keycloak
4. Configure the reverse proxy
The reverse proxy must send some required headers for Keycloak to properly work:
X-Forwarded-For
X-Forwarded-Proto
X-Forwarded-Host
Please refer to https://www.keycloak.org/server/reverseproxy for more information.
Here is a sample nginx.conf
file. Again, the parts in red should be adapted.
server {
server_name keycloak.public.dns ;
# To only redirect a specific set of paths, you may replace the line below with something of the form
# location ~ ^(/auth/resources/|/auth/js/|/auth/realms/olvid/) {
location /auth {
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
proxy_pass http://keycloak.internal.ip :8080;
}
location /olvid {
return 302 /auth/olvid/#;
}
location = / {
return 302 /auth;
}
client_max_body_size 10M;
listen [::]:443 ssl ipv6only=on;
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/keycloak.public.dns /fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/keycloak.public.dns /privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
Once nginx
is restarted, simply open your Keycloak’s public DNS in a browser, you should see the “Welcome to Keycloak” front page.
Remember the KEYCLOAK_ADMIN
and KEYCLOAK_ADMIN_PASSWORD
credentials you set in your docker-compose.yaml
file: you will need them to sign in to the Keycloak administration console.
You can now continue with the Configuration of Keycloak