Keycloak: the user-friendly identity and access management tool

While other solutions might be better known (Aperero CAS, LemonLDAP), Keycloak is one of the more user friendly while also providing a complete toolkit for user & access management.

• Official website: Keycloak
• Documentation: Keycloak documentation
• Docker images: quay.io/keycloak/keycloak
• Critical documentation: All configuration & environment variables available

Please note that the official distribution is quay.io/keycloak/keycloak which is now up to version 22.0.5-0 as of November 2023.
There is an alternative Docker-based distribution: JBOSS/Keycloak unfortunately it is no longer maintained and the latest image is version 16.1.1 which was released January 25th 2022.

While functionnalities and the overall UI design haven't changed too much meaning documentation can be used whatever distribution you have, any technical documentation for Docker/Docker-compose environment variables will not translate from one distribution to another.

To illustrate:

• The UI:

• Docker-compose.yml file:

This article will provide the information to deploy your own Keycloak platform and a quick overview of the basics.

Deploying Keycloak v 22.X.X on Ubuntu 22.04 via Docker-compose and an external PostgreSQL database

Pre-requisite

• A PostgreSQL dedicated database and user

  CREATE USER keycloakadmin with password 'Averypassword4Keycloak!';
  CREATE DATABASE keycloakdb with owner keycloakadmin ;
  GRANT ALL PRIVILEGES ON DATABASE keycloakdb TO keycloakadmin;

• Ubuntu 22.04 server up to date with docker-compose installed

  sudo apt update -y
  sudo apt upgrade -y
  sudo apt install -y docker-compose

• Ubuntu 22.04 server must be able to connect to the dedicated database:

  psql -h <DBHOSTIP> -U keycloakadmin -p 5432 keycloakdb

• Ubuntu 22.04 server must be able to pull docker images from Keycloak Docker image registry

• Set up a dedicated sub-domain.
  For our example keycloak.nicksopenworld.com

• Optional: a Traefik service to manage HTTPS certificates
  Keycloak can manage HTTPS if provided with certificate files but having Traefik or an equivalent makes it so much easier.

Files and folders configuration & setup

For this demonstration, a sub-directory "keycloak" has been created in /opt containing:

docker-compose.yml

version: "3.9"

services:
  keycloak:
    image: quay.io/keycloak/keycloak:22.0.5-0
    container_name: keycloak
    command: ['start']
#To start in DEV mode:
#    command: ['start-dev']
    logging:
      driver: syslog
      options:
        tag: keycloak
    restart: always
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: keycloak
      KC_DB: postgres
      KC_DB_URL_HOST: 192.168.22.22
      KC_DB_URL_PORT: 5432
      KC_DB_URL_DATABASE: keycloakdb
      KC_DB_USERNAME: keycloakadmin
      KC_DB_PASSWORD: 'Averypassword4Keycloak!'
      KC_DB_SCHEMA: public
      KC_HOSTNAME_STRICT: 'true'
      KEYCLOAK_LOGLEVEL: INFO
      ROOT_LOGLEVEL: INFO
      KC_HEALTH_ENABLED: 'true'
      KC_HTTP_ENABLED: 'true'
      KC_METRICS_ENABLED: 'true'
      KC_PROXY: reencrypt
      KC_HOSTNAME_URL: https://keycloak.nicksopenworld.com
      KC_HOSTNAME_ADMIN_URL: https://keycloak.nicksopenworld.com

    networks:
      - local
networks:
  local:
    name: local
    driver: bridge

Explaining a few of the parameters

• KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD are used to create the default admin user.
  The password is not encrypted or secured in any way as we will be updating it on firt log-in as a matter of basic security procedure.
  The application actually doesn't force that update so make sure it is done.

• KC_HTTP_ENABLED is set to "true" because we will be expose HTTPS using Traefik: communication between Traefik and Keycloak will be done through HTTP.

• "command: ['start'/'start-dev']" defines if you are launching Keycloak in a PRODUCTION environment or as a DEV/TEST platform in which case it will use the embeded H2 database to store information.
  Also note that using the '--optimized' command is reserved for non-PRODUCTION environments meaning that even if you set database configuration, the container will start up using the embeded H2 database.

• No volumes ?
  Since our container will be behind a Traefic, we don't need to store certificates locally.
  And we don't have any need of persistent data storage.

If you want to check all the available configuration parameters: all configuration & environment variables available

Once you've configured the parameters you need and saved your docker-compose.yml file, simply run:
cd /opt/keycloak
sudo docker-compose up -d

Keycloak administration - First steps

Connect to the UI and connect to the Administration console:

Once connected, you'll be logged on the Master realm.

Secure "admin" account

The password for the "admin" account for the Master realm can be found in the docker-compose.yml in clear text making it a security issue.

Once connected, go to "Users" and update it:

Do not forget to set the Temporary value to Off.

Create your REALM

The Master realm should be kept for Keycloak administration tasks.

Open the dropdown menu and click Create Realm:

You will only need to provide a name for your realm.
You can then navigate between realms using the dropdown.

Realm settings - General information

All the endpoint information and general information for your realm can be found in the Realm settings:

Email configuration

In Email tab, you can configure SMTP for mail sending and also the email flow:

This is an overly complex example to illustrate what they are for:

• From: email are sent by the person/team in charge of Keycloak when managing users or automatically by the platform.
  We therefore chose to send with a dedicated email.

• Reply to: when people reply to these types of emails, it's generally because of an issue, so we send it to support email.

• Envelope from : when emails bounce, we need to update our user listing so we send these emails to marketing who keep our contact up to date.

In actual fact, I've usually had Support email as the value set for all 3 fields.

Login options & forgotten password management

Once SMTP capability has been set up, we can activate the "Forgot password" button in the Login tab.

This allows end users to renew their password without having to contact Support.

Other options:

Functional overview: Realms, IdP, Federations, Clients, Groups, Users, ...

A general view:

What a realms for ?

Realms are used for data segregation: realms don't share any information with other realms.
And each realm has his own entrypoint(s)/login page.

Connections between realms can be set up to push data from one to the other but it requires an active action from Keycloak managers and is only necessary in specific scenarios.

A simple example would be a company acquiring another such as Dell with Alienware.

• Dell had their employees with emails @dell.com and access to Dell internal tools
• Alienware had their employees with emails @Alienware.com and their own internal tools
• some external ressources worked for both companies and had access to both tool sets with their own email @external.com

In this scenario, we would have the Keycloak Master realm and 2 dedicated realms:

• Dell realm with @dell.com and @external.com users
• Alienware realm with @Alienware.com and @external.com users

Disclaimer: this scenario is entirely made up, I have no idea what Dell or Alienware use in regards to internal tools.

Do we need to set up a connection to an external IdP or User Federation ?

No!
For small structures, Keycloak can be self-sufficient by setting up groups and users to be able to provide the necessary information for user authentication in the connected applications.

Connection to an external IdP or User Federation, if you have either one or both in your organisation, is userful in order to automatically import users and their information into your Keycloak platform following rules you've pre-defined when said users log into their ressources via Keycloak.

One Keycloak platform can import from multiple IdP/User Federation platforms.

Keycloak can also be used as an IdP.

What is a client ?

A client is the entrypoint an external application will use to retrieve user information and validate authentication.

Theoretically, if 2 applications required the same user information (for example First & Last name, email and date of birth), they could use the same client in Keycloak.

However, this would mean that either the users accessing one application would also get access the other, unless we set up a very granular and detailled configuration.
And it could cause issues if one application's requirements changed and not the other.

To keep things simple, usually 1 client is for 1 application only.

What are groups for if clients are the elements defining access to ressources ?

Clients might define what type of information is sent to authenticate for each application, the information must be present in Keycloak.

The information can be at the user level (First name, Last name, Username, email...) but can also be defined in groups.

For example, groups can be set up per application with each group adding to the user informatoin all the necessary attributes for that application.

Or groups can reflect the different teams in your orginsation: Support group will provide all the information for the ressources used by that team.

This schema is not technically accurate as there are different protocols and back-and-forth communication between the IdP/Federation, Keycloak and the applications it allows authentication into.
It's a general view how data is transferred used from the identity platform to the application client.

Authentication management using Keycloak

When to use Keycloak

It can be used any time but makes the most sense when you start having multiple applications/platforms for which user credentials are required to access ressources.

Instead of having to remember and save multiple username/password combinations, you only have 1 set of credentials to use:

• Keycloak's if you don't have an external IdP/User Federation
• Your IdP/User Federation credentials

Is it compatible with everything ?

For Authentication, it manages SAML and OpenID protocols so as long as the application/platform you want to connect can either, it should work.

And depending on the application/platform, you might have a native SAML or OpenID module out of the box or you might need to install an externsion/module.

For example Redmine has both a SAML and an OpenID functional plugin.
Wordpress has multiple SAML plugins, some free and some not.
Metabase has SAML support but only for paying versions, the free opensource version only manages LDAP integration (and Keycloak can connect and import data from LDAP services but can't act as one).

Diagnostics & debug using Keycloak

• Events: if proprely configured, you will find logs for authentications (failed or succesfull) and user management actions.
  For example, if a user has too many failed connections, Keycloak will automatically block the account in order to avoid DDOS-type issues. Checking the Events will confirm the status and reason of the account suspension.

• Sessions: lists all the active sessions, meaning users logged in Keycloak and the ressources they are actively connected to.
  It also allows for mass-management for example ifyou want to disonnect everyone from a given service: simply revoke all active sessions for that service.

Conclusion

Keycloak is an easy to use tool to set up Single-Sign-On, easing the user management over multiple applications/platforms.

However it has many complex functionnalities available to be used depending on your requirements.

To see more detailed examples of integrations, checks the other articles in the Keycloak or SSO categories.