This series of articles will explain the detail setup for one of my recent proof of concept project for Keycloak. The following topics will be covered and this is the first part of the series.
- Part 1: Keycloak Installation
- Part 2: OIDC and Oauth 2 with Keycloak
- Part 3: Keycloak with User Federation
Source Code can be found from:
https://github.com/zhangran1/keycloak-tutorial-series
This series of articles will mainly focus on the usage of Keycloak, separate articles might be written at later time to cover OIDC, Oauth and API security.
System information
OS: Ubuntu 20.04
JDK: 11.0.11
Maven: 3.6.3
Docker: 20.10.2
Docker-compose: 1.29.2
Keycloak: 15.0.2 (Launch via docker)
This proof of concept is optimised for the above system setup, all applications was running in the same host. As Keycloak evolves relatively fast in recent years, it is possible that this guide is deprecated or irrelevant if you are using a different version of Keycloak.
Install and Launch Keycloak
Generally there are two ways to run Keycloak:
- Launch Keycloak via command line after download the Keycloak from https://www.keycloak.org/downloads
- Launch Keycloak via Docker
The demo source code opted for Docker based Keycloak due to the simplicity of configuring SSL cert, nevertheless, here will cover both launch Keycloak via command line and from docker container.
Launch Keycloak via command line
- Download Keycloak from https://www.keycloak.org/downloads and you will get keycloak-15.0.2.zip
2. Unzip keycloak-15.0.2.zip and rename the folder to keycloak
$ unzip keycloak-15.0.2.zip && mv keycloak-15.0.2 keycloak
3. Create an admin user and give it a password
$ sh keycloak/bin/add-user-keycloak.sh -u admin -p admin
You may see the following output:
Note that /home/zhangran/Documents/medium-com/keycloak is the folder I unzip the keycloak in step 2.
Added ‘admin’ to ‘/home/zhangran/Documents/medium-com/keycloak/keycloak/standalone/configuration/keycloak-add-user.json’, restart server to load user
4. Add a user in keycloak.
$ sh keycloak/bin/add-user.sh -u user1 -p user1
You may see the following output:
Added user ‘user1’ to file ‘/home/zhangran/Documents/medium-com/keycloak/keycloak/standalone/configuration/mgmt-users.properties’
Added user ‘user1’ to file ‘/home/zhangran/Documents/medium-com/keycloak/keycloak/domain/configuration/mgmt-users.properties’
5. Launch Keycloak
$ sh keycloak/bin/standalone.sh -b 0.0.0.0 -bmanagement 0.0.0.0 — server-config=standalone-ha.xml
6. Now you can access keycloak . By default keycloak runs at port 8080
Visit http://localhost:8080 and you may see the following page.
Click Administration Console and use the credential created in step 3 to sign in.
username: admin
password: admin
Voilà, you successfully launched Keycloak.
Launch Keycloak via Docker
- Create a docker compose file and place at the location of your choice. Below is the contend of docker compose file. In this guide, the docker compose file named as keycloak-docker.yml. This docker compose file conatins
version: ‘3.3’
services:
keycloak:
image: jboss/keycloak:15.0.2
container_name: keycloak-demo
command: [“-c standalone.xml”]
environment:
- KEYCLOAK_USER=admin
- KEYCLOAK_PASSWORD=admin
- DB_VENDOR=h2
port:
- 8080:8080
- 9990:9990
2. Launch container via docker compose up command
docker-compose -f keycloak-docker.yml up
If everything works ok, you may see the following two lines in console output.
keycloak-demo | 04:27:32,085 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management
keycloak-demo | 04:27:32,085 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990
3. Access Keycloak via http://localhost:8080, you will see the login page
Click Administration Console and use the credential created in step 3 to sign in.
username: admin
password: admin
Voilà, you successfully launched Keycloak.
For rest of the articles we will primarily focus on using container to launch Keycloak.
