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.

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 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 as the name of the action.

For example:

{ "name": "POST" }

Content

If the HTTP request contains Content, such as a 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.

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 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 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 to JSON String 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 must be included as an array of Field Lines 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 .

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.

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 of the certificate as defined by Section 7.2.1 in X509 19/10 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]
			}
		}
	]
}