Keycloak - highly customisable auth server

I have recently been working with Keycloak as an identity solution for our project. Keycloak is an open source auth server written in Java distributed with Apache 2 license. In the past I have worked with Azure B2C, AWS Cognito and Identity Server 4. Compared with those, even though some are in different categories, I have been quite impressed with Keycloak. It has a good set of documentation and customisation options available making it suitable for any greenfield project as well as an existing application where you feel the need to upgrade your old authentication mechanism to Open ID Connect (OIDC).

DEMO

I've put together a demo that you can run with docker compose so that you can try out the features.

1. Get the source from here: Kayes-Islam / keycloak-demo
2. Run docker compose up --build.

This exposes three services, Keycloak on port 8080, and Angular SPA on port 4200 and an asp.net core web-api on 5000. Note that the Keycloak service takes half a minute or so to get up an running so wait for it to start up.

Open up the client app at http://localhost:4200. Click the Call API button without logging in and you'll see the web-api returning 401 un-authorized error. But if you login using the demo account below and then click "Call API" you'll see successful response with JSON data.
Demo User:
U: demo.user
P: P@ssw0rd

NOTE: If you are having an issue logging in check the console logs from the SPA. It should have an error entry that says "iat time too far in the past". "iat" is issued at time. This happens when your container's time is not in sync with your host machines time. This is an issue on WSL/WSL2 on windows, specially if you have a laptop that is set to sleep after inactivity, because when windows wakes up, it doesn't re-sync the time on the WSL.
FIX: Open WSL console on windows then run hwclock -s.

Features

Now that you've got a demo up and running, let's talk about a few reasons I would recommend anyone to consider Keycloak as an auth solution.

Easy to use admin portal

Keycloak has a great admin portal that is easy to configure out of the box. If you are running the demo, open up http://localhost:8080 and login as admin user to have a look around:
U: admin
P: admin

Here are a few screenshots of how I have configured the client-app:

Customizable Themes

From sing-up page to admin portal, you can customize pretty much any part of the UI using custom themes. Themes are developed using Freemarker Templates and it's all documented here.

Extensible with Service Provider Interfaces (SPIs)

Everything in Keycloak has been implemented using injectable providers. You can register custom implementations of the provider interfaces in Java, drop the jar file in the deployments directory and it's available to be configured. There are many extensible SPIs available in Keycloak, but below are two of the most important one's in my opinion:

Storage SPI

Do you have an existing user database that does not currently have OpenID Connect capabilities? Keycloaks User Storage SPI allows you to extend the storage and retrieval of user data. You basically extend the UserStorageProvider class and implement a bunch of interfaces in Java with methods such as getUserById(), isValid() etc. The benefits you get is an OIDC solution on top of your existing infrastructure, with all the capabilities that come with it such as OAuth2, discovery, user registration, client registration, account management, admin portal etc just to name a few. Here are the docs. I have recently worked on such a project to create a Storage SPI for existing user database and it works very well.

Authentication SPI

Using the authentication SPI you can create a custom challenge, add an extra authentication step, or replace the entire flow if that's what your requirement is. Maybe you are creating an auth solution is for the tradies. So when users sign up, you want them to enter a their trade license number. Maybe you want to validate the trade license every-time they log in to ensure it's not expired. You can implement all that using a custom Authentication SPI and configure it as part of the flows for your realm. See here for more.

LDAP and Kerberos integration

Although I haven't tried these features yet, they look really good on the documentation. These stood out to me at first glance because I have worked with some applications in the past that rely on Active Directory for authentication. Keycloak comes with an LDAP provider which is just an implementation of User Storage SPI. Therefore when configured can it retrieve user information or validate user credentials with Active Directory. See here for more info.

Keycloak also allows you to configure Kerberos authentication. Note that both LDAP and Kerberos integration are separate pieces, you can configure only one or both. This let's Keycloak deal with LDAP/Kerberos hand-shake providing an OIDC solution on top. I think this is a great separation to have since it frees your application, the resource server (back-end) and the client app (front-end), to be developed against the OIDC standard. That way you can just plug in the auth server. You may have one deployment of your application configured with your clients LDAP running in intranet with Active Directory, another perhaps deployed on cloud using social login, and another maybe with a different auth provider all together B2C/Cognito/Auth0. More info on Kerberos integration.

Configurable with a wide variety of databases

Since Keycloak works on top of JDBC, it can be configured to use any database that has JDBC driver, which is a wide range of databases, including Postgresql, SQL Server and MySql.

Authorisation services

In addition to the standards based protocols, Keycloak provides a number of additional features and one of these is authorisation services. It gives you fine grained control on permissions that can be allocated on resources from the admin console. These permissions are exposed to the resource server as a set of RESTful APIs. Docs here.

Account Management Console

Keycloak has a built in account management console that can be accessed by every logged in user. You could redirect users to their account management console from the client application where they can update their profile information, change password, check session history etc.

Having Keycloak provide the account management functionality is great since the OIDC provider is the custodian of this information. Like all other user interface elements in Keycloak, you can customise the Account Management Console anyway you like.

Support for wide range of external Identity Providers

If you want to provide users options to login with the popular platforms such as Facebook, GitHub etc, Keycloak supports a wide range of external identity providers including any provider that supports OpenID Connect.

Conclusion

So in conclusion I would highly recommend you check out Keycloak for the following project types:

• You are creating a new application and you need an identity solution.
• You have an existing application with and existing users database that is not OAuth2 or OpenID Connect and you'd like to create an OpenID Connect solution on top of the existing database.
• You want to create a multi-tenant application. Multi-tenancy can be achieved via realms or groups, based on your requirements.
• You host different instances of you application and would like to provide different types of Authentication for these instances based on your client requirements, eg. one with custom Storage SPI reading/writing to/from existing database, one with federated login with Microsoft and Google, One with simple username and password based authentication, etc.
• You need to provide windows integrated or Active Directory based authentication.