oathkeeper: the guaranteed CVE fixes are the paid part

Two roles from one rule set: reverse proxy and decision endpoint

The definition at the top is precise about what this is. An identity and access proxy and an access control decision API, authorizing HTTP requests based on sets of access rules, following the model Google designed for zero-trust networks.

Two roles come out of that. It can sit in front of an application as a reverse proxy that makes the decision and forwards the request, or it can answer a decision question for something else that is already terminating traffic. The same rules describe both.

The listed capabilities describe the same idea from six angles: it authenticates and authorises requests, it acts as either role, it mutates requests by attaching identity information, it integrates with existing gateways and proxies, it supports several authentication and authorisation strategies at once, and it is meant to run inside zero-trust architectures.

Then the reasons it is built this way, and the first is the important one. Authentication and authorisation are decoupled from application code. A rule set lives in the proxy, not in each service, which is the entire argument for this category of software.

The rest are deployment claims: it works as a gateway plugin or standalone, it takes rules per endpoint, it scales in cloud-native environments, and it offers both proxy and sidecar modes.

Integration means using someone else's hook, named one by one

The integrations section is the most useful part of the readme, because it names the mechanism rather than asserting compatibility.

Four hosts are listed with the specific extension point in each. One mesh gateway is integrated through its authentication service. One proxy is integrated through its external authorisation HTTP filter, which is the standard hook a proxy exposes for asking an external component about a request. One managed API gateway is integrated through its custom authorizers mechanism. And one web server is integrated through authentication based on the result of a subrequest, which is that server's own way of delegating the question to another process.

That is the honest shape of this category of tool. Oathkeeper does not sit in the mesh or replace the gateway; it answers a question the gateway is already able to ask. Which means your gateway's hooks determine how much of Oathkeeper you can use, and the readme's list is effectively a compatibility matrix.

The sidecar mode is the answer for the cases with no hook. It is mentioned once, in the reasons list, and it inherits the properties of any sidecar: the decision is made somewhere else, and the network path to it is now part of your request path.

The open distribution is pitched at workloads without SLAs

The installation section draws a line that most projects blur, and the wording is unusual enough to quote.

The install guide uses the open source distribution to get started without licence requirements, and the readme says it suits individuals, researchers, hackers, and companies that want to experiment, prototype, or run unimportant workloads without service level agreements. It adds that you get the full core engine and are free to inspect it, extend it, and build it from source.

So the open part is not a crippled tier. It is the engine, complete, with the source, and the recommendation for it is honest about when you do not need it.

The guide covers the platforms you would expect: Linux, macOS, Windows and containers, plus configuration of access rules and authentication strategies and deployment to Kubernetes and other orchestrators.

What is missing from the open path, by omission rather than by statement, is a promise. If your workload is business critical, the readme says to use a commercial agreement to reduce operational and security risk, and the next section lists what that agreement contains.

Guaranteed patches, service levels and a private registry are the commercial list

The enterprise licence section is the most concrete commercial description in the document, and it is worth reading as a list of what the open path does not include.

The licence layers on top of the self-hosted engine and provides: enterprise features that are not in the open source version; regular security releases including patches for published vulnerabilities, with service level agreements; support for advanced scaling, multi-tenancy and complex deployments; premium support with service levels, direct access to engineers and onboarding; and access to a private container registry with frequent, vetted, up-to-date builds.

Then the sentence that makes it concrete: for guaranteed vulnerability fixes, current enterprise builds, advanced features and production support, you need a valid licence and access to the private registry.

The distinction being sold is therefore not capability but assurance. Anyone can patch an open source project. What the licence buys is a schedule, a contractual level, and a build you do not assemble yourself.

One detail in the repository is worth pairing with that paragraph. The tree contains a file whose name is the ignore list for a Go vulnerability scanner, which means the project does track advisories against its own dependency tree in the open repository. Tracking is not the same as guaranteeing, and the readme is careful to sell only the second.

The readme's contents list is generated by the only npm script

The package manifest in a Go project is usually a footnote. Here it is the clearest description of the documentation tooling.

The manifest is private, its version is a placeholder because it is not the Go module, and it declares the same licence the repository does. It has exactly one script, and that script regenerates the readme's table of contents.

Which matches the file itself: the contents block is wrapped in comments that say it was generated, that it should not be edited, and that it should be regenerated instead. The heading is not hand-maintained.

The rest of the manifest is tooling. A documentation generator for API references is a pinned dependency rather than a development one, because building the reference is part of producing the project. A licence checker, the formatter and the table-of-contents tool are pinned development dependencies with exact versions.

And then the overrides block, which pins four transitive packages to minimum versions or, in one case, to an exact version. A library that quotes shell arguments is exactly the kind of transitive dependency an override list exists for, and its presence says something about how this project treats its dependency tree.

Every build tool is fetched over the network, and one is not pinned

The Makefile is a toolchain installer with a few targets attached, and reading it tells you what a contributor needs.

Five tools are downloaded into a local binary directory when they are missing. The documentation generator is built from a command package in this repository. The import formatter is installed at its latest version. A licence checker and the project's own multi-purpose command line tool come from two separate upstream install scripts, the latter pinned to a specific release. The linter is installed from its own upstream script at a pinned version.

So four of five are pinned and one tracks the newest release. Each of those download steps retries seven times on a refused connection, which is a sensible concession to CI networks.

The dependencies are declared against the Makefile's own timestamp rather than a stamp file, so touching the Makefile re-downloads the tools. The formatter is the exception: its version is read out of the package manifest at build time, printed by the format target, and then invoked through a one-off package runner rather than from the installed tree. One version, defined once, used by both the dependency list and the command line:

	npx --package=prettier@$(PRETTIER_VERSION)  prettier . --write

Two upstream modules are replaced by directories in this tree

The Go module file contains two replacement directives, and both point at directories inside the repository rather than at published versions.

One maps a general-purpose shared library used across the company's projects onto a directory here. The other maps a test helper onto a directory nested inside the middleware package rather than beside its siblings. Neither is at a tagged version, because neither is coming from the module proxy.

That pattern means part of what a reader sees as this project's code is actually a fork or a vendored copy of an upstream library, which matters for two reasons: an audit of this repository's dependencies has to include those directories, and an update to the upstream library does not arrive by bumping a version.

The dependency list is also instructive about a security-sensitive project in 2026. It carries two JSON web token libraries and two JSON object signing and encryption libraries at once, plus an OAuth2 server library, an authentication middleware published by a commercial identity vendor, a cloud provider's storage and pipeline clients, a caching library, a metrics client, a configuration library and a templating library. That is the price of a component that has to authenticate against many providers, and it is why the linter and the advisory ignore list exist alongside it.

Two of the company's own libraries are pinned to untagged commits rather than releases, which is the other way to get a fix in ahead of cutting a version.

The local compose file samples every request

The development compose file is small and says something about the default posture.

The service builds from a dockerfile whose name does not appear in the tree listing, publishes two ports, and runs the serve command against a configuration file mounted from a local directory. It restarts on failure, which is the right default for a proxy in a development stack and the wrong default in production, where a crash loop can hide a misconfiguration.

The tracing configuration points at a single-process collector and sets the sampling type to constant with a value of one. That means every request is sampled. For a local stack that is the useful setting, because a developer working on the decision path wants to see the request they just made. For a deployed service with real traffic it would be a very expensive setting, and it is worth noticing that it is the one written down here.

The collector's user interface port is published and its data collection ports are left commented out, which is a small piece of housekeeping that saves someone an afternoon of wondering why nothing arrives.

Everything else in the tree follows the same pattern of a large service: a command directory, an API directory, packages for the proxy, the rule engine, storage drivers and middleware, generated schema directories, an upgrade document, a development document, and a coverage configuration.

Editorial conclusion

Oathkeeper fits a team with an existing gateway that has a hook for asking someone else about a request, and who wants authorisation policy in one place rather than in each application. Two things to weigh before you commit. The integration story is precise, which is a strength, but it also means your choice of gateway constrains how you deploy it, and the sidecar mode is the fallback rather than the first-class path. And the licensing split deserves a decision: the core engine is complete enough to build and inspect yourself, while the sold part is the guarantee, the service level and the vetted build. If you run this somewhere an outage or an unpatched advisory matters, that is a budget conversation, and the readme is unusually direct about it. If you are experimenting, the open distribution is explicitly the recommended path.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. ory/oathkeeper on GitHub
3. Project website
4. README
5. Releases