JWT and OAuth 2.0 with Spring Boot REST APIs

1. JWT and OAuth 2.0 — The Big Picture

A typical enterprise microservices architecture uses an Authorization Server to authenticate users and issue access tokens. The frontend sends the access token to an API Gateway and protected microservices. Spring Security Resource Server validates JWT access tokens and converts their claims into authenticated principals and authorities.

2. Authentication vs Authorization

Authentication

Authentication answers:

Example:

username = srikanth
password = ********

The authentication system verifies that the credentials belong to the user.

Authorization

Authorization answers:

Srikanth
   |
   ├── READ orders       ✓
   ├── CREATE orders     ✓
   ├── DELETE orders     ✗
   └── ADMIN operations  ✗

3. What is JWT?

JWT = JSON Web Token.

A JWT is a compact token containing claims about a subject. It is digitally signed so that a Resource Server can verify its integrity and origin.

xxxxx.yyyyy.zzzzz

JWT has three parts:

HEADER.PAYLOAD.SIGNATURE

3.1 JWT Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-2026-01"
}

3.2 JWT Payload

{
  "sub": "1001",
  "username": "srikanth",
  "roles": ["USER"],
  "scope": "orders.read orders.write",
  "iss": "https://auth.company.com",
  "aud": "order-service",
  "iat": 1723980000,
  "exp": 1723983600
}

These properties are called claims.

3.3 JWT Signature

For an asymmetric algorithm such as RS256, the Authorization Server signs the header and payload using a private key.

signature =
    Sign(
       header + "." + payload,
       privateKey
    )

The Resource Server verifies the signature using the corresponding public key.

3.4 JWT is Not Normally Encrypted

The signature protects integrity and authenticity. It does not provide confidentiality.

4. What is OAuth 2.0?

OAuth 2.0 is an authorization framework. It allows a client to obtain an access token and use that token to access protected resources without directly handling the user's password.

OAuth2 Roles

Common Authorization Server / Identity Provider choices include Keycloak, Auth0, Okta, Microsoft Entra ID and Spring Authorization Server.

5. JWT vs OAuth2

6. Example Spring Boot Microservices System

Consider an e-commerce application:

7. Spring Boot Resource Server

Suppose the Order Service is a protected REST API.

Maven Dependencies

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

application.yml

server:
  port: 8082

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.company.com

The issuer-uri tells Spring Security which Authorization Server issued the tokens. Spring Boot/Spring Security can use the issuer metadata to discover the public signing keys and validate JWTs.

SecurityConfig

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(
            HttpSecurity http) throws Exception {

        http
            .csrf(csrf -> csrf.disable())

            .authorizeHttpRequests(auth -> auth

                .requestMatchers("/public/**")
                .permitAll()

                .requestMatchers(HttpMethod.GET, "/orders/**")
                .hasAuthority("SCOPE_orders.read")

                .requestMatchers(HttpMethod.POST, "/orders/**")
                .hasAuthority("SCOPE_orders.write")

                .anyRequest()
                .authenticated()
            )

            .oauth2ResourceServer(
                oauth2 -> oauth2.jwt()
            );

        return http.build();
    }
}

Order Controller

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping
    public List<String> getOrders() {
        return List.of(
            "Order-1001",
            "Order-1002"
        );
    }

    @PostMapping
    public String createOrder() {
        return "Order created";
    }
}

Calling the API

GET /orders
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Spring Security extracts the Bearer token, validates it and creates an authenticated SecurityContext before the controller is executed.

8. JWT Validation Flow

401 vs 403

9. OAuth Scopes

Suppose the JWT contains:

{
  "scope": "orders.read orders.write"
}

Spring Security commonly maps OAuth scopes to authorities using the SCOPE_ prefix.

orders.read
      ↓
SCOPE_orders.read

Therefore this works:

.requestMatchers(HttpMethod.GET, "/orders/**")
.hasAuthority("SCOPE_orders.read")

And:

.requestMatchers(HttpMethod.POST, "/orders/**")
.hasAuthority("SCOPE_orders.write")

10. Roles vs Scopes

A JWT can contain both:

{
  "sub": "1001",
  "roles": ["ADMIN"],
  "scope": "orders.read orders.write"
}

Custom Role Authority

If your Authorization Server puts roles in a custom claim, configure a JWT authority converter appropriate to that claim.

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {

    JwtGrantedAuthoritiesConverter authorities =
            new JwtGrantedAuthoritiesConverter();

    JwtAuthenticationConverter converter =
            new JwtAuthenticationConverter();

    converter.setJwtGrantedAuthoritiesConverter(authorities);

    return converter;
}

The exact converter configuration depends on whether your provider exposes roles in roles, realm_access.roles, groups or another claim.

11. Accessing the Current User

@GetMapping("/me")
public Map<String, Object> me(
        @AuthenticationPrincipal Jwt jwt) {

    return jwt.getClaims();
}

Or:

@GetMapping("/me")
public String currentUser(
        @AuthenticationPrincipal Jwt jwt) {

    return jwt.getSubject();
}

If the token contains:

{
   "sub": "1001"
}

then jwt.getSubject() returns 1001.

12. OAuth2 Authorization Code + PKCE

For browser and mobile public clients, Authorization Code with PKCE is a key OAuth2 flow.

Why PKCE?

PKCE protects the authorization-code exchange against interception of the authorization code.

code_verifier

        ↓ SHA-256

code_challenge

The client initially sends the code_challenge. Later it sends the code_verifier. The Authorization Server verifies that the verifier produces the original challenge.

13. OAuth2 Client Credentials Flow

This is especially important for microservice-to-microservice communication where there is no human user.

Example:

spring:
  security:
    oauth2:
      client:
        registration:
          payment-service:
            provider: company-auth
            client-id: order-service
            client-secret: ${ORDER_SERVICE_SECRET}
            authorization-grant-type: client_credentials
            scope:
              - payment.read

        provider:
          company-auth:
            token-uri: https://auth.company.com/oauth2/token

Conceptually:

Order Service
     |
     | client_credentials
     ▼
Authorization Server
     |
     | JWT Access Token
     ▼
Order Service
     |
     | Bearer JWT
     ▼
Payment Service

14. Access Token vs Refresh Token

Example:

Access Token  = 15 minutes
Refresh Token = several days (depending on policy)

15. JWT with RSA / Asymmetric Keys

A strong microservices design is to let only the Authorization Server hold the signing private key.

The services only need the public key to verify signatures. They should not possess the private signing key.

16. JWK and JWKS

JWK = JSON Web Key.

JWKS = JSON Web Key Set, a collection of public keys.

Example endpoint:

https://auth.company.com/oauth2/jwks

The JWT header can contain a kid value:

{
  "alg": "RS256",
  "kid": "key-002"
}

The Resource Server can select the matching public key from the JWKS.

17. Key Rotation

Suppose the current key is:

kid = key-001

Later the Authorization Server introduces:

kid = key-002

JWKS may temporarily contain both:

key-001
key-002

New tokens use key-002, while Resource Servers can continue validating older tokens signed with key-001 until the old key is retired according to the organization's rotation policy.

18. JWT vs Session Authentication

Traditional Session

JWT-Based Access Token

JWT access tokens can enable stateless access-token validation because the Resource Server can validate the token without looking up a server-side HTTP session for every request.

19. API Gateway Authentication vs Microservice Authorization

A common architecture is:

For stronger defense in depth:

The downstream service should not blindly trust security headers supplied by an upstream gateway. It should establish its own security context and perform authorization appropriate to the resource it owns.

20. OAuth2 vs OpenID Connect

OAuth2 primarily addresses authorization.

OpenID Connect (OIDC) adds an identity/authentication layer on top of OAuth2.

OIDC introduces concepts such as:

• ID Token
• UserInfo endpoint
• openid scope

Access Token vs ID Token

21. Custom JWT Authentication vs OAuth2

Suppose you implement your own login endpoint and generate a JWT:

@PostMapping("/login")
public TokenResponse login(...) {

    // authenticate username/password

    String token = Jwts.builder()
        .subject(user.getUsername())
        .claim("role", user.getRole())
        .issuedAt(new Date())
        .expiration(expiration)
        .signWith(privateKey)
        .compact();

    return new TokenResponse(token);
}

This is JWT-based authentication.

22. Complete OAuth2 + JWT Microservices Architecture

23. Mapping This to a Typical Spring Boot Microservices Project

A system with an API Gateway, Orchestrator and Auth Service can evolve into the following design:

With OAuth2/OIDC, the Auth Service can be replaced or supplemented by a dedicated Authorization Server/Identity Provider. The application services can become OAuth2 Resource Servers.

24. Should You Build Your Own Authorization Server?

For enterprise systems, avoid implementing OAuth2 security protocols from scratch unless there is a strong architectural reason.

Common established choices include:

If you need to operate your own Authorization Server, Spring Authorization Server is one option. Note that current Spring Authorization Server releases have their own Java/Spring version requirements, so verify compatibility before selecting it for a Java 11 application.

25. Production Security Checklist

26. Complete Mental Model

27. Interview-Ready Answer

The key distinction

OAuth2
  ↓
How authorization/access is granted

JWT
  ↓
How the access token can be represented

Spring Security Resource Server
  ↓
How the API validates the token

Scopes / Roles
  ↓
How API authorization decisions are made

28. Quick Revision Cheat Sheet