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.
- 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
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:
|File at the root of the directory containing our running image configuration (see below)
|Folder where the Letsencrypt certificate files will be stored.
Requires volume to be declared in docker-compose.yml:
|If you want to have persistence in the Keycloak data.
Requires volume to be declared in docker-compose.yml:
#To start in DEV mode:
# command: ['start-dev']
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:
sudo docker-compose up -d
Keycloak administration - First steps
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.
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
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.
|If you want to allow users to self-register.
|Activates the checkbox allowing user to remain logged in until session expiry.
|Email as username
|By default, Keycloak allows for a dedicated username.
Enabling this will disable usernames for login, only allowing for emails.
|Login with email
|Allows user to use their email as well as their username to log on.
|Automatically disabled if Email as username or Login with email is enabled.
It allows for multiple users with the same email as long as they have different usernames.
Only usernames will be allowed to log-in.
|Automatically send an email validation procedure to end user who have logged in for the first time or have had their email updated in the Keycloak account.
Functional overview: Realms, IdP, Federations, Clients, Groups, Users, ...
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 ?
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.
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.