Ory Oathkeeper Documentation

Ory Oathkeeper is an Identity & Access Proxy (IAP) and Access Control Decision API. It is designed for Zero-Trust network architectures and follows the BeyondCorp model.

Key capabilities include:

• Authenticating and authorizing HTTP requests.
• Acting as a reverse proxy or a standalone decision API.
• Mutating requests by injecting identity information.
• Integrating with existing API gateways and proxies.
• Supporting multiple authentication and authorization strategies.
• Decoupling security logic from application code.

Ory Oathkeeper is part of a larger ecosystem of identity and access management services designed for container orchestration systems (Kubernetes, CloudFoundry, OpenShift).

Key components include:

• Ory Oathkeeper: A Zero Trust Identity & Access Proxy (IAP) that handles authentication (JWT, Access Tokens, API Keys, mTLS), authorization, and request mutation (e.g., encoding user info into X-User-ID headers).
• Ory Kratos: Identity and User Management (Login, Registration, MFA, Profile management).
• Ory Hydra: OAuth2 and OpenID Connect Provider.
• Ory Keto: Access Control Policy engine (Policy Decision Point).

In version v0.37, regex capture groups from URL matchers can be used in several places, including the ID Token generator. However, existing keto_engine_acp_ory authorizers can no longer use the old regex substitution format (e.g., my:action:$1).

You must switch to the new Go template format: {{ printIndex .MatchContext.RegexpCaptureGroups 0}}.

Note: The index has changed by -1 compared to the old format. A rule migrator is available to make old rules compatible if a version string is provided.

In version v0.33.0-beta.1+oryOS.13, the hydrator mutator configuration changed from integer/count types to duration types.

To use the automatic migration feature, add "version": "v0.32.0-beta.1" to your existing access rules. Oathkeeper will then migrate the old config to the new format automatically.

{
  "version": "v0.32.0-beta.1",
  "mutators": [
    {
      "handler": "hydrator",
      "config": {
        "retry": {
          "delay_in_milliseconds": 500,
          "max_retries": 5
        }
      }
    }
  ]
}

The id_token mutator now uses Go text/template to render custom claims using the AuthenticationSession struct. The aud configuration key has been removed in favor of a claims key, which accepts a raw string representing a Go template.

{
  "handler": "id_token",
  "config": {
-    "aud": ["https://my-backend-service/some/endpoint"]
+    "claims": "{\"aud\": [\"https://my-backend-service/some/endpoint\"]}"
  }
}

As of v0.35.0-beta.1, the SDKs hosted within the Oathkeeper repository under ./sdk/... have been removed. You must use the official SDKs published to their respective package repositories:

• Python: ory-oathkeeper-client (PyPI)
• PHP: ory/oathkeeper-client (Packagist)
• Go: ory/oathkeeper-client-go (GitHub)
• NodeJS: @oryd/oathkeeper-client (NPM, includes TypeScript)
• Java: sh.ory.oathkeeper:oathkeeper-client (Maven)
• Ruby: ory-oathkeeper-client (RubyGems)

Breaking Changes:

• The Go SDK has renamed several structs and fields.
• All other SDKs have migrated to openapi-generator, which may result in different TypeScript definitions for NodeJS.

Short tests are designed to run quickly and use SQLite instead of external databases. You can run all short tests across the entire repository or target a specific module.

# Run all short tests
go test -short  ./...

# Run short tests in a specific module
cd internal/check
go test -short  .

To install Oathkeeper from source, ensure you have Go installed, then use the following commands to fetch the repository and run the install target via make.

cd ~
go get -d -u github.com/ory/oathkeeper
cd $GOPATH/src/github.com/ory/oathkeeper
make install

In version v0.14.0+oryOS.10, the Keto authorizer was updated to support the new ORY Keto engine concepts.

1. Rename Handler: Change the handler from keto_warden to keto_engine_acp_ory.
2. Add flavor option: A new optional flavor configuration key is available (defaults to regex).
3. Update Environment Variable: Rename AUTHORIZER_KETO_WARDEN_KETO_URL to AUTHORIZER_KETO_URL.

Example rule update:

{
  "id": "...",
  "upstream": ...,
  "match": ...,
  "authenticators": ...,
  "authorizer": {
-    "handler": "keto_warden",
+    "handler": "keto_engine_acp_ory",
    "config": {
      "required_action": "...",
      "required_resource": "...",
      "subject": "...",
+      "flavor": "exact" 
    }
  },
  "credentials_issuer": ...
}