Running Keycloak with Docker

Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services. Docker Images for Keycloak are available on the quay.io Docker repository. In this tutorial we will learn how to run it with Docker, using some common environment parameters.

So as said, the Docker Image for Keycloak is currently maintained in this repository: https://quay.io/repository/keycloak/keycloak

You can pull it as follows:

$ docker pull quay.io/keycloak/keycloak

On the other hand, when it’s time to run it, you would typically use some environment variables to make it fit for your applications. Let’s see some use cases.

Starting Keycloak and adding an Admin User

That is the most obvious use case, as an Admin user is needed in order to manage Keycloak:

docker run --rm --name keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin  -p 8180:8180  -it quay.io/keycloak/keycloak  -b 0.0.0.0  -Djboss.http.port=8180

You will see that Keycloak starts in foreground and binds to port 8180 (by default port 8080 will be used but it can clash with other services, like WildFly, running on that port):

09:16:07,923 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Keycloak 15.0.2 (WildFly Core 15.0.1.Final) started in 22594ms - Started 692 of 977 services (686 services are lazy, passive or on-demand)
09:16:07,925 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management
09:16:07,925 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

Next, login to the Admin Console, which is available at: http://localhost:8180 with admin/admin:

keycloakd docker

Adding other Keycloak users

You can also add an Admin user on an already running container by executing the add-user-keycloak script available in the /opt/jboss/keycloak/bin folder.

Firstly, collect the container id:

$ docker ps

CONTAINER ID        IMAGE                        
31a5c280ecdf        quay.io/keycloak/keycloak

Next, run the following command:

docker exec 31a5c280ecdf /opt/jboss/keycloak/bin/add-user-keycloak.sh -u frank -p foo

You will see the following log:

Added 'frank' to '/opt/jboss/keycloak/standalone/configuration/keycloak-add-user.json', restart server to load user

Finally, restart the container with:

docker restart 31a5c280ecdf

Managing Keycloak Realms running on Docker

You can approach Keycloak management on docker in at least two ways. One option is using the Web Console as we have seen in the previous section. Another option is to use the Keycloak CLI which you can trigger with a docker exec command.

Let’s see it in action. Firstly, we need to login to Keycloak server:

docker exec 31a5c280ecdf /opt/jboss/keycloak/bin/kcadm.sh config credentials --server http://localhost:8180/auth --realm master --user admin --password admin

We have now logged with the admin user. Let’s use this session to add another realm:

docker exec 31a5c280ecdf /opt/jboss/keycloak/bin/kcadm.sh create realms -s realm=wildfly-realm -s enabled=true -o

If you want a quickstart example of Keycloak CLI you can check this tutorial: Keycloak quickstart example using CLI

Importing a Keycloak Realm at start up

Just in case you want to boot Keycloak and have your Realm imported, you can add the KEYCLOAK_IMPORT Environment variable and the Volume argument (-v) to specify the path where the JSON Realm file will be picked up:

docker run --rm \ 
--name keycloak \ 
-e KEYCLOAK_USER=admin \ 
-e KEYCLOAK_PASSWORD=admin \ 
-e KEYCLOAK_IMPORT=/tmp/realm.json -v /tmp/realm.json:/tmp/realm.json \ 
-p 8180:8180 \ 
-it quay.io/keycloak/keycloak \ 
-b 0.0.0.0 \ 
-Djboss.http.port=8180 \ 
-Dkeycloak.profile.feature.upload_scripts=enabled

Exporting a Keycloak Realm

If you want to export a realm that you have created you’ll need to ensure the container running Keycloak has a volume mapped. For example you can start Keycloak setting the volume (‘v’) option to the /tmp folder:

docker run -d -p 8180:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -v $(pwd):/tmp --name keycloak quay.io/keycloak/keycloak

Then, you can then get the export from this instance by running:

docker exec -it keycloak keycloak/bin/standalone.sh \ 
-Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=export \ 
-Dkeycloak.migration.provider=singleFile \ 
-Dkeycloak.migration.realmName=my_realm \ 
-Dkeycloak.migration.usersExportStrategy=REALM_FILE \ 
-Dkeycloak.migration.file=/tmp/my_realm.json

(notice we use -Djboss.socket.binding.port-offset=100 so that the export runs on a different port than Keycloak itself).

Configuring a Database for Keycloak Image

Keycloak image supports multiple database as backend. You can specify the DB vendor directly with the DB_VENDOR environment variable. Supported values are:

  • h2 for the embedded H2 database,
  • postgres for the Postgres database,
  • mysql for the MySql database.
  • mariadb for the MariaDB database.
  • oracle for the Oracle database.
  • mssql for the Microsoft SQL Server database.

Environment variable names can be used to configure any of the above Database type:

  • DB_ADDR: This is the hostname of the database (optional).
  • DB_PORT: This is the port of the database (optional, default is DB vendor default port)
  • DB_DATABASE: Specify name of the database to use (optional, default is keycloak).
  • DB_SCHEMA: Specify name of the schema to use for DB that support schemas.
  • DB_USER: This is the user to authenticate against the database (optional, default is “).
  • DB_USER_FILE: This is the user to authenticate to the database via file input (alternative to DB_USER).
  • DB_PASSWORD: Specify user’s password to use to authenticate to the database (optional, default is “).
  • DB_PASSWORD_FILE: Specify user’s password to use to authenticate to the database via file input (alternative to DB_PASSWORD).

PostgreSQL example

First, start a PostgreSQL instance:

docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres

Next, launch the Keycloak server:

docker run --name keycloak --net keycloak-network quay.io/keycloak/keycloak  -e DB_USER=keycloak -e DB_PASSWORD=password