Seamless Migration to Keycloak: Insights into Transitioning from Spring Authorization Server
Tags: keycloak, iam, spring, migration
Published: 2024-03-31 22:26:44

Transitioning between authorization solutions is often a strategic move. Here we dive into the journey from Spring Authorization Server to [Keycloak](https://www.keycloak.org) – two prominent players in the realm of identity and access management (IAM)

---

In 2020, Spring decided to deprecate "[Spring Security OAuth](https://spring.io/projects/spring-security-oauth)" and announced an [End-of-Life as end of May 2022](https://spring.io/projects/spring-security-oauth#support). Back then, we started to think about an alternative to Spring. Although Spring announced back the return of Spring Security OAuth in [Spring Authorization Server](https://spring.io/projects/spring-authorization-server), the earlier is poor in features compared to Keycloak and its strong community. There could be many reasons driven by evolving security needs, scalability requirements, or for enhanced user experience to device for Keycloak. 

Starting on the journey of transitioning from Spring Authorization Server to Keycloak is quite the undertaking, isn't it? 👀 
But fear not, because I'm here to guide you through it! Recognizing the complexity of this move, I've decided to break it down into a series of articles, tackling each challenge along the way to ensure a smooth transition 🤝.


You might be wondering, **why go through all this trouble if both are based on [Auth2.0 standard](https://datatracker.ietf.org/doc/html/rfc6749)?** Well, despite the popularity of both Spring Authorization Server and Keycloak, detailed migration guides are surprisingly scarce. Each has different URLs, slightly difference in payload and the most important is the missing OpenID Connect (OIDC) in Spring Security OAuth which makes it harder to have the easy move you expect (e.g. using the default OIDC broker in Keycloak). That's where I come in – to provide you with a roadmap for success 👨‍🎓

Before we dive into the nitty-gritty details, let's make sure we're all on the same page. Understanding the basics of Identity and Access Management (IAM) is key. If terms like OAuth 2.0, authorization code flow, refresh token flow, and OpenID Connect (OIDC) sound like a foreign language to you, Just Google it. I am sure you'll find many resources for that. Building a solid understanding of these fundamentals will set the stage for a smoother migration journey. So, are you ready to get started? Let's do this! 🚀


**Getting started**
When it comes to tackling big tasks like this, I'm a big advocate for starting small and taking things one step at a time. This approach allows for learning from mistakes and making necessary adjustments along the way – it's all about that iterative process!

---
So, _where do we begin?_ 
Well, let us assume the current authorization server as simple as below:
![spring authorization server diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kzdp1d4whqgm3qfovct5.png)
The authorization server depends on two services, one for the user profile and another that stores the user credentials. 

It's crucial to maintain a seamless user experience during migration. Users shouldn't need to re-login for new tokens from Keycloak or transfer data between data sources. This applies to resource servers too.

To ensure this, we need a traffic-controlling gateway and careful management of client migration. Instead of big moves, migrating client by client minimizes the risk of full outages in case of failures.

Based on that, Here is -_in abstract_- the new design:
![keycloak and spring authorization server](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9n3p8um56vratigolo2l.png)

In below articles, I'll cover some topics to achieve a smooth migration: 
- [Brokering non-OIDC OAuth 2.0 identities] (https://dev.to/mohammedalics/seamless-migration-to-keycloak-non-oidc-oauth-20-broker-58a6) to solve absence of OIDC in Spring Security OAuth.
- [Authorization Code flow migration](https://dev.to/mohammedalics/seamless-migration-to-keycloak-authorization-code-flow-5ehm) and retain OAuth Clients and Resource Servers Untouched 
- [Refresh token migration](https://dev.to/mohammedalics/seamless-migration-to-keycloak-refresh-token-4m4f) and the same, OAuth Clients untouched.
- The migration of refresh token grant type can't be completed without utilizing the [Token Exchange in our OAuth 2.0 custom identity provider](https://dev.to/mohammedalics/seamless-migration-to-keycloak-token-exchange-4b7p) described in the above article. 

Beside that, there are some selected topics where I found it very useful to share. 
- [Optimized Keycloak build](https://dev.to/mohammedalics/optimized-keycloak-build-4gep): Creating a suitable Docker file for Keycloak based on your setup
- [Ensure Keycloak stays within the internal network while exposing only its APIs publicly](https://dev.to/mohammedalics/securing-keycloak-configuring-admin-access-within-your-private-network-4f1g)
- [Use maven shade plugin to include SPIs third-party libraries in the same SPI JAR](https://dev.to/mohammedalics/optimized-keycloak-spi-deployment-using-maven-shade-plugin-1ee6)
- Use [Terraform to configure a custom identity provider] (https://dev.to/mohammedalics/custom-identity-providers-in-keycloak-with-terraform-a-step-by-step-guide-81h)
- For Datadog users, A guide to [integrate Keycloak with Datadog](https://dev.to/mohammedalics/integrating-keycloak-with-datadog-enabling-keycloak-traces-in-kubernetes-using-datadog-apm-1563)

I hope it will help you!