This post is a complete guide to Keycloak, starting with what it is, why it is so
popular, briefly going over the long way it has come to now be a Cloud Native Computing
Foundation project and why it will stay relevant if not become even more relevant in the
future.
Identity and Access Management
Most services on the internet require some kind of user and permission management. In
software terms systems which provide such functionality are called "Identity and Access
Management" or short IAM.
We refer to IAM systems when we speak about a system that ensures the appropriate
individuals or systems have the right access to resources within a computing environment.
IAM systems typically encompass user authentication, authorization, and management of
digital identities.
So they are crucial for maintaining security and compliance within
organizations by controlling access to sensitive information and resources.
Read here for an helpful blog post regarding the user management within keycloak.
OAuth 2.0
The wording resources already brings into play one of the de facto standards of nowadays
web. The authorization framework OAuth 2.0 allows third-party applications to obtain limited
access to a user's resources hosted by a resource owner, such as a web service or an
application, without exposing the user's credentials.
OAuth 2.0 is widely adopted for enabling secure authorization flows between applications, especially in scenarios where users want to
grant access to their resources to third-party services without sharing their passwords.
Therefore the standard works commonly refers to the following terms:
- Resource Owner
The End-User of your application (can also be a technical entity e.g. another
service) - Client
An application which attempts to access a users ressources - Ressource Server
The server hosting the ressources - Authorization Server
The server authenticating users, issuing and validating access tokens to registered clients
This would be keycloak in our case
There are multiple grant types supported by OAuth 2.0 to authenticate and authorize users.
The three most important grants are briefly discussed in the following sub sections:
- Authorization Code grant
- Refresh Token grant
- Client Credentials Grant
Authorization Code grant
1. The client application redirects the user to the authorization server's authorization
endpoint, typically through a web browser.
2. The user authenticates with the authorization server and grants permissions to the
client application.
3. Upon successful login the authorization server redirects the user back to the client
application's redirect URI with an authorization code.
4. The client application exchanges the authorization code for an access token by sending
a POST request to the authorization server's token endpoint, along with its client-id and
the authorization code.
5. The authorization server validates the authorization code and client-id and issues an
access token to the client application.
6. The client application can now use the access token to access protected resources on
behalf of the user.
Refresh Token grant
When a user authorizes a client application to access their resources, as seen in the
authorization code grant, the authorization server issues both an access token and a refresh
token. The refresh token is used to obtain a new access token when the current one expires.
1. Access tokens have a limited lifespan for security reasons. When an access token
expires, the client application can no longer use it to access the user's resources.
2. When the client application attempts to use an expired access token to access a
protected resource, the resource server responds with an error indicating that the token
has expired.
3. The client application then sends a request to the authorization server's token endpoint,
including the refresh token in the request body, along with its client credentials.
4. The authorization server validates the refresh token and checks if it's still valid and
associated with the client application.
5. If the refresh token is valid, the authorization server issues a new access token to the
client application, typically along with a new refresh token. The new access token can
then be used to access the user's resources, and the cycle continues.
Client Credentials grant
This last grant is suitable for server-to-server communication where the client application
acts on its own behalf, without needing access to a user's resources. Therefore the grant
does not involve any user interaction. Instead an access token for a service registered as a
client is issued.
1. The client application sends a POST request to the authorization server's token
endpoint, including its client credentials (client ID and client secret) in the request body.
2. The authorization server verifies the client credentials and issues an access token
directly to the client application.
3. The client application can now use the access token to access protected resources on
its own behalf, without involving any user interaction.
OpenID Connect
As if this is not enough another protocol is just as important as OAuth 2.0.
OpenID Connect is an authentication protocol built on top of the OAuth 2.0 authorization
framework.
The differentiation between the two terms is the proof of identity (atuthentication)
and the right to access a specific resource (authorization). OIDC provides a standardized
way for users to authenticate themselves to web applications without needing to expose
their passwords.
OpenID Connect enables single sign-on (SSO) capabilities, allowing users
to access multiple applications with a single set of credentials. It's widely used for identity
federation and interoperability between different identity providers and service providers on
the web.
On a technical level this means OIDC provides additional flows, as grants are called in this
standard and an additional token present for the OAuth 2.0 grants described before.
SSO
Various scenarios for single sign-on are covered with the help of OIDC.
A well known one is the popular "Sign in with... " option on websites.
This scenario can be used to generally explain what OIDC allows users to do.
ID tokens
ID tokens play a crucial role in OpenID Connect by providing client applications with
standardized user identity information. It is another JSON Web Token (JWT), just like the
access and refresh tokens from OAuth 2.0, that contains identity information about the
authenticated user.
It's typically issued by the identity provider (authorization server) during
the authentication process. The ID token provides the client application with basic user
information, such as user ID, name, and other crucial user information, allowing the
application to personalize the user experience and make authorization decisions based on
the given information.
The ID token is simply returned by the authorization server together with the access token,
so the two only differ in content and purpose.
User Profile
In OpenID Connect (OIDC), the user profile endpoint is a standard endpoint provided by the
identity provider (authorization server) where client applications can retrieve additional user
profile information beyond what is provided in the ID token. This endpoint allows client
applications to access a richer set of user attributes or details that may not be included in the
ID token.
The beauty about this endpoint is that the access is controlled via the protocol we already
know, OAuth 2.0 so that the identity provider basically becomes the resource server for the
user profile.
SAML 2
After going deep into the details and most used keywords of OAuth 2.0 and OpenID Connect
one could argue this is enough functionality for a single IAM server but Keycloak supports
another although much frequently used protocol with SAML 2 (Security Assertion Markup
Language).
SAML 2 is an XML-based standard for exchanging authentication and authorization data
between identity providers and service providers. It enables single sign-on (SSO)
capabilities across different domains or systems.
With SAML, users can authenticate once with an identity provider and gain access to multiple service providers without needing to log
in again. SAML 2.0 is widely used in enterprise environments and federated identity
management systems to enable secure access to various applications and services.
To briefly summarize SAML 2 can be used instead of OpenID Connect so most identity
providers only provide one of the two protocols with OIDC being far more popular nowadays.
User federation
Taking a step back from the protocols implemented by Keycloak to be an IAM server and
looking at the source of the identities when using Keycloak as the identity provider we are
confronted with choosing a user federation for our users.
The term user federation refers to the practice of integrating and centralizing user identities
and authentication mechanisms across multiple systems or domains.
Keycloak provides multiple implementations for connecting an existing user federation but is
also capable of using its already connected database for the purpose of identity
management and authentication.
Her is a list of implementations provided by Keycloak:
- Kerberos
- LDAP
- Active Directory
- Red Hat Directory Server
- Tivoli
- Novell eDirectory
- generic LDAP - Integrated database
Why to choose Keycloak as an IAM server
The protocols and setups explained so far are generic although we listed the user federation
capabilities of Keycloak in particular there are tons of projects, Software as a service
solutions, libraries to built IDPs, implement them with your application acting as resource
server and other ways to follow and of course there is no single solution as each decision in
software engineering is a trade off highly dependent on the circumstances.
However there are some arguments for Keycloak which are often involved in such trade offs,
which should be made when looking into it.
Provided functionality
As described before Keycloak implements all of the standard protocols we looked into. And if
one would start to zoom into these and look into the different signature algorithms, the multi
realm features and account management console it becomes clear that it is far more
capable then most other existing solutions.
To mention the top three features you might not be aware of:
OSS with a strong backup
The project has not only been around for ages but has been backed by Red Hat from the
start.
We will dive a bit into the project history as well though the quick summary is that the
support from Red Hat has increased even though Keycloak is not the direct base of a
commercial product - at least not anymore. Additionally the popularity for the project with
>19.200 stars on GitHub and a sheer endless number of public guides, community provided
extensions and libraries integrating with Keycloak speaks for itself.
So a strong community and several active project maintainers paid by Red Hat all together
do a great job in moving the project forward.
Customization
The most amazing part of it: Customization.
Everything explained up until this point is either highly configurable via the admin console
keycloak provides or even via a set of service provider interfaces which can be overwritten in
- Account console
Bundled web application which allows users to manage their OIDC user profile - Simple, cloud native self hosting
A simple immutable docker image allows a deployment everywhere you like
This is a topic the project aims for as it is an incubator project of the Cloud Native
Computing Foundation (CNCF) - Performance
At open200 we run a server for ca. 70 users (heavily used) with 1vCPU and 2GB
RAM
At the moment (v23) a new high availability mode is available as preview feature
Java and provided as a jar file. Additionally the look and feel can be completely customized
by providing HTML, java-script and CSS.
A look behind the curtain
With customization options being mentioned in the last section it makes sense to dig a little
into how Keycloak is built.
The project has a long history dating back to its initial release in 2014, since then the project
has evolved from a Wildfly (JBoss) based architecture to a Quarkus based distribution.
The transformation the codebase alone required was well covered in a talk we gave at the
Java Meetup Vienna in November 2023.
Today the project is not only compliant with many standards but also provides its own set of
APIs and SPIs to use for easier integration, extension or modification of Keycloak's
functionality. This is a comprehensive list of the most used ones in our experience. An in
depth guide on how to implement some customizations can be found in another blog article
by Martin Pfeffer.
Admin REST API:
As the name says a RESTful API for interacting with Keycloak, there is an official java
wrapper for it.
It provides endpoints for creating, updating, and deleting realms, users, roles, clients, and
other resources, as well as performing administrative tasks like user authentication and
token revocation.
Account Management API:
This API allows users to manage their own accounts, including updating profile information,
changing passwords, and managing session settings.
It is the backbone of the account console and can be used to provide a self built account
console if wanted.
Authorization Services API:
The Authorization Services API enables developers to implement fine-grained access control
policies and authorization mechanisms in their applications.
It provides endpoints for evaluating permissions, enforcing access policies, and managing
authorization resources like permissions, policies, and policy associations, this is mainly
based on another standard called UMA 2.0 (User-Managed Access).
User Federation SPI:
Keycloak provides a Service Provider Interface (SPI) for integrating with external identity
providers and user stores.
This SPI allows developers to extend Keycloak's user federation capabilities by
implementing custom user federation providers similar to interact with an existing user base
of any kind.
Event Listener SPI:
The Event Listener SPI allows developers to listen for and handle events generated by
Keycloak, such as user authentication, user registration, and token issuance.
One can implement custom event listeners to perform additional actions or integrate with
external systems based on Keycloak events.
An outlook of what the future brings
The Keycloak project is currently working on three relevant topics which might make it even
more interesting for some people out there, as it will provide more stability, flexibility and
scalability with those three topics to come.
Declarative User profile
A feature currently in preview in Keycloak is the declarative User profile which allows
administrators to define a set of attributes or claims that should be included in the user's
profile information without requiring additional client-specific configuration.
This feature simplifies the process of managing user profile information across multiple clients or
applications by centralizing attribute definitions at the realm level.
The beauty in Keycloak is that managed by the server the profile is automatically extended
across all the APIs and UIs.
So e.g. the account console, so a new attribute e.g. for storing the
users favorite Ice cream becomes available as (dependent on the configuration) editable
new attribute in their account console.
Active-Passive Sync
In Keycloak v23 a new blueprint for running an active-passive multi-site setup was
published.
The team behind Keycloak emphasized before that scalability is a top priority on their
roadmap and the setup they tested. Especially they worked on being "fully supported" in the
next few versions allowing a basically infinite scalability with fault tolerance.
New standards
As OAuth 2.0 is getting a minor update with OAuth 2.1 being finalised the support of this
latest standard is already under implementation in Keycloak. This does not only make up for
a bullet proof future but also allows people with high security standards to start of with the
latest standards available if one was to start a new project with a fresh instance of Keycloak
now.
Keycloak is key for modern access management
In summary, this blog post serves as a comprehensive guide to Keycloak and access
management (IAM) solutions in the modern web. We took a look at essential topics such as
OAuth 2.0, OpenID Connect, SAML 2, the idea of a user federation, but also went into the
specific features and capabilities of Keycloak. I hope I was able to highlight Keycloak's
various APIs, its architecture, and customization options, as well as upcoming features like
the declarative user profile.
Sources:
OAuth 2.0 links:
https://datatracker.ietf.org/doc/html/rfc6749
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-14
OpenID connect links:
https://openid.net/developers/how-connect-works/
https://infosec.mozilla.org/guidelines/iam/openid_connect.html
SAML links:
https://auth0.com/intro-to-iam/what-is-saml
UMA 2.0 links:
https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html
Keycloak links:
https://www.keycloak.org/docs/latest/authorization_services
https://www.keycloak.org/docs/latest/server_admin/
https://www.keycloak.org/docs/latest/securing_apps/
https://www.keycloak.org/docs/latest/release_notes/
