Secure Your APIs: OAuth2 and JWT for Beginners - The JetBrains Blog

Kotlin

A concise multiplatform language developed by JetBrains

Follow

Follow:

X X

RSS RSS

Visit the Kotlin Site

Backend<br>News<br>Tutorials<br>Secure Your APIs: OAuth2 and JWT for Beginners

Alina Dolgikh

This tutorial was written by an external contributor.

Mdu Sibisi

Mdu Sibisi is an Oracle-certified software developer and blogger with over ten years of experience working primarily with object-oriented languages. He has been writing about technology for more than eight years, focusing on making complex topics easier to understand. Mdu is passionate about accessible developer education, clean code, and creating content that helps developers learn and grow.

Website | Twitter

Repository with the companion code for the tutorial

Go to GitHub

APIs are frequent targets for bad actors since they expose data and functionality. Securing them while maintaining usability is often one of the most challenging and time-consuming parts of API development. OAuth 2.0 and JSON Web Tokens (JWT) help make these processes more manageable and reliable. They allow developers to represent and verify identity and manage access by safely transmitting claims and enabling delegated authorization.

This article discusses these technologies and the most efficient ways you can use them to secure your Spring Boot-built APIs and backends. If you’re interested in a coroutine‑driven solution, a companion tutorial using Ktor is also planned and will be published soon.

OAuth2 and JWT Primer

OAuth2 and JWT(s) aren’t competing technologies. They’re complementary pieces of the puzzle, with one handling the delegation of authorization and the other serving as the compact, verifiable token format that carries secure information.

Authentication vs. Authorization

Authentication verifies identity (who you are), usually through credentials like passwords, tokens, or certificates. JWTs can carry identity information and act like a form of ID once issued. Roles and other claims within a JWT are then used for authorization.

Authorization helps control what a user has access to (what they can do). This includes the scopes or resources that they can "touch" and how those permissions are managed. In a system that uses OAuth2 and JWT, the access badge is bundled into your ID card. OAuth2 oversees and manages this process.

The Role of OAuth2

OAuth2 is a framework for delegated access. Instead of sharing passwords directly, users grant applications a token that represents their permissions. This means that your backend (acting as a Resource Server) doesn’t have to issue tokens. Instead, it trusts and validates the ones coming from the Authorization Server within OAuth2’s framework. This decoupling of duties allows you to simplify your APIs while reducing security risks and ensuring all tokens follow a clear, consistent, centralized policy.

You don’t have to worry about implementing user logins or browser redirects within your API. As far as validation and authorization are concerned, your backend or API’s job is to receive the Bearer Token, authenticate the signature, check expiration, and enforce scopes/roles.

Your API just checks badges; it’s not responsible for printing them. So how do JWTs fit into the equation?

What Is a JWT?

A JWT is a small, web-friendly piece of text (string) that securely transports information between systems. Their compactness makes them easy to pass around in HTTP headers or URLs. Each token uses Base64URL encoding, making them safe to include in query strings or headers.

JWTs are signed (and sometimes encrypted), so that recipients can verify that they weren’t tampered with. They’re also self-contained, carrying details like user ID, roles, or permissions. These elements (especially self-containment and signing) allow for stateless authentication without Session Storage. This means that you don’t need a database or cache to track active sessions. It also encourages fewer lookups and less infrastructure complexity, which reduces your system’s overhead.

JWTs have a very simple, standardized structure made up of three parts, separated by dots:

The Header contains metadata about the token, such as the type (JWT) and the signing algorithm (HS256, RS256).

The Payload features the claims, which are statements about the user or system (like user ID, roles, or token expiry).

The Signature is a cryptographic signature created using the header, payload, and a secret or private key. This ensures the token has not been tampered with.

The basic structure of a JWT looks like this:

xxxxx.yyyyy.zzzzz

A real-world Base64URL-encoded token typically resembles the following:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9<br>.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ<br>.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

When OAuth2 meets JWT

There are four key roles in OAuth2’s implementation:

Resource Owner: The entity (usually the user)...