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.
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!
A summary of the most interesting AI Use Cases we have implemented.
Composable commerce skapar förmågan att möta kunders ändrade förväntningar snabbt och framgångsrikt.
Data Mesh is a strategy for scaling up your reporting and analysis capabilities. Learn more about the Google Cloud building blocks that enable your Data Mesh.