shiro-jwt

English | 简体中文

JWT authentication and authorization extension for Apache Shiro, built on shiro-extension-spring and jwt-issuer-api (easy4j). It provides JWT-aware filters (header X-Authorization or token parameter), stateful/stateless realms, principal repositories, credentials matching and i18n messages for Shiro-based applications.

Table of Contents

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage / API
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

1. Project Overview

What it is

shiro-jwt brings JWT login to Shiro web applications:

• JwtAuthenticatingFilter (extends TrustableRestAuthenticatingFilter from shiro-extension-spring) accepts JWTs from the X-Authorization header or the token request parameter.
• JwtStatefulAuthorizingRealm / JwtStatelessAuthorizingRealm cover session-based and stateless JWT authentication.
• JwtPayloadRepository / JwtPrincipalRepository / JwtPayloadPrincipal map JWT payloads (from jwt-issuer-api) onto the Shiro principal model.
• JwtAuthorizationFilter and JwtWithinExpiryFilter enforce authorization and expiry checks.
• ShiroJwtMessageSource provides i18n authentication/authorization messages (EN / zh-CN).

What it is not

• It is not a JWT signing/verification library — token issuance and parsing are delegated to io.github.easy4j:jwt-issuer-api (JwtPayload).
• It is not a Spring Boot starter; filters/realms must be wired into your Shiro configuration.

Typical scenarios

Scenario	Description
REST API JWT authentication	JwtAuthenticatingFilter extracts the JWT from X-Authorization / token and authenticates it.
Stateless JWT services	JwtStatelessAuthorizingRealm for services without server-side sessions.
Session-based JWT	JwtStatefulAuthorizingRealm for classic session applications.
Expiry enforcement	JwtWithinExpiryFilter rejects requests whose JWT is no longer within the expiry window.

2. Features & Status

Capability	Status	Notes
JWT authenticating filter	Available	JwtAuthenticatingFilter — X-Authorization header or token parameter; extends TrustableRestAuthenticatingFilter.
Stateful / stateless realms	Available	JwtStatefulAuthorizingRealm, JwtStatelessAuthorizingRealm.
Payload & principal repository	Available	JwtPayloadRepository (interface), JwtPrincipalRepository, JwtPayloadPrincipal.
Credentials matching	Available	JwtCredentialsMatcher.
Authorization filters	Available	JwtAuthorizationFilter, JwtWithinExpiryFilter (X-Authorization / token).
Handlers	Available	JwtAuthenticationFailureHandler, JwtAuthenticationSuccessHandler (payload repository + expiry check), JwtAuthorizationFailureHandler (all Ordered).
Subject factory	Available	JwtSubjectFactory (session-creation enabled/disabled).
Tokens	Available	JwtAuthenticationToken (extends DefaultAuthenticationToken), JwtAuthorizationToken.
Exceptions	Available	ExpiredJwtException, IncorrectJwtException, InvalidJwtToken, NotObtainedJwtException.
i18n messages	Available	messages.properties (+ en_US, zh_CN) via ShiroJwtMessageSource.
Utilities	Available	SubjectJwtUtils, JSONResult, StringUtils (under org.apache.shiro.spring.boot.utils).

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

3. Requirements & Compatibility

Item	Version
JDK	17+
Maven	3.0+ (Maven Wrapper 3.5.0 bundled)
Apache Shiro	2.2.1 (shiro-core, shiro-web)
easy4j dependencies	shiro-extension-spring, jwt-issuer-api (both 2.0.x.20260630-SNAPSHOT)
JSON	fastjson 2.0.62, jackson-databind 2.17.2
Other	spring-context / spring-web, commons-lang3, guava, javax.servlet-api 4.0.1

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

 Client (JWT in X-Authorization header / token parameter)
        |
        v
 JwtAuthenticatingFilter (authc)
        |  createJwtToken() -> JwtAuthenticationToken
        v
 JwtStatefulAuthorizingRealm / JwtStatelessAuthorizingRealm
        |  JwtPrincipalRepository -> JwtPayloadRepository (jwt-issuer-api)
        |  JwtCredentialsMatcher
        v
 Subject (JwtPayloadPrincipal)
        |
        v
 JwtAuthorizationFilter / JwtWithinExpiryFilter (authz)
        |
        +-- handlers --> ShiroJwtMessageSource (i18n)

This is a two-module Maven aggregator. Existing Java package names under org.apache.shiro.spring.boot.jwt and org.apache.shiro.spring.boot.utils remain unchanged for source compatibility:

Module	Role
shiro-jwt-core	JWT tokens, credentials matcher, authentication exceptions and framework-neutral utilities; no Spring API dependency.
shiro-jwt-spring	Payload/principal repositories, Spring Web filters, handlers, realms, message source and SubjectJwtUtils; depends on core.

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/3.0.x branch is 2.0.x.20260630-SNAPSHOT.

Maven

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

Gradle

implementation 'io.github.easy4j:shiro-jwt-spring:2.0.x.20260630-SNAPSHOT'

6. Quick Start

Wire the JWT authenticating filter into your Shiro filter chain:

import org.apache.shiro.spring.boot.jwt.authc.JwtAuthenticatingFilter;
import org.apache.shiro.spring.boot.jwt.realm.JwtStatelessAuthorizingRealm;

// 1. Stateless realm (no server-side session required)
JwtStatelessAuthorizingRealm realm = new JwtStatelessAuthorizingRealm();

// 2. Filter: accepts "X-Authorization: <jwt>" or "?token=<jwt>"
JwtAuthenticatingFilter filter = new JwtAuthenticatingFilter();
filter.setLoginUrl("/login/jwt");
// register filter + realm with your SecurityManager / filter chain

Expected result: requests carrying a valid JWT are authenticated by the realm; the Shiro subject principal becomes the JwtPayloadPrincipal extracted from the token payload; requests without a valid JWT are redirected to the login URL.

7. Configuration

This library has no configuration properties or prefix; it is configured programmatically:

Extension point	Configurable via
JwtAuthenticatingFilter	setLoginUrl(...), request parameter name (default token) and header name (default X-Authorization).
JwtAuthenticationSuccessHandler	constructor (JwtPayloadRepository, boolean checkExpiry)
JwtPrincipalRepository	constructor (JwtPayloadRepository), setCheckExpiry(boolean)
JwtSubjectFactory	constructor (boolean sessionCreationEnabled)
Message texts	bundled org/apache/shiro/spring/boot/jwt/messages*.properties

8. Core Usage / API

Class	Role
JwtAuthenticatingFilter	Extracts JWT from X-Authorization header / token parameter and authenticates (AUTHORIZATION_HEADER, AUTHORIZATION_PARAM constants).
JwtAuthorizationFilter	Authorization filter using the same header/parameter extraction.
JwtWithinExpiryFilter	Rejects JWTs outside the expiry window.
JwtStatefulAuthorizingRealm / JwtStatelessAuthorizingRealm	Realms for session-based / stateless JWT auth.
JwtPayloadRepository / JwtPrincipalRepository / JwtPayloadPrincipal	JWT payload → Shiro principal mapping.
JwtCredentialsMatcher	Credentials matching for JWT tokens.
ShiroJwtMessageSource	ResourceBundleMessageSource subclass; getAccessor() returns the MessageSourceAccessor.

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.