Skip to main content

Introduction

ORY Oathkeeper authorizes incoming HTTP requests. It can be the Policy Enforcement Point in your cloud architecture, i.e. a reverse proxy in front of your upstream API or web server that rejects unauthorized requests and forwards authorized ones to your server. If you want to use another API Gateway (Kong, Nginx, Envoy, AWS API Gateway, ...), Oathkeeper can also plug into that and act as its Policy Decision Point.

The implemented problem domain and scope is called Zero-Trust Network Architecture, BeyondCorp, and Identity And Access Proxy (IAP).

While ORY Oathkeeper works well with ORY Hydra and ORY Keto, ORY Oathkeeper can be used completely standalone and alongside other stacks with adjacent problem domains (Keycloak, Gluu, Vault, ...). ORY Oathkeeper's Access Control Decision API works with

among others.

Dependencies​

ORY Oathkeeper does not have any dependencies to other services. It can work completely in isolation and does not require a database or any other type of persistent storage. ORY Oathkeeper is configurable with yaml configuration files, JSON files, and environment variables.

Operating Modes​

Starting Oathkeeper via oathkeeper serve exposes two ports: One port serves the reverse proxy, the other ORY Oathkeeper's API.

Reverse Proxy​

The port exposing the reverse proxy forwards requests to the upstream server, defined in the rule, if the request is allowed. If the request is not allowed, ORY Oathkeeper does not forward the request and instead returns an error message.

ORY Oathkeeper deployed as a Reverse Proxy

Example​

Assuming the following request

GET /my-service/whatever HTTP/1.1
Host: oathkeeper-proxy:4455
Authorization: bearer some-token

and you have the following rule defined (which allows this request)

{
  "id": "some-id",
  "upstream": {
    "url": "http://my-backend-service"
  },
  "match": {
    "url": "http://oathkeeper-proxy:4455/my-service/whatever",
    "methods": ["GET"]
  },
  "authenticators": [
    {
      "handler": "anonymous"
    }
  ],
  "authorizer": {
    "handler": "allow"
  },
  "mutators": [
    {
      "handler": "noop"
    }
  ]
}

then the request will be forwarded by ORY Oathkeeper as follows:

GET /my-service/whatever HTTP/1.1
Host: my-backend-service:4455
Authorization: bearer some-token

The response of this request will then be sent to the client that made the request to ORY Oathkeeper.

Access Control Decision API​

The ORY Oathkeeper Access Control Decision API follows best-practices and works with most (if not all) modern API gateways and reverse proxies. To verify a request, send it to the decisions endpoint located at the Ory Authkeeper API port. It matches every sub-path and HTTP Method:

  • GET /decisions/v1/api
  • PUT /decisions/my/other/api
  • DELETE /decisions/users?foo=?bar

When matching a rule, the /decisions prefix is stripped from the matching path.

ORY Oathkeeper deployed as an Decision API

Example​

Assuming you are making the following request to ORY Oathkeeper's Access Control Decision API

GET /decisions/my-service/whatever HTTP/1.1
Host: oathkeeper-api:4456
Authorization: bearer some-token

and you have the following rule defined (which allows this request)

{
  "id": "some-id",
  "match": {
    "url": "http://oathkeeper-api:4456/my-service/whatever",
    "methods": ["GET"]
  },
  "authenticators": [
    {
      "handler": "noop"
    }
  ],
  "authorizer": {
    "handler": "allow"
  },
  "mutators": [
    {
      "handler": "noop"
    }
  ]
}

then this endpoint will directly respond with HTTP Status Code 200:

HTTP/1.1 200 OK
Authorization: bearer some-token

If any other status code is returned, the request must not be allowed, for example:

HTTP/1.1 401 OK
Content-Length: 0
Connection: Closed

It is also possible to have this endpoint return other error responses such as the HTTP Status Found (HTTP Status Code 302), depending configured on the error handling. Use this feature only if your Reverse Proxy supports these type of responses.

Depending on the mutator defined by the access rule, the HTTP Response might contain additional or mutated HTTP Headers:

HTTP/1.1 200 OK
X-User-ID: john.doe

Decision Engine​

The decision engine allows to configure how ORY Oathkeeper authorizes HTTP requests. Authorization happens in four steps, each of which can be configured:

  1. Access Rule Matching: Verifies that the HTTP method, path, scheme, and host of the incoming HTTP request conform to your access rules. The information is taken either from the URL, or from the X-Forwarded-Method, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Uri headers (if present) of the incoming request. The request is denied if no access rules match. The configuration of the matching access rule becomes the input for the next steps.
  2. Authentication: Oathkeeper can validate credentials via a variety of methods like Bearer Token, Basic Authorization, or cookie. Invalid credentials result in denial of the request. The "internal" session state (e.g. user ID) of valid (authenticated) credentials becomes input for the next steps.
  3. Authorization: Access Rules can check permissions. To secure, for example, an API that requires admin privileges, configure the authorizer to check if the user ID from step 2 has the "admin" permission or role. Oathkeeper supports a variety of authorizers. Failed authorization (e.g. user does not have role "admin") results denial of the request.
  4. Mutation: The Access Rule can add session data to the HTTP request that it forwards to the upstream API. For example, the mutator could add X-User-ID: the-user-id to the HTTP headers or generate a JWT with session information and set it as Authorization: Bearer the.jwt.token.

Additionally, error handling can be configured. You may want to send an application/json response for API clients and a HTTP Redirect response for browsers with an end user.

ORY Oathkeeper Pipeline