Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cuioss/oauth-sheriff

A comprehensive framework for handling JWT tokens in multi-issuer environments.
https://github.com/cuioss/oauth-sheriff

java jwt-token oauth oauth2 offline-validation

Last synced: 7 months ago
JSON representation

A comprehensive framework for handling JWT tokens in multi-issuer environments.

Awesome Lists containing this project

README 

          
= oauth-sheriff-core

:toc: macro

:toclevels: 3

:sectnumlevels: 1



[.discrete]

== Status



**Build & Quality**



image:https://github.com/cuioss/OAuth-Sheriff/actions/workflows/maven.yml/badge.svg?branch=main[Java CI with Maven,link=https://github.com/cuioss/OAuth-Sheriff/actions/workflows/maven.yml]

image:https://github.com/cuioss/OAuth-Sheriff/actions/workflows/integration-tests.yml/badge.svg?branch=main[Integration Tests,link=https://github.com/cuioss/OAuth-Sheriff/actions/workflows/integration-tests.yml]



image:https://img.shields.io/github/last-commit/cuioss/OAuth-Sheriff/main[Last Build,link=https://github.com/cuioss/OAuth-Sheriff/commits/main]

image:http://img.shields.io/:license-apache-blue.svg[License,link=http://www.apache.org/licenses/LICENSE-2.0.html]

image:https://img.shields.io/maven-central/v/de.cuioss.sheriff.oauth/oauth-sheriff-parent.svg?label=Maven%20Central["Maven Central", link="https://central.sonatype.com/artifact/de.cuioss.sheriff.oauth/oauth-sheriff-parent"]



image:https://sonarcloud.io/api/project_badges/measure?project=cuioss_OAuth-Sheriff&metric=alert_status[Quality Gate Status,link=https://sonarcloud.io/summary/new_code?id=cuioss_OAuth-Sheriff]

image:https://sonarcloud.io/api/project_badges/measure?project=cuioss_OAuth-Sheriff&metric=ncloc[Lines of Code,link=https://sonarcloud.io/summary/new_code?id=cuioss_OAuth-Sheriff]

image:https://sonarcloud.io/api/project_badges/measure?project=cuioss_OAuth-Sheriff&metric=coverage[Coverage,link=https://sonarcloud.io/summary/new_code?id=cuioss_OAuth-Sheriff]



**Performance Benchmarks**



image:https://github.com/cuioss/OAuth-Sheriff/actions/workflows/benchmark.yml/badge.svg[JMH Benchmarks,link=https://github.com/cuioss/OAuth-Sheriff/actions/workflows/benchmark.yml]

image:https://img.shields.io/endpoint?url=https://cuioss.github.io/OAuth-Sheriff/benchmarks/badges/last-run-badge.json[Last Benchmark Run,link=https://cuioss.github.io/OAuth-Sheriff/benchmarks/]



*Micro Benchmarks*



image:https://img.shields.io/endpoint?url=https://cuioss.github.io/OAuth-Sheriff/benchmarks/badges/performance-badge.json[JWT Performance Score,link=https://cuioss.github.io/OAuth-Sheriff/benchmarks/micro/]

image:https://img.shields.io/endpoint?url=https://cuioss.github.io/OAuth-Sheriff/benchmarks/badges/trend-badge.json[Performance Trend,link=https://cuioss.github.io/OAuth-Sheriff/benchmarks/micro/trends.html]



*Integration Benchmarks*



image:https://img.shields.io/endpoint?url=https://cuioss.github.io/OAuth-Sheriff/benchmarks/badges/integration-performance-badge.json[Integration Performance,link=https://cuioss.github.io/OAuth-Sheriff/benchmarks/integration/]

image:https://img.shields.io/endpoint?url=https://cuioss.github.io/OAuth-Sheriff/benchmarks/badges/integration-trend-badge.json[Integration Trend,link=https://cuioss.github.io/OAuth-Sheriff/benchmarks/integration/trends.html]



xref:benchmarking/doc/performance-scoring.adoc[Understanding Performance Metrics]



[.discrete]

== What is it?



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



toc::[]



== Motivation



=== Why another JWT-Library?



This project started as an instrumentation of https://github.com/smallrye/smallrye-jwt[SmallRye JWT], then shifted to https://github.com/jwtk/jjwt[JJWT] with the goal to implement robust multi-issuer handling. With a strong focus on security (see xref:doc/Requirements.adoc[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.

====



== Quick Start



=== Quarkus Integration (Recommended)



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



[source,xml]

----



    de.cuioss.sheriff.oauth

    oauth-sheriff-quarkus



----



The xref:oauth-sheriff-quarkus-parent/README.adoc[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)

[source,properties]

----

# application.properties

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

----



[source,java]

----

@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:



[source,java]

----

@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:



[source,java]

----

@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 xref:oauth-sheriff-quarkus-parent/oauth-sheriff-quarkus-integration-tests/README.adoc[integration tests module].



=== Standalone Library



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



[source,xml]

----



    de.cuioss.sheriff.oauth

    oauth-sheriff-core



----



[source,java]

----

// 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);

----



== 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:



* xref:doc/specification/technical-components.adoc[Technical Components] - Complete architecture documentation

* xref:doc/plantuml/component-overview.png[Component Diagram] - Visual architecture overview



== Documentation



* xref:doc/navigation.adoc[📚 Documentation Navigation] - Complete guide to all documentation

* xref:oauth-sheriff-core/README.adoc[Usage Guide] - Detailed usage examples

* xref:doc/Requirements.adoc[Requirements] - Functional and non-functional requirements

* xref:doc/security/Threat-Model.adoc[Threat Model] - Security analysis



For configuration details including runtime dependencies and test support, see the xref:oauth-sheriff-core/README.adoc[JWT Validation Module documentation].



== Performance



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



* xref:benchmarking/benchmark-core/README.adoc[Micro-benchmarks] - In-memory performance testing

* xref:benchmarking/benchmark-integration-wrk/README.adoc[WRK Load Testing] - HTTP-based load testing with WRK

* xref:benchmarking/doc/performance-scoring.adoc[Performance Metrics] - Understanding the scoring system