How quay/jwtproxy works
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