Introduction
Ory Oathkeeper sits in front of your APIs and web applications as a reverse proxy that evaluates access rules on every request. It is part of the Ory ecosystem alongside Kratos (identity) and Hydra (OAuth2), and can authenticate requests using JWTs, cookies, OAuth2 tokens, or API keys.
What Oathkeeper Does
- Authenticates incoming requests using configurable authenticator handlers
- Authorizes requests by evaluating policies via local rules or remote decision APIs
- Mutates upstream requests by injecting headers, JWTs, or transformed credentials
- Serves as a BeyondCorp-style access proxy for internal services
- Provides a decision API for integration with existing reverse proxies like Nginx or Envoy
Architecture Overview
Oathkeeper processes each request through a pipeline of three stages: authentication (who is the caller), authorization (is the action allowed), and mutation (what credentials to forward upstream). Each stage uses pluggable handlers configured per-rule in JSON or YAML. Oathkeeper can run as a standalone reverse proxy or as a decision API behind Nginx, Traefik, or Envoy.
Self-Hosting & Configuration
- Deploy as a Docker container, Kubernetes Helm chart, or standalone binary
- Define access rules in JSON mapping URL patterns to handler pipelines
- Configure authenticators: noop, cookie_session, bearer_token, jwt, oauth2_introspection
- Set up authorizers: allow, deny, keto_engine_acp_ory, remote_json
- Configure mutators: noop, header, cookie, id_token to transform upstream requests
Key Features
- Pipeline-based request processing: authenticate, authorize, mutate in sequence
- Decision API mode for integration with any reverse proxy or API gateway
- Multiple authenticator types including JWT validation and OAuth2 introspection
- ID token mutator generates signed JWTs for upstream services
- Hot-reloading of access rules without restarting the proxy
Comparison with Similar Tools
- Pomerium — full zero trust proxy with IdP integration; Oathkeeper focuses on request pipeline without built-in IdP
- OAuth2 Proxy — single authenticator (OIDC); Oathkeeper supports multiple authentication methods per route
- Envoy ext_authz — external authorization filter; Oathkeeper provides a complete proxy or decision API
- Kong — API gateway with plugins; Oathkeeper specializes in identity-aware access control
- Open Policy Agent — policy engine; Oathkeeper integrates with OPA as one of several authorizer backends
FAQ
Q: Can Oathkeeper work with my existing reverse proxy? A: Yes. Oathkeeper provides a decision API that Nginx, Traefik, Envoy, or any proxy can call via auth_request or ext_authz.
Q: Does Oathkeeper handle user registration and login? A: No. User management is handled by Ory Kratos. Oathkeeper evaluates sessions and tokens created by identity providers.
Q: How are access rules defined? A: Rules are JSON objects that map URL patterns to a pipeline of authenticator, authorizer, and mutator handlers.
Q: Can Oathkeeper generate JWTs for upstream services? A: Yes. The id_token mutator creates signed JWTs containing session data that upstream services can verify.