PingAuthorize

API security gateway policy request attributes

The API security gateway generates a set of attributes from inbound and outbound HTTP traffic. These attributes are available to access control policies and reflect details such as the HTTP request, the access token, client certificates, and gateway-specific routing information.

These attributes are automatically included in defaultPolicies.SNAPSHOT in the Policy Editor distribution.

The following table describes these attributes:

Top-level Gateway request attributes

Attribute Value type Description

action

String

Returns the request processing phase and the HTTP method.

This value is formatted as <phase>-<method>. Example values include inbound-GET, inbound-POST, outbound-GET, and outbound-POST.

attributes

Object

Returns additional attributes that don’t correspond to a specific element type in the Trust Framework.

You can find more information in the next table.

domain

String

This value isn’t used.

identityProvider

String

Returns the name of the access token validator that evaluates the bearer token in an incoming request.

service

String

Returns an identifier for the API service.

By default, this value is set to the name of the Gateway API Endpoint. To override the default value, set the Gateway API Endpoint’s service property.

Multiple Gateway API Endpoints can use the same service value.

Additional request attributes

The following table describes the additional attributes included in attributes.

Attribute Value type Description

Gateway

Object

Returns gateway-specific information about the request not provided by the other attributes in this table.

HttpRequest.AccessToken

Object

Returns the parsed access token.

You can find more information on this object in Access token attributes.

HttpRequest.ClientCertificate

Object

Returns properties of the client certificate, if one was used.

You can find more information on this object in Client certificate attributes.

HttpRequest.CorrelationId

String

Returns the ID that uniquely identifies the request and response, if available.

HttpRequest.IPAddress

String

Returns the client IP address.

HttpRequest.QueryParameters

Object

Returns the request URI query parameters.

HttpRequest.RequestBody

Object

Returns the request body, if available.

HttpRequest.RequestHeaders

Object

Returns the request headers.

HttpRequest.RequestURI

String

Returns the request URI.

HttpRequest.ResourcePath

String

Returns the portion of the request URI path that follows the inbound base path defined by the Gateway API Endpoint.

HttpRequest.ResponseBody

Object

Returns the response body, if available.

This attribute is only provided for outbound policy requests.

HttpRequest.ResponseHeaders

Object

Returns the response headers, if available.

HttpRequest.ResponseStatus

Number

Returns the response status code, if available.

TokenOwner

Object

Returns the access token subject as a SCIM resource, as obtained by the access token validator.

Access token attributes

The following table describes the child attributes of HttpRequest.AccessToken. These attributes are populated by the access token validator.

These attributes correspond approximately to the fields defined by the IETF Token Introspection specification: RFC 7662.

Attribute Value type Description

access_token

String

Returns the access token from the client request.

active

Boolean

Indicates whether this access token is currently active, as determined by the access token validator.

audience

String[]

Returns the recipients for whom the access token is intended. Typically, the authorization server sets this field to identify the resource servers that can accept the token.

authentication_age

Number

Returns the number of seconds since the end user was authenticated by the token issuer.

This attribute uses the System Current DateTime resolver and a SpEL processor to calculate the number of seconds since the authentication_time. This calculation requires the auth_time claim in the access token.

authentication_policy

String

Returns the authentication policy that was satisfied when the access token was issued. An authentication policy is also called an authentication context class reference (ACR).

If the access token contains an acr claim, this attribute uses a JSON Path processor to extract the date and time from the HttpRequest.AccessToken attribute.

authentication_time

Zoned Date Time

Returns the date and time when the end user was authenticated.

If the access token contains an auth_time claim, this attribute uses a JSON Path processor to extract the date and time from the HttpRequest.AccessToken attribute. If the claim is missing from the token, the default value is January 1, 1970.

client_id

String

Returns the client ID of the application that was granted the access token.

expiration

DateTime

Returns the date and time at which the access token expired.

issued_at

DateTime

Returns the date and time at which the access token was issued.

issuer

String

Returns the token issuer.

Typically, this value is a URI that identifies the authorization server.

not_before

DateTime

Returns the date and time before which a resource server doesn’t accept an access token.

scope

Collection

Returns the list of scopes granted to this token.

subject

String

Returns the token subject.

This value represents a user identifier set by the authorization server.

token_owner

String

Returns the user identifier resolved by the access token validator’s token resource lookup method.

This value is a SCIM ID of the form <resource type>/<resource ID>.

token_type

String

Returns the token type set by the authorization server.

Typically, this value is bearer.

user_token

Boolean

Returns a flag set by the access token validator to indicate whether the token includes a subject. When this flag is false, the token contains no subject and was issued directly to a client.

username

String

Returns the subject’s user name.

This value represents a user identifier set by the authorization server.

Client certificate attributes

The following table describes the child attributes of HttpRequest.ClientCertificate:

Attribute Value type Description

algorithm

String

Returns the name of the certificate signature algorithm, such as SHA256withRSA.

algorithmOID

String

Returns the signature algorithm OID.

issuer

String

Returns the distinguished name (DN) of the certificate issuer.

notAfter

DateTime

Returns the expiration date and time of the certificate.

notBefore

DateTime

Returns the earliest date on which the certificate is considered valid.

subject

String

Returns the DN of the certificate subject.

subjectRegex

String

Returns the regular expression that must be matched by the subject field of the certificate to ensure the certificate belongs to the requesting client.

valid

Boolean

Indicates whether the SSL client certificate is valid.

Gateway configuration attributes

The following table describes the child attributes of Gateway:

Attribute Value type Description

BasePath

String

Returns the portion of the HTTP request URI that matches the Gateway API Endpoint’s base-path value.

TrailingPath

String

Returns the portion of the HTTP request URI that follows the BasePath.

Base path parameters

String

Returns parameters defined in the Gateway API Endpoint’s base-path configuration property.

Custom attributes

String

Returns custom attributes that are defined in the Gateway API Endpoint’s policy-request-attribute configuration property.