# quay/jwtproxy architecture

> Architecture diagram of the GitHub repository quay/jwtproxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quay/jwtproxy
- Repository: https://github.com/quay/jwtproxy

## Overview

##### Project type and purpose
- This is an open-source Go microservice that implements a dual-mode JWT proxy:
- A forward (signing) proxy that attaches JWTs to outgoing requests.
- A reverse (verifying) proxy that validates JWTs on incoming requests and forwards to an upstream.
- It’s not a full-stack app but a self-contained network service, with CLI entrypoint (`cmd/jwtproxy/main.go`), pluggable key management, nonce storage, and optional MITM SSL support.

##### File structure
- Top-level artifacts:
- `cmd/jwtproxy/` – CLI entrypoint building the `jwtproxy` binary.
- `config/` – Configuration loader (`config.go`) and example YAML (`config.example.yaml`).
- `jwt/` – Core JWT logic: token creation/verification (`jwt.go`, `proxy_handlers.go`), plus subpackages:
– `claims/` (static claim injection/verifier)
– `keyserver/` (implements key-registry protocol, caching, preshared)
– `noncestorage/` (TTL cache storage, local memory)
– `privatekey/` (autogenerated vs. preshared sources)
- `proxy/` – Reverse/forward proxy plumbing (`proxy.go`).
- `examples/` – HTTP and Kubernetes usage scenarios.
- Docker and build files: `Dockerfile`, `.dockerignore`, `glide.yaml`, `go.mod`, etc.

##### README for additional insights
- Describes two main services (signer vs. verifier), their features, config blocks, and how they interoperate.
- Shows that configuration drives which mode(s) are enabled.
- Highlights extensibility points: configurable key server and nonce storage plugins.

a. Main components
1. Clients – internal services or apps making HTTP(s) requests.
2. Forward Proxy (Signer) – listens on `listen_addr`; wraps outgoing requests with JWT header; can MITM HTTPS.
3. Reverse Proxy (Verifier) – listens on `listen_addr`; validates JWTs; terminates TLS if configured; forwards to an Upstream service.
4. Upstream Service – the actual backend that receives verified requests.
5. Key Server / Key Registry – HTTP endpoint serving public keys for verification.
6. Nonce Storage – in-memory TTL cache to track used nonces.
7. Private Key Store – either autogenerated (with rotation + publishing) or preshared.
8. Configuration Store – the YAML file driving both proxies.
9. TLS/SSL CA – certificate authority for MITM (Signer) and certificate for TLS termination (Verifier).
b. Relationships and data flow
- Client → Forward Proxy: HTTP(s) request → Signer attaches JWT header.
- Forward Proxy → Remote Service / Upstream: request carries JWT.
- Reverse Proxy ← Client / other service: incoming JWT-signed requests.
- Reverse Proxy → Key Server: fetch public key (with optional cache) to verify signature.
- Reverse Proxy → Nonce Storage: check/record nonce to prevent replay.
- Reverse Proxy → Upstream Service: forwarded request after verification, possibly with unforgeable headers.
- Forward Proxy → Private Key Store: read or rotate/generate private key, and potentially publish public key to Key Server.
c. Architectural patterns and principles
- Pluggable components (strategy pattern) for key server, private key source, nonce storage.
- Clear separation of concerns: signing vs. verifying, proxy engine vs. JWT logic vs. config.
- Use of standard libraries (net/http, crypto/tls) and minimal external dependencies.
d. Technologies, frameworks, and libraries
- Go modules (`go.mod`, `glide.yaml`)
- net/http for proxy and server
- crypto/tls for MITM and TLS termination
- JSON/YAML for config
- Docker for containerized build

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client\n(Internal Service)"]:::components

    %% CLI Entrypoint
    CLIEntrypoint["CLI Entrypoint\n(jwtproxy binary)"]:::components
    click CLIEntrypoint "https://github.com/quay/jwtproxy/blob/master/cmd/jwtproxy/main.go"

    %% Configuration
    subgraph "Configuration"
        ConfigLoader["Config Loader"]:::components
        click ConfigLoader "https://github.com/quay/jwtproxy/blob/master/config/config.go"
        ConfigExample["Config Example YAML"]:::components
        click ConfigExample "https://github.com/quay/jwtproxy/blob/master/config.example.yaml"
    end

    %% Forward Proxy (Signer)
    subgraph "Forward Proxy (Signer)" 
        direction TB
        FListener["Listener\n(listen_addr)"]:::proxies
        FRouter["Router"]:::proxies
        FJWTHandler["JWT Handler\n(signing)"]:::proxies
        FTransport["Transport\n(HTTP/HTTPS MITM)"]:::proxies
        ProxyEngineF["Proxy Engine"]:::proxies
        click ProxyEngineF "https://github.com/quay/jwtproxy/blob/master/proxy/proxy.go"
    end

    %% Reverse Proxy (Verifier)
    subgraph "Reverse Proxy (Verifier)"
        direction TB
        RListener["Listener\n(listen_addr)"]:::proxies
        RRouter["Router"]:::proxies
        RJWTHandler["JWT Handler\n(verification)"]:::proxies
        RTransport["Transport\n(TLS Termination)"]:::proxies
        ProxyEngineR["Proxy Engine"]:::proxies
        click ProxyEngineR "https://github.com/quay/jwtproxy/blob/master/proxy/proxy.go"
    end

    %% Upstream Service
    Upstream["Upstream Service"]:::components

    %% Key Server / Registry Plugins
    subgraph "Key Server / Registry"
        direction TB
        KeyServerInterface["KeyServer Interface"]:::external
        click KeyServerInterface "https://github.com/quay/jwtproxy/blob/master/jwt/keyserver/keyserver.go"
        KeyRegistry["KeyRegistry Interface"]:::external
        click KeyRegistry "https://github.com/quay/jwtproxy/blob/master/jwt/keyserver/keyregistry/keyregistry.go"
        KeyCache["KeyCache"]:::stores
        click KeyCache "https://github.com/quay/jwtproxy/blob/master/jwt/keyserver/keyregistry/keycache/keycache.go"
        MemoryCache["MemoryCache Impl"]:::stores
        click MemoryCache "https://github.com/quay/jwtproxy/blob/master/jwt/keyserver/keyregistry/keycache/memory/memory.go"
        PresharedKeyServer["Preshared Impl"]:::stores
        click PresharedKeyServer "https://github.com/quay/jwtproxy/blob/master/jwt/keyserver/preshared/preshared.go"
    end

    %% Nonce Storage Plugins
    subgraph "Nonce Storage"
        direction TB
        NonceInterface["NonceStorage Interface"]:::external
        click NonceInterface "https://github.com/quay/jwtproxy/blob/master/jwt/noncestorage/noncestorage.go"
        LocalCache["Local TTL Cache"]:::stores
        click LocalCache "https://github.com/quay/jwtproxy/blob/master/jwt/noncestorage/local/local.go"
    end

    %% Private Key Plugins
    subgraph "Private Key Store"
        direction TB
        PrivateKeyInterface["PrivateKey Interface"]:::external
        click PrivateKeyInterface "https://github.com/quay/jwtproxy/blob/master/jwt/privatekey/privatekey.go"
        AutogenPK["Autogenerated Impl"]:::stores
        click AutogenPK "https://github.com/quay/jwtproxy/blob/master/jwt/privatekey/autogenerated/autogenerated.go"
        PresharedPK["Preshared Impl"]:::stores
        click PresharedPK "https://github.com/quay/jwtproxy/blob/master/jwt/privatekey/preshared/preshared.go"
    end

    %% Core JWT Logic
    subgraph "Core JWT Logic"
        direction TB
        JWTCore["JWT Core"]:::components
        click JWTCore "https://github.com/quay/jwtproxy/blob/master/jwt/jwt.go"
        JWTHandlers["Proxy Handlers"]:::components
        click JWTHandlers "https://github.com/quay/jwtproxy/blob/master/jwt/proxy_handlers.go"
        JWTTests["JWT Tests"]:::components
        click JWTTests "https://github.com/quay/jwtproxy/blob/master/jwt/jwt_test.go"
    end

    %% Docker & Build
    subgraph "Build & Docker"
        DockerfileNode["Dockerfile"]:::components
        click DockerfileNode "https://github.com/quay/jwtproxy/tree/master/Dockerfile"
        DockerIgnore[".dockerignore"]:::components
        click DockerIgnore "https://github.com/quay/jwtproxy/blob/master/.dockerignore"
        Glide["glide.yaml"]:::components
        click Glide "https://github.com/quay/jwtproxy/blob/master/glide.yaml"
        GoMod["go.mod"]:::components
        click GoMod "https://github.com/quay/jwtproxy/blob/master/go.mod"
    end

    %% Deployment Examples
    subgraph "Examples"
        HTTPExample["HTTP Server Example"]:::components
        click HTTPExample "https://github.com/quay/jwtproxy/tree/master/examples/httpserver/"
        K8sExample["Kubernetes Example"]:::components
        click K8sExample "https://github.com/quay/jwtproxy/tree/master/examples/kubernetes-httpserver/"
    end

    %% CA Certificates
    CA["Certificates / CA"]:::cert

    %% Connections
    Client -->|"HTTP(s) Request"| FListener
    FListener --> FRouter
    FRouter --> FJWTHandler
    FJWTHandler -->|"Attach JWT"| FTransport
    FTransport -->|"Request with JWT"| Upstream

    Client -->|"JWT Request"| RListener
    RListener --> RRouter
    RRouter --> RJWTHandler
    RJWTHandler -->|"Verify JWT"| KeyServerInterface
    RJWTHandler -->|"Fetch Public Key"| KeyRegistry
    KeyRegistry --> KeyCache
    KeyCache --> MemoryCache
    RJWTHandler -->|"Check / Record Nonce"| NonceInterface
    NonceInterface --> LocalCache
    RJWTHandler -->|"Forward Verified"| RTransport
    RTransport --> Upstream

    FJWTHandler -->|"Read/Rotate Key"| PrivateKeyInterface
    PrivateKeyInterface --> AutogenPK
    PrivateKeyInterface --> PresharedPK
    AutogenPK -->|"Publish Public Key"| KeyServerInterface

    ConfigLoader --> FListener
    ConfigLoader --> RListener

    CA --> FTransport
    CA --> RTransport

    %% JWT Core Logic connections
    FJWTHandler --> JWTCore
    RJWTHandler --> JWTCore
    JWTCore --> JWTHandlers

    %% Legend
    subgraph Legend
        direction TB
        L1["Blue: Proxy Components"]:::proxies
        L2["Green: Stores"]:::stores
        L3["Orange: External Plugins"]:::external
        L4["Gray: Other Components"]:::components
        L5["Yellow: Certificates"]:::cert
    end

    classDef proxies fill:#dae8fc,stroke:#6c8ebf;
    classDef stores fill:#d5e8d4,stroke:#82b366;
    classDef external fill:#f8cecc,stroke:#b85450;
    classDef components fill:#f5f5f5,stroke:#999999;
    classDef cert fill:#fff2cc,stroke:#d6b656;
```
