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.

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:

"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.
"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 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 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": "john.doe@acmecorp.com",
  "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" 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.

mtrimpe

2025/01/14 13:05:31

query

I was also surprised; but there is no universal standard for mapping a query string to an object. It's merely a convention based on the behavior of HTML <form>'s. Partially due to that fact a common attack vector is to include a query parameter twice and exploit the fact that one system might only check the first parameter while another system might only check the value of the last parameter. I worked out a simple standard and method for mapping query string to object's in my HTTP Request Information Model (https://hackmd.io/@oidf-wg-authzen/HJR-hCCE1e ) to address those concerns.

Omri Gazitt

2025/01/14 19:41:56

For query, I would actually leave the processing to the API gateway implementation. Each gateway has a way of making route parameters and query parameters available to the caller in parsed format. I would advocate for keeping the spec simple rather than creating new canonicalization rules.

David Brossard

2025/01/28 22:45:25

Agreed. It's up to the API GW to determine how to handle multiple queries with the same name. BTW JSON suffers from the same problem

2025/01/14 13:08:12

hostname

The hostname might not always be available. If we require it then we might force implementers to perform a possibly expensive reverse DNS lookup from an IP just to be compliant.

2025/01/14 19:25:45

I went through the Express Request object to see what would be interesting to mandate. I agree that if a field is not universal and easy to extract, it should not be mandated.

2025/01/20 05:31:15

I was intending for this to only be the hostname component of the URI

2025/01/14 13:08:55

IP might not yet be available either if only the hostname is available but the has not been resolved yet (i.e. the request has not yet been performed.)

2025/01/24 10:25:32

@omri Which IP do we actually mean here? The client IP? Or the target IP of the HTTP request (e.g. https://127.0.0.1/test) ?

2025/01/14 13:14:26

Similar to the concern around query parameters; but how do we handle duplicate Header entries in this case? We can use the same approach as I suggested for query parameters or we can consider using the Combined Field Lines concept (https://www.rfc-editor.org/rfc/rfc9110.html#name-field-lines-and-combined-fi)

2025/01/15 00:07:22

I get your statement better now. The current request already seems to specify some JSON structure already though (i.e. query params and headers are represented by an object with string key value pairs.) It should then be clear that it can be any JSON element then (string, array, object, etc. etc.) I'd say for interop you'd actually want to specify this; but I also agree that ideally the API Gateway providers should align/agree on this. (Edited)

Alex Babeanu

2025/01/23 15:38:59

Just a textual discrepancy, the example is a POST, the request is a GET. Also in my mind the body would also be in the resource. (add a "body" element under "query" for example) , and the IP if definitively a context, like the headers.

2025/01/28 22:43:14

IMHO body does go to resource, not context. Also, we may want to make sending the body optional to avoid overloading the authzen request

2025/01/14 13:17:48

Can we suggest the same convention here as I recommended in my document? To use the ABNF name from the original URI specification... See https://hackmd.io/@oidf-wg-authzen/HJR-hCCE1e?stext=2455%3A210%3A0%3A1736860564%3A_XuVI4

2025/01/14 19:23:47

That makes sense to me.

2025/01/14 13:26:07

How do we want to handle PUT/POST body content here? We have a lot of use cases where query parameters are sent in a POST-body because they contain PII and the senders are afraid of having those end up in HTTP request logs. And of course classic HTTP <form> request also end up in the POST body. It must be an optional field of course though as we don't want multi-GB files to show up there. (Edited)

2025/01/14 23:38:13

context.body (Edited)

2025/01/15 00:24:30

@mtrimpe Q: what should the type of the body be? - string-valued? (where the string may need to be base64-encoded, since the body could have characters like \0?) - JSON object-valued? (e.g. if the content-type is application/json)? - should the PEP be "smart" and have different behavior based on the content-type header? (e.g. form-encoded produces one behavior, application/json produces another?)

2025/01/15 10:06:46

That's tricky indeed. If we leave query and headers format open then we should probably do the same for this. Looking at the HTTP spec (https://www.rfc-editor.org/rfc/rfc9112#name-message-body) it says a request body is present if Content-Length or Transfer-Encoding is present so perhaps we should focus on defining those at least. I'd be tempted to even leave out Transfer-Encoding altogether and specify that when Transfer-Encoding is present but Content-Length isn't (streaming uploads) a Content-Length of -1 should be used to indicate that a body of unknown length is present. Then by just adding the ability to specify content length we at least enable policies to act on the knowledge *if* a body is present.

2025/01/14 19:48:32

"<request-path>"

I struggle with what the best resource ID would be. Ideally, it should actually be the parameterized route, because the target of the authorization is the route, not the specific path. At the API gateway layer, I want to authorize whether the user can issue a GET on the /api/v1/pets/{id} route, not whether the user has permission to retrieve the /api/v1/pets/1 resource. This second scenario should be done in the application, not the gateway, at least IMO.

2025/01/28 22:47:44

yes I am not sure which is best. In principle, if we did some parsing then id would be the resource's actual ID (the variable part of the route) but if we want this to be the simplest possible integration then it makes sense to adopt route because policies can be structured based on the route and the ID can later be extracted in the PDP

2025/01/24 10:09:04

resource.properties.params

I'd suggest naming this `resource.properties.route_params` to prevent confusion with query parameters. (Edited)

2025/01/24 10:21:10

query resource.properties.query Object

The 'query' is generally understood/specified as the full string. The query parsed into key-value pairs as per https://url.spec.whatwg.org/#application/x-www-form-urlencoded is generally understood as 'query parameters' Should we split this into `query` of type String and `query_parameters` of type Object? Or define `query` this as type Object *or* String? (Edited)

2025/01/24 11:01:49

of the context.body field.

I'd add something like: "If the `context.body` field is present but contains JSON `null` value then the request is assumeed to not have a body."

2025/01/28 22:37:21

A PDP will generally consider that the token has been validated hence this recommendation.

2025/01/28 22:38:41

:{ "subject": { "type": "user", "id": "<JWT.sub>" } } If th

Would type be the type of token rather than the type of identity? We don't necessarily know we are dealing with a user...

2025/01/28 22:39:39

Nevermind, I had not seen the .sub at the end of jwt...

2025/01/28 22:39:08

AuthZEN subject payload:{ "subject": { "type": "JWT", "id": "<JWT>" } } Ex

Yes, that makes sense

2025/01/28 22:41:09

In the example below, id="/api/v1/pets/{id}" but shouldn't it be equal to the actual path e.g. "/api/v1/pets/123"?

2025/01/28 22:41:39

in other words id should be equal to path, rather than route

2025/02/07 14:26:07

@omri we should look into OpenAPI and how it can inform the mapping for the GW to the PDP

Pim G

2025/03/05 08:25:15

route parameters resource.properties.params Object

above it is mentioned that if the "matched HTTP route is not available to the API gateway, it MAY instead default to using the URI as the resource:" However, the "route parameters" are in the MUST table. This is conflicting, I suggest moving the "route parameters" to the MAY table.

AuthZEN REST API Gateway Profile proposal

Context

Purpose

Scope

Principles

Scenarios

HTTP REST information model

Mappings

Subject

Overriding the default subject claim

Overriding the default extracted subject type

Action

Action Request Body

Resource

Context

Read more

Partial Evaluation Cedar Meeting

Meeting Notes 2025-04-08

Identiverse AuthZEN Interop Demo

Revised Spec