Skip to content

README.md

Latest commit

 

History

History
193 lines (140 loc) · 8.48 KB

README.md

File metadata and controls

193 lines (140 loc) · 8.48 KB
Raw

security-jwt-extension

English | 简体中文

Java License

JWT authentication and authorization utilities for Spring Security. This module extends the Spring Security authentication model with JWT-aware tokens and filters, for both the servlet (Web) and reactive (WebFlux) stacks.

Table of Contents

1. Project Overview

What it is

security-jwt-extension provides JWT-oriented building blocks for Spring Security applications: authentication tokens carrying a JWT principal/credentials plus optional request metadata (signature, longitude, latitude), a reactive JWT authentication web filter, a servlet-side authorization success handler, and a token-refresh REST endpoint placeholder.

What it is not

  • It is not a JWT library — token creation/parsing is delegated to your application or the underlying Spring Security infrastructure.
  • It is not a complete Spring Security starter: no auto-configuration is shipped in this module; wire the components into your own SecurityFilterChain / SecurityWebFilterChain.

Typical scenarios

Scenario Description
Servlet + JWT authorization Attach JwtAuthorizationSuccessHandler to your authorization flow to build the response after a successful JWT check.
WebFlux + JWT authentication Use JwtAuthenticationWebFilter with a ReactiveAuthenticationManager that validates JWT credentials.
Token refresh endpoint (WIP) RefreshTokenEndpoint marks the intended location of a refresh-token REST endpoint.

2. Features & Status

Capability Status Notes
JwtAuthenticationToken Available Servlet authentication token with principal/credentials, sign, longitude, latitude metadata.
JwtAuthorizationToken Available Authorization-phase token with the same metadata fields.
JwtAuthenticationWebFilter Available WebFlux filter over ReactiveAuthenticationManager.
JwtAuthorizationSuccessHandler Available Servlet AuthenticationSuccessHandler for authorization success responses.
RefreshTokenEndpoint WIP @RestController placeholder; no endpoints implemented yet.

Status is reported as of 2.0.x.x.20260630-SNAPSHOT on the feature/2.0.x branch.

3. Requirements & Compatibility

Item Version
JDK 17+
Maven 3.0+ (Maven Wrapper 3.5.0 bundled)
Spring Security 5.6.0 (spring-security-core, spring-security-web)
Spring Framework 5.3.39 (spring-web, spring-webflux)
Jackson 2.17.2 (jackson-databind)
easy4j dependency io.github.easy4j:spring-security-extension

Version lines

Branch JDK baseline Version pattern
feature/1.0.x JDK 8 1.0.x.*
feature/2.0.x JDK 17 2.0.x.*
feature/3.0.x JDK 21 3.0.x.*

4. Architecture & Modules

 Servlet / WebFlux client (Bearer JWT)
        |
        +--(servlet)--> JwtAuthorizationSuccessHandler
        |
        +--(webflux)--> JwtAuthenticationWebFilter
                           | ReactiveAuthenticationManager
                           v
                     JwtAuthenticationToken / JwtAuthorizationToken
                           |  (sign, longitude, latitude)
                           v
                     Spring Security (core)
                           |
                           +-- RefreshTokenEndpoint (WIP, REST)

This is a single-module project (packaging jar):

Module / artifact Role
security-jwt-extension JWT tokens, filters and handlers for Spring Security (servlet + WebFlux).

5. Installation

The artifact is not yet published to Maven Central. Resolve it from the project's configured artifact repository (Aliyun Packages) or install it locally from source; the snapshot version currently used on the feature/2.0.x branch is 2.0.x.x.20260630-SNAPSHOT.

Maven

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>security-jwt-extension</artifactId>
    <version>2.0.x.x.20260630-SNAPSHOT</version>
</dependency>

Gradle

implementation 'io.github.easy4j:security-jwt-extension:2.0.x.x.20260630-SNAPSHOT'

6. Quick Start

Build a JWT authentication token and let the reactive filter hand it to your ReactiveAuthenticationManager:

import org.springframework.security.boot.jwt.authentication.JwtAuthenticationToken;
import org.springframework.security.boot.jwt.authentication.JwtAuthenticationWebFilter;
import org.springframework.security.authentication.ReactiveAuthenticationManager;

// 1. Token
JwtAuthenticationToken token =
        new JwtAuthenticationToken(principal, jwtCredentials);
token.setSign("optional-request-sign");
token.setLongitude(116.397128d);
token.setLatitude(39.916527d);

// 2. Reactive filter wired with your JWT-validating manager
ReactiveAuthenticationManager manager = /* your manager */;
JwtAuthenticationWebFilter filter = new JwtAuthenticationWebFilter(manager);

Expected result: incoming requests matched by the filter are authenticated against the manager using the JWT credentials carried by JwtAuthenticationToken.

7. Configuration

This is a pure library: no configuration properties, no property prefix, no auto-configuration. All components are instantiated and wired by the application.

8. Core Usage / API

Class Package Role
JwtAuthenticationToken org.springframework.security.boot.jwt.authentication AbstractAuthenticationToken subclass for the authentication phase.
JwtAuthorizationToken org.springframework.security.boot.jwt.authorization Token for the authorization phase (same metadata fields).
JwtAuthenticationWebFilter org.springframework.security.boot.jwt.authentication WebFlux AuthenticationWebFilter using a ReactiveAuthenticationManager.
JwtAuthorizationSuccessHandler org.springframework.security.boot.jwt.authorization Servlet AuthenticationSuccessHandler; also exposes clearAuthenticationAttributes.
RefreshTokenEndpoint org.springframework.security.boot.jwt.endpoint @RestController placeholder (no endpoints yet).

Servlet-style authorization success handling:

import org.springframework.security.boot.jwt.authorization.JwtAuthorizationSuccessHandler;

JwtAuthorizationSuccessHandler handler = new JwtAuthorizationSuccessHandler();
// Called by your authorization flow when the JWT check succeeds
handler.onAuthenticationSuccess(request, response, authentication);

9. Testing & Build

# Full build with JaCoCo coverage report/check
./mvnw clean verify

# Install into the local repository
./mvnw install

Test & gate facts (as configured in the pom):

  • No unit tests exist in this module yet.
  • JaCoCo is bound to prepare-agent / report / check; the check rule requires a 90% line coverage ratio (configured with haltOnFailure=false).

10. Versioning & Branches

Branch JDK baseline Version pattern Status
feature/1.0.x JDK 8 1.0.x.* Active; current snapshot 1.0.x.20260630-SNAPSHOT
feature/2.0.x JDK 17 2.0.x.* Maintained
feature/3.0.x JDK 21 3.0.x.* Maintained

Maintenance strategy: the 1.0.x line keeps JDK 8 compatibility for legacy deployments; the 2.0.x and 3.0.x lines are the modern JDK baselines. Release artifacts are published to the project's configured artifact repository (Aliyun Packages) and GitHub Releases; the project has not yet published to Maven Central.

11. Contributing & License

Contributions are welcome — please open an issue or a pull request on the GitHub repository.

This project is licensed under the Apache License 2.0. See LICENSE for details.