Skip to content

JWT Spring Boot Starter — Complete GitHub Wiki

Jump to bottom
Smit Roy edited this page May 23, 2026 · 1 revision

JWT Spring Boot Starter — Complete GitHub Wiki

Overview

jwt-spring-boot-starter is a reusable, production-oriented JWT authentication starter built for Spring Boot applications.

The project was designed to eliminate repetitive JWT boilerplate code that developers typically write in almost every backend application.

Instead of manually configuring:

  • JWT utilities
  • token validation
  • token parsing
  • authentication filters
  • Spring Security configuration
  • SecurityContext integration
  • bean registration
  • request interception

Developers can simply:

  1. Add the dependency
  2. Configure JWT properties
  3. Start using JWT authentication immediately

The starter automatically configures:

  • JwtService
  • JwtAuthenticationFilter
  • SecurityFilterChain
  • JWT validation flow
  • Spring Security integration

with minimal setup.

Motivation Behind The Project

JWT authentication is one of the most common authentication mechanisms used in modern backend systems.

However, implementing JWT repeatedly across projects creates a large amount of duplicated infrastructure code.

Typical JWT setup usually requires:

  • JwtUtil class
  • token validation logic
  • claims extraction
  • expiration handling
  • authentication filters
  • Bearer token parsing
  • Spring Security integration
  • SecurityContext configuration
  • route protection setup
  • excluded route management

This project was created to transform JWT authentication into a reusable plug-and-play dependency.

The goal is:

Reduce authentication boilerplate while maintaining flexibility and extensibility.

Architecture

High Level Flow

Incoming Request
        ↓
JwtAuthenticationFilter
        ↓
Extract Bearer Token
        ↓
Validate JWT
        ↓
Extract Claims
        ↓
Create Authentication Object
        ↓
SecurityContextHolder
        ↓
Protected Controller Access

Auto Configuration Flow

application.yml
        ↓
JwtConfigurationProperties
        ↓
JwtAutoConfiguration
        ↓
JwtSecurityConfiguration
        ↓
JwtAuthenticationFilter
        ↓
JwtService

Modules

The project currently consists of:

jwt-core

Framework-independent JWT utility engine.

Responsibilities:

  • token generation
  • token validation
  • claims extraction
  • refresh token support
  • token type handling

jwt-spring-boot-starter

Spring Boot integration layer.

Responsibilities:

  • auto configuration
  • Spring Security integration
  • JWT filter registration
  • route protection
  • request authentication
  • SecurityContext integration

Features

JWT Features

  • Access token generation
  • Refresh token generation
  • Claims extraction
  • Type-safe claim parsing
  • Token validation
  • Subject extraction
  • Access/refresh token detection

Spring Security Features

  • Automatic JWT filter registration
  • Stateless authentication
  • Bearer token parsing
  • SecurityContext integration
  • Request authentication
  • Protected route handling
  • Public route support

Developer Experience Features

  • Plug-and-play setup
  • Zero manual bean registration
  • Auto configuration
  • Extensible architecture
  • Override support
  • Lightweight design

Installation

Step 1 — Add GitHub Packages Repository

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/smitroy4/jwt-spring-boot-starter</url>
    </repository>
</repositories>

Step 2 — Add Dependency

<dependency>
    <groupId>com.smit</groupId>
    <artifactId>jwt-spring-boot-starter</artifactId>
    <version>1.0.2</version>
</dependency>

Configuration

application.yml

jwt:
  secret-key: mysupersecretkeymysupersecretkey123456
  access-token-expiration: 600000
  refresh-token-expiration: 604800000

Configuration Properties

Property Description
jwt.secret-key Secret key used for JWT signing
jwt.access-token-expiration Access token expiration time in milliseconds
jwt.refresh-token-expiration Refresh token expiration time in milliseconds

Quick Start

Generate Token

@RestController
@RequiredArgsConstructor
public class AuthController {

    private final JwtService jwtService;

    @GetMapping("/auth/token")
    public String token() {
        return jwtService.generateAccessToken(
            "101",
            Map.of("email", "admin@test.com", "role", "ADMIN")
        );
    }
}

Protected Endpoint Example

@RestController
public class UserController {

    @GetMapping("/user")
    public String user(Authentication authentication) {
        return "Authenticated User: " + authentication.getName();
    }
}

Authentication Flow Example

Step 1 — Generate JWT

GET /auth/token

Response:

eyJhbGciOiJIUzI1NiJ9...

Step 2 — Access Protected Endpoint

GET /user
Authorization: Bearer YOUR_TOKEN

Response:

Authenticated User: 101

JWT Authentication Filter

Overview

JwtAuthenticationFilter is responsible for:

  • intercepting requests
  • extracting Bearer tokens
  • validating JWTs
  • creating Authentication objects
  • storing authentication in SecurityContext

The filter extends:

OncePerRequestFilter

which guarantees:

One filter execution per request.

SecurityContext Integration

After successful validation:

SecurityContextHolder.getContext().setAuthentication(authentication);

is executed.

This allows authenticated user information to become available globally inside the Spring Security ecosystem.

Auto Configuration System

The project uses Spring Boot's:

META-INF/spring/AutoConfiguration.imports

mechanism.

This enables:

  • automatic configuration loading
  • no component scanning requirements
  • starter-based architecture

Included Auto Configurations

JwtAutoConfiguration

Registers:

  • JwtService
  • JwtConfigurationProperties
  • JwtAuthenticationFilter

JwtSecurityConfiguration

Registers:

  • SecurityFilterChain
  • JWT filter integration
  • protected route handling

Public Route Handling

Current implementation supports:

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

which allows:

  • login routes
  • token generation endpoints
  • public APIs

without requiring authentication.

Protected Routes

All non-public routes automatically require JWT authentication.

Example:

.anyRequest().authenticated()

Dependency Injection

The starter automatically provides:

JwtService

through Spring's dependency injection container.

No manual bean registration is required.

Extensibility & Override Support

The starter is designed around:

@ConditionalOnMissingBean

This enables applications to override default implementations.

Overriding JwtService

Applications can provide:

@Bean
public JwtService jwtService() {
    return new CustomJwtService();
}

The starter automatically backs off.

Overriding JwtAuthenticationFilter

Applications can fully customize authentication behavior.

Example:

@Bean
public JwtAuthenticationFilter jwtAuthenticationFilter(JwtService jwtService) {
    return new CustomJwtAuthenticationFilter(jwtService);
}

Overriding SecurityFilterChain

Applications may replace the default security configuration entirely.

Example:

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
    );
    return http.build();
}

Internal Package Structure

jwt-spring-boot-starter
│
├── config
│   ├── JwtAutoConfiguration
│   └── JwtSecurityConfiguration
│
├── properties
│   └── JwtConfigurationProperties
│
├── security
│   └── JwtAuthenticationFilter
│
└── META-INF/spring
    └── AutoConfiguration.imports

Technologies Used

Layer Technology
Language Java 21
Framework Spring Boot 4.x.x
Security Spring Security
JWT JJWT
Build Tool Maven
Distribution GitHub Packages
CI/CD GitHub Actions

CI/CD Pipeline

The project uses:

  • GitHub Actions
  • Maven build automation
  • automated dependency resolution
  • cloud-based build validation

The pipeline validates:

  • compilation
  • dependency resolution
  • Maven build integrity

on every push.

Publishing

Currently distributed through:

  • GitHub Packages

Future support planned for:

  • Maven Central

Current Limitations

Current version does not yet support:

  • role-based authorization
  • authorities extraction
  • Redis token blacklist
  • dynamic route exclusions
  • RSA signing
  • OAuth2 support
  • refresh workflow authentication

These are planned future improvements.

Roadmap

Planned Features

Security

  • Dynamic excluded routes
  • Role-based authorization
  • Authorities extraction
  • Custom annotations
  • Token revocation
  • Redis blacklist

JWT Enhancements

  • RSA support
  • Public/private key signing
  • Advanced claims validation
  • Multi-tenant JWT support

Developer Experience

  • Swagger/OpenAPI integration
  • Better exception handling
  • Startup logs
  • Enhanced configuration support
  • Metrics & monitoring

Enterprise Features

  • OAuth2 bridge
  • Distributed token revocation
  • Session synchronization
  • API gateway integration

Design Philosophy

The project follows several important principles:

1. Convention Over Configuration

Provide useful defaults with minimal setup.

2. Extensibility

Applications should be able to override any starter component.

3. Minimal Boilerplate

JWT infrastructure should require minimal repetitive code.

4. Modular Architecture

Separate:

  • core JWT logic
  • Spring integration
  • security infrastructure

for maintainability.

Contribution Guidelines

Contributions are welcome.

Suggested contribution areas:

  • feature improvements
  • security enhancements
  • performance optimization
  • testing
  • documentation
  • integration support

Development Setup

Clone Repository

git clone https://github.com/smitroy4/jwt-spring-boot-starter.git

Build Project

mvn clean install

Deploy Project

mvn deploy

Author

Smit Roy

GitHub:

https://github.com/smitroy4

License

MIT License

Clone this wiki locally