How ory/oathkeeper works
Project Type and Purpose
• ORY Oathkeeper is a cloud-native Identity & Access Proxy (IAP) and Access Control Decision API written in Go. It can be deployed as a standalone API server, as an envoy/Ambassador external‐auth service, AWS API Gateway custom authorizer, Nginx subrequest authenticator, or via its CLI tooling. It enforces authentication, authorization, and optional request mutations based on a set of rules.
File Structure Analysis
• Top Level:
• cmd/ → CLI and HTTP server entry points (root.go, serve.go, health, version, credentials, rules).
• api/ → HTTP handlers & OpenAPI-generated client models for the Access Control Decision API.
• pipeline/ → Core request processing pipeline subdivided into authn (authenticators), authz (authorizers), errors, mutate (mutators).
• proxy/ → HTTP proxy implementation (request handler, response writer).
• credentials/ → Fetcher, signer, verifier for external credential stores (S3, GCS, Azure).
• rule/ → Rule fetching, matching, validation, in-memory or remote repositories.
• driver/ → Abstractions for storage drivers, config providers, registry of pluggable drivers.
• internal/ → HTTP client for remote ORY services, cloud storage helpers, config loader.
• middleware/metrics/ → Prometheus metrics and optional gRPC middleware.
• .docker/, .docker_compose/ → Dockerfiles for container images; compose configs for local development.
• .schema/, schemas/, spec/ → JSON schema definitions and OpenAPI templates for generating clients & docs.
• Patterns & Principles:
• Pipeline design: each request flows through a sequence of authenticators → authorizers → mutators → upstream proxy.
• Registry/Factory: pluggable components are registered via registries in pipeline and driver packages.
• 12-factor config: Koanf/YAML/JSON schemas drive configuration loading.
• Container-first: minimal dependencies, multi-arch binaries, Kubernetes-friendly.
Key Insights from README
• Explains IAP role in Zero-Trust / BeyondCorp.
• Emphasizes ecosystem integration: Envoy, Ambassador, AWS API Gateway, Nginx.
• Highlights HTTP API docs (OpenAPI) and CLI usage.
• Notes cloud-native philosophy: runs everywhere, small footprint, minimal deps.