Token-Sheriff

Status

Build & Quality

Performance Benchmarks

Micro Benchmarks

Integration Benchmarks

Understanding Performance Metrics

What is it?

A comprehensive library for validating JWT tokens in multi-issuer environments with a focus on offline validation.

Motivation

Why another JWT-Library?

This project started as an instrumentation of SmallRye JWT, then shifted to JJWT with the goal to implement robust multi-issuer handling. With a strong focus on security (see Requirements), the project evolved through several iterations until it became an entirely new library with its own validation and parsing implementation (JJWT remains only as a test dependency for token generation). The main differentiator is the comprehensive approach to security in multi-issuer environments.

The Challenge

Modern microservice architectures often need to validate JWT tokens from multiple identity providers without making synchronous calls to authorization servers. This library addresses several key challenges:

Why Offline Validation?

• Performance: No network round-trips for token validation, enabling sub-millisecond validation times
• Resilience: Service remains functional even when identity providers are temporarily unavailable
• Scalability: Validation scales with your application, not limited by identity provider capacity
• Cost: Reduces load on identity providers, avoiding rate limiting and additional infrastructure costs

Key Problems Solved

• Multi-Issuer Complexity: Seamlessly handle tokens from Keycloak, Auth0, Azure AD, and other providers in a single application
• Key Rotation: Automatic JWKS key fetching and caching with configurable refresh strategies
• Security: Protection against common JWT vulnerabilities through comprehensive validation pipeline
• Configuration Overhead: OpenID Connect Discovery for automatic configuration from well-known endpoints

Note

This library focuses on JWT validation and is not meant as a replacement for full OAuth2 or OpenID Connect libraries. It will never create tokens, only validate them.

Quick Start

Quarkus Integration (Recommended)

For Quarkus applications, use our dedicated extension for seamless integration:

<dependency>
    <groupId>de.cuioss.sheriff.token</groupId>
    <artifactId>token-sheriff-validation-quarkus</artifactId>
</dependency>

The Quarkus Extension provides:

• Minimal configuration with zero-configuration for sensible best-practice security settings
• CDI injection of validated tokens
• Automatic metrics and health checks
• Native image support for GraalVM
• Dev UI integration for testing

Minimal Configuration Example (using OpenID Connect Discovery)

# application.properties
sheriff.token.issuers.keycloak.jwks.http.well-known-url=https://keycloak.example.com/realms/master/.well-known/openid-configuration

@GET
@Path("/data")
@BearerAuth(requiredScopes = {"read"}, requiredRoles = {"user"})
public Response getData() {
    // Only business logic - security handled automatically by interceptor
    // If validation fails, error response is returned automatically
    return Response.ok(data).build();
}

The extension also supports standard MicroProfile JWT Auth 2.1 injection — every validated token is a JsonWebToken and Principal:

@Inject
JsonWebToken callerPrincipal;  // MP-JWT standard

@GET
@BearerAuth(requiredScopes = {"read"})
public Response getData() {
    String userName = callerPrincipal.getName();  // UPN fallback: upn → preferred_username → sub
    Set<String> groups = callerPrincipal.getGroups();
    return Response.ok("Hello " + userName).build();
}

For details, see the MicroProfile JWT Compatibility specification and the Quarkus Extension documentation.

For a complete working example, see the integration tests module.

Standalone Library

For non-Quarkus applications, use the core validation library:

<dependency>
    <groupId>de.cuioss.sheriff.token</groupId>
    <artifactId>token-sheriff-validation</artifactId>
</dependency>

// Create validator with OIDC Discovery
TokenValidator validator = TokenValidator.builder()
    .issuerConfig(IssuerConfig.builder()
        .httpJwksLoaderConfig(HttpJwksLoaderConfig.builder()
            .wellKnownUrl("https://your-issuer.com/.well-known/openid-configuration")
            .build())
        .expectedAudience("your-client-id") // Add expected audience
        .build())
    .build();

// Validate token
AccessTokenContent accessToken = validator.createAccessToken(AccessTokenRequest.of(tokenString));

Core Features

• Multi-issuer support for handling tokens from different identity providers
• Automatic JWKS key management with rotation support
• OpenID Connect Discovery for automatic configuration
• Type-safe token parsing with strongly typed Access, ID, and Refresh tokens
• Comprehensive security with configurable validation pipeline
• High performance with sub-millisecond validation and built-in caching
• Production ready with extensive testing against Keycloak

Architecture

For detailed architectural information, see:

• Architecture Reference - Validation pipeline, components, and design
• Component Diagram - Visual architecture overview

Documentation

• Documentation Hub - Complete guide to all documentation
• Usage Guide - Detailed usage examples
• Requirements - Functional and non-functional requirements
• Threat Model - Security analysis
• MicroProfile JWT Compatibility - MP-JWT 2.1 integration and rationale
• Multi-IDP Testing - Testing with multiple OIDC providers

For configuration details including runtime dependencies and test support, see the Token-Sheriff Core documentation.

Performance

The library is continuously benchmarked with results published to GitHub Pages:

• Micro-benchmarks - In-memory performance testing
• WRK Load Testing - HTTP-based load testing with WRK
• Performance Metrics - Understanding the scoring system
• Integration Benchmark Analysis (March 2026) - WRK HTTP load testing analysis
• Micro-Benchmark Analysis (March 2026) - JMH library performance analysis