Access Token and OAuth2 Pattern – Securing Java APIs

Introduction

Securing APIs in distributed systems is no longer optional. As applications scale and services proliferate, managing authentication and authorization becomes increasingly complex. That’s where the Access Token and OAuth2 pattern comes into play.

In this tutorial, we'll explore how to implement OAuth2 to protect Java APIs using access tokens, real-world examples, and best practices.

🔍 What is the Access Token and OAuth2 Pattern?

Core Intent

The goal of the pattern is to secure communication between clients and APIs using access tokens issued via OAuth2 authorization flows.

Participants

• Resource Owner – The user who owns the data
• Client Application – The frontend or service requesting access
• Authorization Server – Issues tokens after authenticating users
• Resource Server (API) – Validates and processes requests

[Client] → [Authorization Server] → [Access Token]
[Client] → [Resource Server with Access Token] → [Protected Resource]

🧑‍💻 Real-World Use Cases

• Securing REST APIs for mobile/web apps
• Token-based login in microservices (e.g., Spring Boot + Keycloak)
• Delegated authorization (e.g., allow Google login on your app)
• Protecting admin dashboards and internal APIs

🚀 Common Implementation Strategies in Java

1. Spring Security with OAuth2 Resource Server

@EnableWebSecurity
public class SecurityConfig {

  @Bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
      .authorizeHttpRequests(authz -> authz.anyRequest().authenticated())
      .oauth2ResourceServer(oauth2 -> oauth2.jwt());
    return http.build();
  }
}

2. Using Keycloak

• Configure Keycloak realm, client, and user
• Add application.properties:

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/demo

✅ Pros and ❌ Cons

Pros

• Decouples authentication from services
• Scalable and standards-based
• Delegated access without password sharing

Cons

• More moving parts to manage (token storage, rotation)
• Requires HTTPS (tokens can be intercepted otherwise)
• Complexity increases with custom grant types

🚨 Anti-Patterns to Avoid

• Storing tokens in local storage (XSS risk)
• Not validating token signature and expiry
• Exposing too many scopes or weak tokens

🔁 Comparison with Similar Patterns

Pattern	Purpose
Basic Auth	Sends credentials per request (less secure)
Session-based Auth	Works well for web apps, not APIs
OAuth2 + Access Tokens	Best for decoupled services and APIs

🧩 Refactoring Legacy Code

If you're using basic auth or session-based login:

1. Introduce OAuth2 Authorization Server (e.g., Keycloak or Auth0)
2. Replace login/session logic with token validation
3. Use Spring Security filters to decode tokens

💡 Best Practices

• Use short-lived access tokens + refresh tokens
• Prefer asymmetric encryption (RS256) for tokens
• Validate issuer, audience, scopes on API side
• Use HTTPS for all requests
• Rotate signing keys periodically

🧠 Real-World Analogy

Imagine a movie ticket system:

• You get a ticket (token) at the box office (auth server)
• You show it at the entrance (API)
• The staff checks date, time, and seat (claims, expiry, audience)

No need to tell your name or share your bank account—just present the ticket.

🆕 Java Version Relevance

• Java 17+ recommended for modern Spring Boot support
• Records can be used for clean JwtPayload classes
• Sealed interfaces can improve type safety in grant flow models

✅ Conclusion & Key Takeaways

OAuth2 and Access Tokens are indispensable for securing Java microservices and APIs. Whether you're integrating with Google, Facebook, or custom auth servers, this pattern provides scalability, extensibility, and security.

TL;DR

• Always validate token signature and claims
• Use refresh tokens and key rotation
• Delegate auth to centralized services (Auth0, Keycloak)

❓FAQ

1. What is the difference between OAuth2 and OpenID Connect?
   OAuth2 provides authorization. OIDC is a layer on top for authentication.

2. Can I use OAuth2 without JWT?
   Yes, though JWT is the most common format for access tokens.

3. Is OAuth2 secure for mobile apps?
   Yes, if implemented with PKCE and HTTPS.

4. What’s the best tool to implement OAuth2 in Java?
   Spring Security with Keycloak is the most popular choice.

5. Should I store access tokens in cookies?
   Only if they're HttpOnly, Secure, and not accessible via JS.

6. Do I need a database to use OAuth2?
   Not always. Some providers use in-memory or external token stores.

7. How long should access tokens live?
   Short (5–15 min). Use refresh tokens for re-authentication.

8. Can I revoke an access token?
   Yes. Most auth servers support revocation endpoints.

9. What is a Bearer token?
   A token passed in the Authorization header: Bearer <token>

10. Is OAuth2 suitable for internal APIs?
    Yes, especially when multiple services or teams are involved.