OAuth-Sheriff

1. Status

Build & Quality

Performance Benchmarks

Micro Benchmarks

Integration Benchmarks

Understanding Performance Metrics

2. What is it?

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

Table of Contents

• 1. Status
• 2. What is it?
• 3. Motivation
  • Why another JWT-Library?
  • The Challenge
  • Why Offline Validation?
  • Key Problems Solved
• 4. Quick Start
  • Quarkus Integration (Recommended)
    • Declarative Security with Interceptors
  • Standalone Library
• 5. Core Features
• 6. Architecture
• 7. Documentation
• 8. Performance

3. 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 implementation. 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.

4. Quick Start

Quarkus Integration (Recommended)

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

<dependency>
    <groupId>de.cuioss.sheriff.oauth</groupId>
    <artifactId>oauth-sheriff-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.oauth.issuers.keycloak.jwks.http.well-known-url=https://keycloak.example.com/realms/master/.well-known/openid-configuration

@Inject
@BearerToken(requiredScopes = {"read"})
private BearerTokenResult tokenResult;

// Token is automatically validated and injected
if (tokenResult.isSuccessfullyAuthorized()) {
    // The call is authorized and verified to contain the scope "read"
}

Declarative Security with Interceptors

For a more declarative approach, use the @BearerAuth interceptor annotation:

@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();
}

Access the validated token using parameter injection:

@GET
@BearerAuth(requiredScopes = {"read"})
public Response getData(@BearerToken BearerTokenResult tokenResult) {
    AccessTokenContent token = tokenResult.getAccessTokenContent()
        .orElseThrow(() -> new IllegalStateException("Token not available"));

    String userId = token.getSubject().orElse("unknown");

    return Response.ok(data).build();
}

When to use which approach:

• Producer pattern (@BearerToken): Explicit validation control, custom error handling, complex authorization logic

• Interceptor pattern (@BearerAuth): Declarative security, automatic error responses, clean separation of concerns

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.oauth</groupId>
    <artifactId>oauth-sheriff-core</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(tokenString);

5. 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

6. Architecture

For detailed architectural information, see:

• Technical Components - Complete architecture documentation

• Component Diagram - Visual architecture overview

7. Documentation

• 📚 Documentation Navigation - Complete guide to all documentation

• Usage Guide - Detailed usage examples

• Requirements - Functional and non-functional requirements

• Threat Model - Security analysis

For configuration details including runtime dependencies and test support, see the JWT Validation Module documentation.

8. 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 (January 2026) - WRK HTTP load testing analysis

• Micro-Benchmark Analysis (January 2026) - JMH library performance analysis