# AuthZEN REST API Gateway Profile proposal

Author: Omri Gazitt
Initial draft: Jan 13 2025
Update: Feb 20 2025
Update: Feb 22 2025: "user" -> "identity"

## Context

API Gateways are natural AuthZEN Policy Enforcement Points (PEPs).

An API gateway executes a set of filters before forwarding the request to the endpoint that it is proxying, and can execute a set of filters before returning the response to the caller.

API gateway filters are meant to execute with very low latency (a small number of milliseconds), since they are in the execution path of every request.

One such filter can be an AuthZEN call to a compliant PDP.

## Purpose

The purpose of an AuthZEN filter is to translate between the HTTP Information Model (see below) and the [AuthZEN information model](https://openid.github.io/authzen/#name-information-model).

Ideally, the filter implementation allows the developer to indicate which HTTP elements (method, path, headers, body) to map into which fields of the AuthZEN evaluation request.

So why define an AuthZEN profile for API gateways? To provide a simple mapping as a sensible default (which a developer can ideally override).

This in turn can accelerate the process of enabling API Gateways to easily become AuthZEN clients.

## Scope

This profile focuses on the HTTP transport and specifically the REST pattern (as opposed to GraphQL).

## Principles

In keeping with the principle of "convention over configuration", this proposal offers a set of reasonable defaults, but also enables overriding those defaults.

## Scenarios

This profile covers two scenarios:
1. *"Medium-grained authorization"*: answering the question "can this subject invoke this REST endpoint". In this context, a "REST endpoint" refers to an **{ HTTP Method, HTTP route }** tuple. In this scenario, the gateway offers a "defense in depth" capability by authorizing the endpoint, but the target endpoint's implementation is responsible for fine-grained authorization associated with what the endpoint actually does.
2. *"Fine-grained authorization"*: placing the responsibility on the API gateway for determining whether a subject can perform an action on a fine-grained resource managed by the target endpoint.

In the *medium-grained authorization* scenario, this proposal lays out a protocol that utilizes the required fields of the AuthZEN payload format (*subject type, subject id, action name, resource type, resource id*) to precisely identify the subject (user) and the resource (endpoint).

In the *fine-grained authorization* scenario, the policy managed by the PDP is responsible for doing the "heavy lifting" of determining which of the HTTP information model fields are relevant for authorization. The gateway simply maps the HTTP information model to the AuthZEN information model in a predictable way, and the PDP policy does the rest.

## HTTP REST information model

The following HTTP information model elements are semantically important and therefore need to be mapped to the AuthZEN information model:

- HTTP method
- HTTP URI
- hostname
- path
- matched route
- path parameters
- query / query parameters
- HTTP headers
- HTTP body

## Mappings

AuthZEN's [information model](https://openid.github.io/authzen/#name-information-model) defines a **subject**, **action**, **resource**, and **context** for a well-formed AuthZEN payload. The mappings are given below.

### Subject

An authenticated call to an API gateway typically contains an `Authorization` header with some kind of token (e.g. `Basic`, `Bearer`).

The subject of the authorization request is commonly identified by a claim in that token.

The most common token found in web systems is a `JWT`, and the most commonly used claim to identify the subject is the `sub` claim.

It is RECOMMENDED that the API Gateway validate the JWT in the Authorization header as part of its request processing.

If the gateway does this, it will have extracted the `sub` claim out of the JWT (noted below as `<JWT.sub>`). It is RECOMMENDED that the gateway format the `subject` in the AuthZEN request as follows:

{
  "subject": {
    "type": "identity",
    "id": "<JWT.sub>"
  }
}

If the API Gateway does not process the Authorization header, it MAY utilize the AuthZEN JWT profile to format the `subject`, discussed below.

The [AuthZEN JWT profile](https://hackmd.io/6rB2M7e3QuWUo2MBEKZ8nw?view) defines how to map a JWT found in the `Authorization` header to a `type` / `id` in the following way:

GET /my-endpoint HTTP/1.1
Host: example.com
Authorization: Bearer <JWT>

AuthZEN subject payload:

{
  "subject": {
    "type": "JWT",
    "id": "<JWT>"
  }
}

Example:

GET /my-endpoint HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ

The JWT above has the following payload:

{
  "sub": "1234567890",
  "email": "[e-mail]",
  "name": "John Doe",
  "iat": 1516239022
}

The API Gateway would formulate the AuthZEN payload `subject` in the following way:

{
  "subject": {
    "type": "JWT",
    "id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ"
  },
  ...
}

In this case (which corresponds to the "fine-grained authorization" scenario), the PDP is responsible for decoding the JWT, and using the `sub` claim from the JWT as the subject of the call (in this case, `1234567890`).

#### Overriding the default subject claim

The API Gateway MAY allow the developer to override the default claim that the PDP uses by providing a mechanism for the developer to specify the `subject.properties.subject_claim` property in the subject payload.

#### Overriding the default extracted subject type

The API Gatway MAY allow the developer to override the default type for the extracted subject (which is `"identity"`) by providing a mechanism for the developer to specify the `subject.properties.subject_type` property in the subject payload.

### Action

The `action.name` field is required for an AuthZEN request. A compliant API Gateway passes the **HTTP method** as the `action.name`.

Example:

GET /my-endpoint HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ

AuthZEN request:

{
  "subject": {
    "type": "identity",
    "id": "1234567890"
  },
  "action": {
    "name": "GET"
  },
  ...
}

#### Action Request Body

An HTTP request has a body that MAY be relevant for fine-grained authorization scenarios. However, the body is often expensive to deserialize, and may actually be a stream.

An HTTP gateway MAY offer the developer the option of deserializing the body, although it is RECOMMENDED that this mapping is turned off by default, given the fact that the body could be too large to practically deserialize, or may be a streamed request.

In the event that a developer chooses the option to deserialize the body and map it into an AuthZEN request, the gateway SHOULD determine the deserialization format from the `content-type` field of the request. For example, `application/json` deserializes into a string in the format produced by `JSON.stringify`. This string is then provided as the value of the `action.properties.body` field.

Example:

POST /api/v1/pets/123?format=json HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ
Content-type: application/json
X-Tenant-ID: acmecorp

{ "foo": "bar" }

AuthZEN request:

{
  "subject": {
    "type": "identity",
    "id": "1234567890"
  },
  "action": {
    "name": "POST",
    "properties": {
      "body": "{ \"foo\": \"bar\" }"
    }
  },
  "resource": {
    "type": "route",
    "id": "/api/v1/pets/{id}",
    "properties": {
      "uri": "https://example.com/api/v1/pets/123?format=json",
      "scheme": "https",
      "hostname": "example.com",
      "path": "/api/v1/pets/123",
      "route": "/api/v1/pets/{id}",
      "params": {
        "id": "123"
      },
      "query": {
        "format": "json"
      },
      "ip": "10.1.2.3"
    }
  },
  "context": {
    "headers": {
      "Content-type": "application/json",
      "X-Tenant-ID": "acmecorp"
    }
  }
}

### Resource

The `resource.type` and `resource.id` fields are required for an AuthZEN request. By default, a compliant API Gateway maps the **HTTP Route** designated below as `<route>` in the following way:

`resource.type`: "route"
`resource.id`: `"<route>"`

The HTTP Route is analogous to the ["patterned path fields"](https://swagger.io/specification/#paths-object) defined in the OpenAPI Specification.

If the matched HTTP route is not available to the API gateway, it MAY instead default to using the URI as the resource:

`resource.type`: "uri"
`resource.id`: `"<uri>"`

Additional information is provided in the `resource.properties` object in the following manner. The following MUST be provided:

| Request | AuthZEN field | Type |
| -------- | -------- | -- |
| URI | `resource.properties.uri` | String |
| scheme | `resource.properties.scheme` | String |
| hostname | `resource.properties.hostname` | String |
| path | `resource.properties.path` | String |
| route parameters | `resource.properties.params` | Object |
| query | `resource.properties.query` | Object |

Additional parsed Request fields MAY be provided as well.

For example:

| Request | AuthZEN field | Type |
| -------- | -------- | -- |
| hostname | `resource.properties.hostname` | String |
| ip | `resource.properties.ip` | String |

Example:

GET /api/v1/pets/123?format=json HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJqb2huLmRvZUBhY21lY29ycC5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.aO9qA3_RZGNiIT_9taln8e4_IoWFuOYUZSC1LbfqPTQ

Matched route: `/api/v1/pets/{id}`.

AuthZEN request:

{
  "subject": {
    "type": "identity",
    "id": "1234567890"
  },
  "action": {
    "name": "GET"
  },
  "resource": {
    "type": "route",
    "id": "/api/v1/pets/{id}",
    "properties": {
      "uri": "https://example.com/api/v1/pets/123?format=json",
      "scheme": "https",
      "hostname": "example.com",
      "path": "/api/v1/pets/123",
      "route": "/api/v1/pets/{id}",
      "params": {
        "id": "123"
      },
      "query": {
        "format": "json"
      },
      "ip": "10.1.2.3"
    }
  }
}

### Context

An HTTP request can have an arbitrary set of headers.

An API Gateway that complies with this profile sends the full set of headers in the `context.headers` field.