README.adoc

Documentation Hub

Table of Contents

• 1. Architecture Decisions
• 2. Commons (base layer)
  • 2.1. Specifications
• 3. Token Validation
  • 3.1. Security
  • 3.2. Specifications
  • 3.3. FAQ
• 4. Client
  • 4.1. Security
  • 4.2. Specifications
• 5. Reference
• 6. Module Documentation
• 7. Benchmarking
• 8. Configuration

This is the central navigation for TokenSheriff documentation.

1. Architecture Decisions

Standing architectural decisions, recorded as durable ADRs under doc/adr/.

• ADR-0001: Validation and Client Module Split with a Commons Base Layer - Two Maven modules (validation + client) in one repository, with the commons base layer enforced by ArchUnit rather than carved out as a third artifact

2. Commons (base layer)

The shared base layer every capability sits on — the de.cuioss.sheriff.token.commons.* packages inside token-sheriff-validation (transport, error model, security events, metrics), enforced by ArchUnit rather than shipped as a separate module.

• Overview - Capability entry point: intro, scope, reading order, document map

• Requirements - COMMONS-N, grouped by concern

• Architecture - The base layer and its ArchUnit boundary

• Threat Model - SSRF / TLS / response-DoS / error-detail leakage

• References - Bibliography

2.1. Specifications

• Transport - Discovery, JWKS, token/userinfo/…; TLS, SSRF, resilience

• Error Model - Typed exceptions → RFC 9457 at every HTTP edge

• Observability - SecurityEventCounter events + metric identifiers

3. Token Validation

The token validation capability — its requirements, architecture, security model, and specifications.

• Overview - Capability entry point: intro, scope, reading order, document map

• Requirements - Functional and non-functional requirements

• Architecture - Validation pipeline, components, and design

3.1. Security

• Threat Model - STRIDE threat analysis with coverage status

• Security Reference - Attack mitigations, controls, and best practices

3.2. Specifications

• MicroProfile JWT Compatibility - MP-JWT 2.1 integration and rationale

• Token Decryption - JWE encrypted-token support

• Multi-IDP Testing - Testing with multiple OIDC providers

3.3. FAQ

• Keycloak FAQ

4. Client

The active OIDC capability — the server-side confidential-client engine that retrieves tokens, holds and refreshes them server-side, and drives the flows on top of the commons transport. It is the engine a Backend-For-Frontend (BFF) is built on; it is not itself a BFF. The token-sheriff-client module (and its token-sheriff-client-quarkus extension) is implemented; this document set remains the normative specification.

• Overview - Capability entry point: intro, scope, reading order, document map

• Requirements - CLIENT-N, grouped by aspect (Retrieval & flow / Token)

• Architecture - Client/BFF engine seam and boundaries

• References - Bibliography

4.1. Security

• Threat Model - Attack catalog per aspect, each entry sourced

• Best Practices - Normative, sourced checklist

4.2. Specifications

• Retrieval & Flow - Auth-code + PKCE, grants, client auth, state/nonce, mix-up, PAR

• Step-up & Logout - RFC 9470 step-up; RP-initiated logout

• Token Handling - Server-side lifecycle delta (references the validation module)

• Test Strategy - Two-layer verification model and traceability matrix

5. Reference

• Log Messages - Global registry of all log messages

6. Module Documentation

• token-sheriff-validation - Core library usage and API (also carries the commons base layer)

  • Usage Guide

  • API Reference

  • Developing

  • Unit Testing

• token-sheriff-client - Framework-agnostic OIDC/OAuth client engine

  • Module Documentation

• token-sheriff-quarkus-parent - Quarkus extensions

  • Module Documentation

  • token-sheriff-validation-quarkus (+ -deployment) - validation extension

  • token-sheriff-client-quarkus (+ -deployment) - client extension

7. Benchmarking

• Benchmarking Overview

• Micro-Benchmark Analysis (March 2026)

• Integration Benchmark Analysis (March 2026)

• Performance Scoring

8. Configuration

• Configuration Reference - All sheriff.token.* properties