My Keycloak learning journey

Keycloak is an open-source identity provider. You can add authentication to applications and secure services with minimum effort. No need to deal with storing users or authenticating users. Keycloak provides user federation, strong authentication, user management, fine-grained authorization, and more. ~ Keycloak

I will share my path to learning Keycloak and the resources that helped me along the way. Maybe some material that I used will help you understand Identity and Access Management (IAM) and Keycloak, too.

It took me some time to learn and get going with Keycloak. I’m not that familiar with the Java ecosystem because some time has passed since my last Java project. So I might have had a harder time learning. But if you use Java on a daily basis, you’re in luck, since Keycloak is written in Java. I also want to emphasize that I’m still not done learning yet, but I feel confident deploying, extending, and integrating Keycloak.

Getting started with Keycloak

My Keycloak journey started in a customer project where we built a login theme for Keycloak and integrated it into our frontend applications. Sure this is only a tiny subset of what Keycloak has to offer but the initial resources are a good starting point for anyone. After visiting the website to find some basic information, some additional videos briefly show the power of Keycloak:

• Securing apps and services with Keycloak authentication | DevNation Tech Talk by Stian Thorgersen (Keycloak Project Lead)
• How to secure your Spring apps with Keycloak by Thomas Darimont @ Spring I/O 2019 by Thomas Darimont (Keycloak Maintainer)

Resources beyond the Keycloak docs: What is IAM?

I made an interesting observation about myself. When I started with Keycloak, the docs weren’t helpful at all. Luckily that changed, and now I think the docs are quite decent. Conversations with colleagues, who also came in contact with Keycloak, had the same issue. I learned that I had this strange relationship with the Keycloak docs because there was a gap between the information that the docs provide and my knowledge. The docs don't explain what IAM is or what OpenID Connect is and how its internals work. They expect you to know it.

I learned: There is the IAM sector and Keycloak as an identity provider application offering. The Keycloak docs focus on the important parts of deploying, managing, and adapting Keycloak. They expect you to know IAM fundamentals and the inner workings of related protocols.

For many people (including me) who jump into Keycloak, this might not be the case. So before the Keycloak docs are of any help to us, we have to build up some basic knowledge around IAM.

If you find yourself facing the same problem, it might be a good idea to take a step back and focus on the foundations of IAM before diving deeper into Keycloak. It makes sense to read about the IAM sector in general but also dive into the protocols you want to use. In my case, it is mostly OAuth2 & OpenID Connect (OIDC).

This raises the question of what IAM is all about. RedHat (who sponsors Keycloak) has a good article describing the IAM context:

Identity and access management (IAM) is a centralized and consistent way to manage user identities (i.e. people, services, and servers), automate access controls, and meet compliance requirements across traditional and containerized environments. ~ What is identity and access management (IAM)?

There is an awesome resource that bridges the gap between learning the basics and learning Keycloak. Stian, the creator of Keycloak, wrote a book last year about Keycloak. I think it is the perfect starting point. It explains the basics of the OpenID Connect protocol and shows how to use it with Keycloak. Furthermore, it touches on a ton of Keycloak features in short sections to show you what's possible. From there you can select the features that fit your requirements for your projects. After that, you can jump to the Keycloak documentation to get a deeper insight into how to use each feature.

One note while reading the book: OAuth2 – the foundation of OpenID Connect – is not the focus of the book. It covers the basics but in my case, it was not quite enough. So I recommend you have a look around for some blog articles that cover OAuth2 more deeply while reading the book.

Learning from Keycloak experts

Luckily at codecentric, we have some very talented people that are experts in IAM and Keycloak (looking at you, Sebastian Rose and Thomas Darimont). Having them around and the ability to ask them anything and learn from the experience they gathered in many customer projects boosted my knowledge.

I was able to attend a Keycloak Fundamentals workshop by Arne Strathmann. There we went over the Keycloak basics, and we worked with the (now old) JBoss CLI for configuring Keycloak. After that, we integrated it into other applications.

Some time later I participated in a meetup where Thomas explained how to extend Keycloak. Besides a great presentation with good simple examples and many learnings from his experience, there were more takeaways for me: Lately Thomas created a Keycloak Starter Repository. This is a great starting point or even boilerplate repo for starting a new Keycloak project. When he presented it, the repo was quite new and had a small baseline. I used this boilerplate for my own Keycloak setup. Over the years this repo got a ton of more config options. It is great that you can find so many working combinations there. Although when you start with Keycloak it might make sense to head to some of the first commits in the repo. There is only one setup in a simpler form. When you are ready to deploy Keycloak on scale, the latest updates might be for you.

Another thing I found is the Keycloak Extension Repository from Thomas. He developed quite a few Keycloak extensions. Maybe the extension you want to build is already in there! I found a lot of helpful ones, and it was a great inspiration source for my extensions.

I would also recommend you keep an eye on the Keycloak blog. There are not that many blog posts but new ones always provide some really helpful information. For example, in December last year, one blog post disclosed a security vulnerabilitiy.

First in the field experience

Equipped with all the learnings, I started to gain some experience building my Keycloak Docker image. With some baseline infrastructure I created on AWS (using VPC, ELB, ECS Fargate, RDS & SES), I was able to deploy and run my image. By now, there are also some open-source resources for Keycloak in AWS infrastructure: cdk-keycloak. After the deployment was complete, I started configuring Keycloak. This configuration includes creating your realm, adding clients to it, configuring log settings, plugins, realm settings, and providing your login flow and token contents. This config setup has to be done on a running Keycloak instance. You can apply your configuration either through the provided admin UI or the CLI. Since both options are a bit cumbersome, I used the keycloak-config-cli. It offers Configuration as Code via YAML or JSON configuration files for Keycloak and works great.

And that's pretty much it.

When you're using Terraform to create the infrastructure for Keycloak, there is the option to configure Keycloak with Terraform: Keycloak-Konfiguration mit Terraform

Conclusion

At first, Keycloak seemed complicated and rigid. But digging deeper into Keycloak I realized it has a lot to offer. There are tons of configuration options, and it is easily extendable.

But I also learned that there is a hidden cost attached to integrating Keycloak into your application landscape. Maintaining a Keycloak cluster in production takes quite some effort. Setting it up correctly and running updates with minimal user impact is not trivial. So before jumping into Keycloak just because it seems free, I would question that decision again.

A lot of competition in the IAM sector has arisen lately. Some provide SaaS offerings besides an open-source core. Others offer a managed Keycloak solution. Managed services have the benefit that we are able to focus on building and shipping our product.

The team behind Keycloak has understood that the IAM landscape evolves. Stian showed some insights into the roadmap in his Keycloak.X-Update blog post, as did the Keycloak.X blog post by Thomas und Sebastian. It feels like they are finally tackling some rough edges of Keycloak. This is great to hear, and I'm confident that it'll be easier working with Keycloak in the future, although it is important to note that this will take some time and lead to some breaking changes for currently running Keycloak clusters.

I'm curious about what tool will win the race and dominate the market in the future. Overall, Keycloak is still a very stable identity provider used by a ton of big companies.

I hope I was able to provide you with some helpful ideas and resources for learning Keycloak.

See ya ✌️