Keycloak is an open-source Identity and Access Management application. We use Keycloak on several of our customers and love it. In this article series we will discover Keycloak, its capabilities, and explore how to use it. The examples will be in Java (Spring Boot), but the concepts are independent from language and platform.
In this first chapter we will discuss the concept of IAM (Identity and Access Management) and walk through the installation of prerequisites and Keycloak.

Identity and Access Management (IAM)

IAM helps us by handling all the tiresome authentication (WHO?) and authorization (WHAT?) stuff in one single place. This burden can then be lifted from all other applications which, if they have a user they don’t know, just send it right over to old uncle IAM who will sort it out for the application. One IAM service can be shared between several (typically most, if not all) applications and services, and at a larger scale, companies like Google, Facebook and GitHub offer IAM-services for applications and systems everywhere. This is called federated authentication and basically means that your application trusts another entity (company) to authenticate a user for you.

It really works kind of like this:

  • User tries to access resource.
  • Resource demands authentication.
  • If user have a valid token. It’s verified by IAM. Go directly to SUCCESS:
  • If not, continue.
  • Resource sends user request to IAM.
  • IAM tries to authenticate the user.
    • If successful user gets a token to prove identity.
    • If not, user gets a login screen to provide username and password (or other means of authentication).
  • When authenticated user is sent back to resource with a fresh token from which access can be decided.
  • SUCCESS: User can access resource!

On top of the simple use-case above there are several more use-cases with varying complexity. Understanding all of these is not in scope for this article series but to name a few:

  • Single sign on.The use case described above. A single point of contact for all authenticating needs.
  • Identity brokering.IAM acts as a single point for authentication but delegates the actual authentication to one or more external identity providers. IAM acts as a facade for these identity providers.
  • Identity provisioning.IAM contains the user store used to acquire information of the logged in user (such as authorization information), as well as performing authentication.
  • User Management.IAM contains means for managing users, roles and general user information as well as user provisioning to/from the other connected user-stores and identity-providers.

Installing KeyCloak

Throughout this document I’m going to assume that you are using an Ubuntu or Debian Linux distribution, however the guide works on most other operating systems as long as the prerequisites are met.
At the end we will have installed KeyCloak with a PostgreSQL database as Docker containers but first we need some housekeeping and some prerequisites.

Prerequisites

You’ll need Java, Docker, Git and Maven. Docker will run the container in which KeyCloak resides, Java will compile and execute our code, Maven will build and package, Git will do versioning. Pretty basic.

Install Java JDK version >= 17

My favorite is to use SDKMAN for keeping track of different SDK/JDK installations and which installation is active. If you want to install the JDK in some other fashion, that’s ok and up to you.

Install SDKMAN at the command line, in your home directory.

$ curl -s "https://get.sdkman.io" | bash

Follow the on-screen instructions to complete the installation.

In a new terminal do

$ source "$HOME/.sdkman/bin/sdkman-init.sh"

Check version of SdkMan to verify

$ sdk version

==== BROADCAST =================================================================
* 2022-10-19: quarkus 2.13.3.Final available on SDKMAN! https://github.com/quarkusio/quarkus/releases/tag/2.13.3.Final
* 2022-10-18: micronaut 3.7.2 available on SDKMAN!
* 2022-10-17: gradle 6.9.3 available on SDKMAN!
================================================================================

SDKMAN 5.16.0

With SdkMan installed we can use it to install Java.

First list all java versions, this will show all java versions available for installation. At command line do

$ sdk list java

================================================================================
Available Java Versions for Linux ARM 64bit
================================================================================
 Vendor        | Use | Version      | Dist    | Status     | Identifier
--------------------------------------------------------------------------------
 AdoptOpenJDK  |     | 8.0.275+1.hs | adpt    |            | 8.0.275+1.hs-adpt
               |     | 8.0.252.hs   | adpt    |            | 8.0.252.hs-adpt
 Corretto      |     | 19           | amzn    |            | 19-amzn
               |     | 17.0.4       | amzn    |            | 17.0.4-amzn
               |     | 11.0.16      | amzn    |            | 11.0.16-amzn
               |     | 8.0.342      | amzn    |            | 8.0.342-amzn
 Dragonwell    |     | 17.0.4       | albba   |            | 17.0.4-albba
               |     | 11.0.16      | albba   |            | 11.0.16-albba
               |     | 8.0.345      | albba   |            | 8.0.345-albba
 GraalVM       |     | 22.2.r17     | grl     |            | 22.2.r17-grl
               |     | 22.2.r11     | grl     |            | 22.2.r11-grl
               |     | 22.1.0.r17   | grl     |            | 22.1.0.r17-grl
               |     | 22.1.0.r11   | grl     |            | 22.1.0.r11-grl
               |     | 22.0.0.2.r17 | grl     |            | 22.0.0.2.r17-grl
               |     | 22.0.0.2.r11 | grl     |            | 22.0.0.2.r11-grl
               |     | 21.3.3.r17   | grl     |            | 21.3.3.r17-grl
               |     | 21.3.3.r11   | grl     |            | 21.3.3.r11-grl
               |     | 21.3.3.1.r17 | grl     |            | 21.3.3.1.r17-grl
               |     | 21.3.3.1.r11 | grl     |            | 21.3.3.1.r11-grl

Find the version you want to install and take a note of the Identifier for that version. Also remember, we want a JDK with version 17 or higher.

Install the java version, I’m using Oracle version 19. You pick your choice.

$ sdk install java 19-oracle

The java version is downloaded, installed and configured, ready for using.

There is a lot more to SDKMAN, it really is a magnificent tool. Check out the website for more info.

Install Docker

Docker is docker. The container manager where we run stuff in containers. This is the plain Jane CLI-version. Use the desktop version if you like, it works just as well.

Update the package manager

$ sudo apt-get update

Install dependencies

$ sudo apt-get install ca-certificates curl gnupg lsb-release

Add the docker GPG-key.
First make the directory to hold apt keys if it’s not already there.

$ sudo mkdir -p /etc/apt/keyrings

And then add the official key. If you are running some other linux dist (f ex Debian) replace ubuntu in the command below with that dist-name.

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

And set up the repository. Same thing here, replace ubuntu with the dist you are running.

$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

The repository is all set and it’s just to install docker

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-compose

Verify installation by running the hello-world image

$ sudo docker run hello-world
Install Git

Git is used for versioning documents on GitHub.

Install the tools at the command line

$ sudo apt-get update
$ sudo apt-get install git-all

Verify by

$ git --version
Install Maven

Maven will build your code and also download and keep track of all the necessary dependencies.

Install maven at the command line

$ sudo apt-get update
$ sudo apt-get install maven

Verify by

$ mvn --version
Installing KeyCloak

Open a terminal window and navigate to wherever you want a directory called keycloak-containers. Since this is just a test-installation, maybe your home directory is fine?

$ mkdir ~/keycloak
$ cd ~/keycloak

Clone the keycloak git repository with all the containers

$ git clone https://github.com/keycloak/keycloak-containers

Change directory to keycloak-containers

$ cd ~/keycloak/keycloak-containers

Build a docker container tagged as mykeycloak (or anything, really) from the ./server directory

$ sudo docker build -t mykeycloak ~/keycloak/keycloak-containers/server

Create a file called docker-compose.yml in the keycloak-containers directory with the following content:

version: '3'

volumes:
  postgres_data:
      driver: local

services:
  postgres:
      image: postgres
      volumes:
        - postgres_data:/var/lib/postgresql/data
      environment:
        POSTGRES_DB: keycloak
        POSTGRES_USER: keycloak
        POSTGRES_PASSWORD: password
      ports:
        - 5432:5432
  keycloak:
      image: mykeycloak
      environment:
        DB_VENDOR: POSTGRES
        DB_ADDR: postgres
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_SCHEMA: public
        DB_PASSWORD: password
        KEYCLOAK_USER: admin
        KEYCLOAK_PASSWORD: admin
      ports:
        - 8091:8080
      depends_on:
        - postgres

Start the docker container and the postgresql database. The keycloak container will run at port 8091.

$ cd ~/keycloak/keycloak-containers
$ sudo docker-compose up -d

Verify that the containers are running

$ sudo docker stats

There, all done. Let’s get cooking!
Open a browser to http://localhost:8091/auth
Login with admin/admin

And that concludes our first article in this series. In the next article we’ll use KeyCloak to secure a REST-endpoint.

All the code and examples can be found over at GitHub.

Categories: Java, Keycloak, Säkerhet, Spring

Fler insikter och blogginlägg

När vi stöter på intressanta tekniska saker på våra äventyr så brukar vi skriva om dom. Sharing is caring!