# HTTP Request Information Model Extension

In some cases it is desirable to offer a Policy Enforcement Point for a generic HTTP gateway.

In order to enable interoperability with AuthZEN the values of generic HTTP requests need to be consistently mapped to the [AuthZEN Information Model](https://openid.github.io/authzen/authorization-api-1_0_01#name-information-model).

To ensure optimal interoperability this extension defines a uniform mapping of HTTP request properties to the AuthZEN Information Model.

## Subject

In the section below we describe what information regarding a generic HTTP request can or must be included in the `subject` section of the evaluation request.

### IP Address

If no domain-specific interpretation of subject ID is available you must use `ip-address` as `type` and the IP address in accordance with [RFC4001](https://datatracker.ietf.org/doc/html/rfc4001) as `id`.

For example:

{
	"type": "ip-address",
	"id": "127.0.0.1"
}

## Action

In the section below we describe what information regarding a generic HTTP request can or must be included in the `action` section of the evaluation request.

### Method

Use the [HTTP Request Method](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) as the name of the action.

For example:

{ "name": "POST" }

### Content

If the HTTP request contains [Content](https://www.rfc-editor.org/rfc/rfc9110#name-content), such as a [Message Body](https://www.rfc-editor.org/rfc/rfc9112#name-message-body) for a PUT or POST request, included it in the optional properties under the `request_content` field within the `http` field. The value must be [Base64 encoded](https://datatracker.ietf.org/doc/html/rfc4648#section-4).

For example:

{ 
	"name": "POST",
	"properties": {
		"http": {
			"request_content": "YnNuPTEyMzQ1Njc4Mg=="
		}
	}
}

## Resource

In the section below we describe what information regarding a generic HTTP request can or must be included in the `resource` section of the evaluation request.

### Uniform Resource Identifier

For the reource `type` use the identifier `uri`.

For the resource `id` use the [Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc3986.html) without `query` and `fragment`.

For example, the URI `https://example.com:8443/application/resources/1?active=true` would result in:

{
	"type": "uri",
	"id": "https://example.com:8443/application/resources/1"
}

### URI Components

Components of the URI should be included in the optional properties. Use the [ABNF rule name of the URI component](https://www.rfc-editor.org/rfc/rfc3986.html#appendix-A) the field name within the `http` field.

The following components must be included if they are present: `scheme`, `userinfo`, `host`, `port`, `path`, `fragment`.

For example, the URI `https://example.com:8443/application/resources/1?active=true` would result in:

{
	"type": "uri",
	"id": "https://example.com:8443/application/resources/1",
	"properties": {
		"http": {
			"scheme": "https",
			"host": "example.com",
			"port": "8443",
			"path": "/application/resources/1",
			"query": "active=true"
		}
	}
}

### Query Parameters

HTTP Query Parameters are frequently used as a convention to pass key-value pairs with requests.

These must be made available as a JSON object in the `parameters` field within the `http` field according to the following algorithm:

- Split the HTTP Query into tokens based on the ampersand (`&`) character.
- All characters before the equals sign (`=`) or the end of the token form the parameter key.
- All characters after the equals sign (`=`) form the parameter value. If the token does not contain an equals sign, the parameter value is a JSON `null` value.
- Convert parameter keys and values from [percent encoding](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) to [JSON String](https://datatracker.ietf.org/doc/html/rfc8259#section-7) representation.
- Include each parameter key and value as a field and value in a JSON Object.
- If parameter keys occur multiple times, the values are included in a JSON Array of values in the order of occurrence.

For example, the query parameter:

active=true&filter=last_name%3DJanssen&filter&filter=geboortejaar%3C2000&test%26%3D=%0A%22&expand

would result in

{
	"properties": {
		"http": {
			"parameters": {
				"active": "true",
				"filter": [
					"last_name=Janssen",
					null,
					"geboortejaar<2000"
				],
				"test&=": "\n\""
				"expand": null
			}
		}
	}
}

## Context

In the section below we describe what information regarding a generic HTTP request can or must be included in the `context` section of the evaluation request.

### HTTP Headers

The [HTTP Headers](https://www.rfc-editor.org/rfc/rfc9110.html#name-header-fields) must be included as an array of [Field Lines](https://www.rfc-editor.org/rfc/rfc9110.html#name-field-lines-and-combined-fi) under the `headers` field within the `http` field.

For example:

{ 
	"http": {
		"headers": [
			"Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
			"Accept-Encoding: gzip, deflate, br, zstd"
			"Host: www.example.com",
			"Connection: keep-alive"
		]
	}
}

### HTTP Version

If available, the HTTP version must be included under the `version` field within the `http` field as a value in accordance with [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-protocol-version) .

For example:

{ 
	"http": {
		"version": "HTTP/2"
	}
}

### X509 Client Certificate

If available, the client-side X509 certificate may be included under the `client_certificate` field within the `http` field in [PEM format](https://www.rfc-editor.org/rfc/rfc7468#section-5).

For example:

{ 
	"http": {
		"client_certificate": "-----BEGIN CERTIFICATE-----\nMII......\n-----END CERTIFICATE----- "
	}
}

### X509 Client Certificate Components

If desired, selected components of the client certificate may be made available as a JSON objects under the `client_certificate` field.

The [ASN.1 data type](https://www.itu.int/rec/T-REC-X.680) of the certificate as defined by [Section 7.2.1 in X509 19/10](https://www.itu.int/rec/T-REC-X.509-201910-I/en) must be used for this.

The components `serialNumber`, `issuer`, `subject`, `validity` are required. Within validity `notBefore` and `notAfter` components are required. Additional components *may* be included.

The below rules must be followed for representing ASN.1 data types in JSON:

- A `Time` data type must be represented as a string containing an ISO 8601 format with qualified timezone.
- A `NUMBER` data type must be represented as numeric value.
- An `EXTENSION` data type must be modeled as an object with a single field with the name of the ASN.1 type identifier. E.g. `{ "subjectAltName": .... }`.
- A `CHOICE` data type must be represented as an object with a single field with the name of the ASN.1 choice identifier. E.g. `{"dNSName": "www.example.com"}`.
- An `ENUMERATED` data type must be represented as a string with the name of the enumerated value.
- A `SEQUENCE` data type with named values must be represented as object with field names identical to the named values. Variable length values within the sequence must be represented as array values.
- A `SEQUENCE` data type must be represented as an array of values.
- A `NUMBER` data type must be represented as numeric value.
- A `BOOLEAN` data type must be represented as a boolean value.
- A `BIT STRING` data type with named values must be represented as an array containing strings of the names of the flags.
- `BIT STRING` and `OCTET STRING` data types are represented as hex-encoded bytes separated by a colon.

See the below example demonstrating the various data types as used in X09 certificates:

"client_certificate": {
	"serialNumber": 12345,
	"issuer": "C=US, O=Let's Encrypt, CN=R10",
	"subject": "CN=testuser",
	"validity": {
		"notBefore":"2000-01-01T00:00:00Z",
		"notAfter":"2002-12-31T23:59:99Z"
	},			
	"extensions": [
		{
			"subjectAltName": [
				{
					"dNSName": "www.example.com"
				},
				{
					"dNSName": "smtp.example.com"
				}
			]
		},
		{
			"keyUsage": [
				"digitalSignature", 
				"keyEncipherment"
			]
		},
		{
			"authorityKeyIdentifier": {
				"keyIdentifier": "12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78"
			}
		},
		{
			"basicConstraints": {
				"cA": true,
				"pathLenConstraints": [1, 2, 3]
			}
		}
	]
}