Why have we written a new JWT Library?

Earlier this year, I was assigned to work on a new Kotlin Multiplatform project for a banking client. This project had one particularity: it had strong security requirements.

Even though I had seen many security and cryptography concepts during college, I’d never had the chance to put them into practice. My first reaction was: I need to learn more about this.

While researching, a lot of topics started to appear, and it can quickly become hard to follow. Ciphers, Algorithms, Hashes, Tokens, Certificates, and the list goes on and on.

When searching for existing community libraries for the project, I quickly came across Cryptography-kotlin (https://github.com/whyoleg/cryptography-kotlin). It’s a robust and well-maintained library that provides many cryptographic APIs in the right way.

Quick advice: It’s important to note that when you work with cryptography, you shouldn’t try to reinvent the wheel. There are many existing tools that have already done the hard work, and all you need to do is link them to your project. Never try to implement cryptographic functions, hashes, or ciphers on your own.

Since I was eager to start playing with it, I started thinking about a “pet project” that I could use to practice. One of the most common use cases for cryptographic APIs is related to Authentication and Authorization—especially handling JWTs.

What is a JWT?

JWT stands for JSON Web Token. In short, it’s a compact, URL-safe way to represent content between two parties as a JSON object. This pattern uses many security-related concepts, such as a signature, which helps ensure that the content has not been tampered with.

It’s a widely adopted standard, and most languages have a library to handle them. Working with JWTs requires different cryptographic operations, such as base64 encoding, signing tokens, verifying integrity, etc.

It’s all well-documented in a series of RFCs, such as https://datatracker.ietf.org/doc/html/rfc7519.

The Pet Project

During my research into JWTs and community implementations, one thing that caught my attention was that many Android apps needing JWTs usually go down one route: JJWT. JJWT is a robust and battle-tested community library implemented to offer JWT capabilities to apps running on the JVM.

For Android developers, it’s a no-brainer—it’s a great fit and works perfectly for them. However, when your goal is to make your project run across multiple targets with Kotlin Multiplatform, its usage starts to become limited.

With all of that in mind, I started working on a “pet project” in my free time to fulfill my personal learning goals. My first idea was to build something that embraced the essence of Kotlin’s features while remaining “similar” to JJWT’s syntax. Making something that felt natural for Android developers would ease its adoption in KMP, as many features could be ported simply by updating imports.

At that point, I had no intention of making it public or turning it into a real library. It was just an experiment to practice cryptographic operations.

But later on, while working on the client project, I noticed that one of its requirements wouldn’t be fully supported by any existing community library. Hardware-backed cryptographic operations were a requirement, but the minimum Android version used by the client posed a limitation when compared to existing community implementations.

Existing libraries, like Signum, offered this feature. However, they enforced a higher minimum Android SDK, which would not work for them.

That was the inflection point for me. It made me realize that if I organized this pet project I was using to learn, and put a bit more effort into supporting this requirement, it could become something much more.

With that in mind, I started planning how to make it happen. I needed to figure out how to architect it to be flexible, yet capable of supporting the different needs that KMP developers might have. It needed to stay close to JJWT’s syntax while retaining the best of Kotlin’s semantics.

After an initial plan and a minimal implementation, I talked to the team. My initial suggestion was to turn it into a real library and transfer it to the Touchlab organization. Since we already have a strong history of maintaining KMP libraries, it was a perfect fit.

Introducing KJWT

As you probably guessed by this point in the post, KJWT is a JWT library for Kotlin Multiplatform applications. Our goal is for it to be simple to use, yet flexible enough to be adapted to different scenarios.

As of now, the project is still in its early stages, and we have a few ideas for new features and improvements. But the library is open, released, and already being used by real production clients.

If you are working with KMP and need JWT support, feel free to check it out at KJWT. If you have any feedback, ideas, improvements, or if you catch any bugs, feel free to open an issue or send us a message in the #touchlab-tools channel on the Kotlin Slack.