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 a helpful blog post regarding 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
The client application redirects the user to the authorization server's authorization endpoint, typically through a web browser.
The user authenticates with the authorization server and grants permissions to the client application.
Upon successful login the authorization server redirects the user back to the client application's redirect URI with an authorization code.
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.
The authorization server validates the authorization code and client-id and issues an access token to the client application.
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.
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.
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.
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.
The authorization server validates the refresh token and checks if it's still valid and associated with the client application.
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.
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.
The authorization server verifies the client credentials and issues an access token directly to the client application.
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. Here 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 is 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:
OpenID connect links:
SAML links:
UMA 2.0 links:
Keycloak links: