# ory/oathkeeper architecture

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

- Interactive diagram: https://gitdiagram.com/ory/oathkeeper
- Repository: https://github.com/ory/oathkeeper

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Ingress Layer
  subgraph "Ingress Layer"
    style IngressLayer fill:#c2f0c2,stroke:#333,stroke-width:1px
    CLI["CLI Tool\n(oathkeeper)"]:::ingress
    Gateways["External Gateways\n(Envoy, Ambassador,\nNginx, AWS API GW)"]:::ingress
  end

  %% Core Service Layer
  subgraph "Core Service (Oathkeeper)" 
    style CoreService fill:#add8e6,stroke:#333,stroke-width:1px
    Proxy["Proxy Module"]:::core
    subgraph "Pipeline"
      style Pipeline fill:#add8e6,stroke:#333,stroke-width:1px
      AuthN["AuthN Stage\n(JWT, API Key, mTLS)"]:::core
      AuthZ["AuthZ Stage\n(Policy Checks)"]:::core
      Mutators["Mutators Stage\n(Request Mutation)"]:::core
      Errors["Error Handlers"]:::core
    end
    HTTPClient["Internal HTTP Client"]:::core
  end

  %% Data Stores & Drivers
  subgraph "Data Stores & Drivers"
    style DataStores fill:#ffd580,stroke:#333,stroke-width:1px
    RuleRepo["Rule Repository"]:::data
    Credentials["Credential Stores"]:::data
    Drivers["Drivers & Registries"]:::data
  end

  %% External Services
  subgraph "External Services"
    style ExtServices fill:#d8b4e2,stroke:#333,stroke-width:1px
    OAuth2["OAuth2 Introspection\n& JWKS Providers"]:::ext
    RemoteAuthZ["Remote JSON Authorizers"]:::ext
  end

  %% Configuration & Schemas
  subgraph "Configuration & Schemas"
    style ConfigLayer fill:#d3d3d3,stroke:#333,stroke-width:1px
    ConfigLoader["Config Loader\n(Koanf & JSON Schema)"]:::config
  end

  %% Observability
  Observability["Prometheus Metrics\n& gRPC Middleware"]:::ext

  %% Deployment Artifacts
  DockerBuild["Docker Build Artifacts"]:::docker
  DockerCompose["Docker Compose Manifests"]:::docker

  %% Upstream Target
  Upstream["Upstream Service"]:::ext

  %% Connections
  Gateways -->|Ingress Request| Proxy
  CLI -->|Manage Rules & Credentials| Drivers
  CLI --> ConfigLoader
  Proxy -->|forward| AuthN
  AuthN -->|success| AuthZ
  AuthN -->|failure| Errors
  AuthZ -->|success| Mutators
  AuthZ -->|failure| Errors
  Mutators -->|success| Upstream
  Mutators -->|failure| Errors
  Errors -->|HTTP Error Response| Gateways

  AuthZ -->|remote calls| HTTPClient
  HTTPClient --> OAuth2
  HTTPClient --> RemoteAuthZ

  AuthN --> Drivers
  AuthZ --> RuleRepo
  AuthN --> Credentials
  AuthN --> Drivers

  Proxy --> Observability
  ConfigLoader --> Proxy
  ConfigLoader --> Drivers
  ConfigLoader --> RuleRepo
  ConfigLoader --> Credentials

  %% Click Events
  click CLI "https://github.com/ory/oathkeeper/blob/master/cmd/root.go"
  click Proxy "https://github.com/ory/oathkeeper/blob/master/proxy/proxy.go"
  click AuthN "https://github.com/ory/oathkeeper/blob/master/pipeline/authn/registry.go"
  click AuthZ "https://github.com/ory/oathkeeper/blob/master/pipeline/authz/registry.go"
  click Errors "https://github.com/ory/oathkeeper/blob/master/pipeline/errors/registry.go"
  click Mutators "https://github.com/ory/oathkeeper/blob/master/pipeline/mutate/registry.go"
  click Drivers "https://github.com/ory/oathkeeper/blob/master/driver/registry.go"
  click RuleRepo "https://github.com/ory/oathkeeper/blob/master/rule/registry.go"
  click Credentials "https://github.com/ory/oathkeeper/tree/master/credentials/"
  click HTTPClient "https://github.com/ory/oathkeeper/tree/master/internal/httpclient/client/"
  click Observability "https://github.com/ory/oathkeeper/blob/master/metrics/prometheus.go"
  click ConfigLoader "https://github.com/ory/oathkeeper/blob/master/driver/configuration/provider_koanf.go"
  click API "https://github.com/ory/oathkeeper/blob/master/api/decision.go"
  click DockerBuild "https://github.com/ory/oathkeeper/tree/master/.docker/Dockerfile-alpine"
  click DockerCompose "https://github.com/ory/oathkeeper/blob/master/.docker_compose/config.yaml"

  %% Class Definitions
  classDef ingress fill:#c2f0c2,stroke:#333;
  classDef core fill:#add8e6,stroke:#333;
  classDef data fill:#ffd580,stroke:#333;
  classDef ext fill:#d8b4e2,stroke:#333;
  classDef config fill:#d3d3d3,stroke:#333;
  classDef docker fill:#f4cccc,stroke:#333;
```
