The agent makes an agent request after it receives a client request to determine what action to take in response. PingAccess then returns an agent response to the agent that communicates how to proceed.

The Request-Line of the agent request is identical to the Request-Line of the client request. Unless otherwise specified, all headers in the agent request are sent as they appear in the client request. The agent request effectively mirrors the client request, except that the message-body of the client request is omitted from the initial agent request.

If PingAccess needs the message-body, PingAccess returns an HTTP 477 response, as defined in PAAP agent response. The message-body is omitted from the initial agent request because PingAccess doesn't need it to make a policy decision in most cases, and removing the message-body makes performance more efficient. The HTTP 477 response mechanism provides PingAccess a way to get the message-body if it's necessary.

HTTP request headers

The following HTTP request headers might require additional agent processing:

Content-Length

The Content-Length header in the agent request has a value matching the message-body of the request being sent. For the initial agent request, which is sent without the message-body, the Content-Length is 0. A subsequent agent request resulting from a 477 response sends a Content-Length that indicates the size of the entity-body of the request, which is the same as in the client request.

vnd-pi-agent
This header lets the agent communicate details of its configuration for optional logging purposes. The agent might specify the custom keys specific to the deployment of the agent, or utilize one or more of the well-known keys.
v
The version of the agent making the request.
t
The type of agent and/or the type of platform where the agent resides.
h
The hostname of the server where the agent resides.

These header examples are considered semantically equivalent.

vnd-pi-agent: v="1.0.0", h="apache.example.com", t="Apache 2.4.41"
vnd-pi-agent: v="1.0.0", h="apache.example.com"
vnd-pi-agent: t="Apache 2.4.41"
vnd-pi-agent: v="1.0.0"
vnd-pi-agent: h="apache.example.com"
vnd-pi-agent: t="Apache 2.4.41"

The syntax for the vnd-pi-agent value conforms to a dictionary in this specification, https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html#dictionary, where member-values are constrained to be an sh-string item.

For more information, see Agent inventory logging.

vnd-pi-expect

This header allows the agent to communicate its needs to PingAccess. !477 is the only defined value, which tells PingAccess that the agent request contains all the data the agent it is capable of sending regarding the client request. PingAccess should never respond with a 477 to an agent request that has !477 as the value of the vnd-pi-expect request header. While the expect header from RFC 2616 with an expectation-extension could convey the same semantics, Ping Identity elected not to use it due to language in the RFC that suggests intermediaries might, should, or must reject a request using an expectation-extension they don’t understand with a 417.

A simple and effective approach for an agent implementation is to send the initial agent request with no body, a content-length of zero, and omitting the vnd-pi-expect header. The header vnd-pi-expect: !477 is only ever sent when an agent receives a 477 response to its initial request. In other words, the initial agent request never has a vnd-pi-expect header, while a second agent request in response to an HTTP 477 response always has !477 as the value for the vnd-pi-expect header.

PingAccess should never respond to a GET request with a 477, but following this standard allows an agent to handle such an occurrence in an appropriate way.

vnd-pi-v

Indicates the version of PAAP the agent is using. The value is 1.0

vnd-pi-authz

This header is similar to the authorization header defined in RFC 2616 but is specifically intended to enable an agent to authenticate itself to PingAccess. The syntax for the “credentials” value of the header is the same as the section 2.1 of The OAuth 2.0 Authorization Framework: Bearer Token Usage .

The header looks like this:

vnd-pi-authz: Bearer <token>

Where <token> is a secret shared between PingAccess and the PAA.

In some cases, unrestricted access to the agent protocol at PingAccess might create an information leakage vulnerability. The custom headers returned in the agent response, for example, might reveal internal details of applications or infrastructure that needs to be protected. Potentially worse, the values might reveal content from encrypted Web Access Management (WAM) tokens or reference access tokens. Authenticating PAAs to PingAccess is one means of mitigating the concern.

Authentication is optional. When it is required is at the discretion of PingAccess. Authentication of the agent to PingAccess is intended as a static deployment option, and no challenge response constructs are defined. Failed authentication – missing credentials when required or invalid credentials – is indicative of either a configuration problem or unauthorized access attempt. In such circumstances, PingAccess responds with an HTTP 403 and should include the vnd-pi-authz header in the response using a quoted string value with human readable information to help troubleshoot and allow for differentiation from an unauthorized end-user. An agent might send the 403 response or a 500 response to the client, depending on which is most appropriate.

vnd-pi-resource-cache

Indicates that for the given host the vnd-pi-resource-cache and vnd-pi-resource-cache-ttl headers, defined in the caching part of the next section, are to be returned in the agent response. Generally an agent will include this header when it needs to first establish its resource definition cache for a particular host, or when its current cache is stale or invalid. When an agent request includes the vnd-pi-resource-cache header, the agent response should include the vnd-pi-resource-cache and vnd-pi-resource-cache-ttl headers. An agent must be prepared to handle an agent response that omits those headers. The literal value requested can be used by the agent to request the resource cache data.

vnd-pi-resource-cache: requested
X-Forwarded-For

The X-Forwarded-For header contains the originating IP address of a client making a request. If no X-Forwarded-For header is present in the client request, it is added to the agent request with a value indicating the IP address of the client making the connection. If an X-Forwarded-For header is present in the client request, the IP address of the client is added to the end of the delimited list of IP addresses this header contains when sent in the agent request.

Host and X-Forwarded-Host

The agent sets the Host header in the agent request as it appeared in the client request, unless it is unable to easily manipulate the Host header. In the event that it could not modify the Host header, the X-Forwarded-Host header contains the original host requested by the client. If X-Forwarded-Host is already present in the client request, it is sent along unchanged in the agent request.

X-Forwarded-Proto

If X-Forwarded-Proto is present in the client request, it is sent along unchanged in the agent request. Otherwise, if the scheme used in the client request is different than the agent request (https vs. http), set the X-Forwarded-Proto header in the agent request to the scheme used in the client request. This header can be omitted if the client request and the agent request use the same scheme.

PingAccess determines the requested resource and constructs self-referential URIs using the contents of the request, including the headers listed above. The scheme is determined from the client’s connection and the X-Forwarded-Proto header, with the latter taking precedence when present. The host and port are determined from the Host and X-Forwarded-Host headers, with the latter taking precedence when present.

Policy decision request

The following example demonstrates a policy decision request for an unauthenticated user.

GET /application/headers HTTP/1.1
Host: http://example.com/
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Cookie: nonce=6424266c-ca9b-4e1f-9fde-d1860bfa2582
vnd-pi-v: 1.0
X-Forwarded-For: 172.30.3.248
vnd-pi-resource-cache: requested
X-Forwarded-Proto: http
vnd-pi-authz: Bearer Agent:htZ2W39EfAPLQd8w9cRT6y

Agent request without POST body

The following example demonstrates an agent request, in this case, the OpenID Connect (OIDC) callback in a web session POST login type. For brevity, the POST body isn't included.

POST /pa/oidc/cb HTTP/1.1
Host: http://example.com/
Connection: keep-alive
Content-Length: 0
Cache-Control: max-age=0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Origin: https://rhel-test.englab.corp.pingidentity.com:9031 
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip,deflate
Accept-Language: en-US,en;q=0.8
Cookie: nonce=b000c6a2-4a03-4bde-be29-956456cd1d2a vnd-pi-v: 1.0
X-Forwarded-For: 172.30.3.248
vnd-pi-resource-cache: requested
X-Forwarded-Proto: http
vnd-pi-authz:Bearer Agent:htZ2W39EfAPLQd8w9cRT6y

Agent request with POST body

The following example demonstrates a policy decision request with the POST body included.

Note:

The vnd-pi-expect: !477 header disallows the HTTP 477 agent response to request the message-body because it is already included.

POST /pa/oidc/cb HTTP/1.1
Host: http://example.com/
Connection: keep-alive
Content-Length: 1557
Cache-Control: max-age=0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Origin: https://rhel-test.englab.corp.pingidentity.com:9031
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip,deflate
Accept-Language: en-US,en;q=0.8
Cookie: nonce=b000c6a2-4a03-4bde-be29-956456cd1d2a
vnd-pi-v: 1.0
X-Forwarded-For: 172.30.3.248
vnd-pi-resource-cache: requested
X-Forwarded-Proto: http
vnd-pi-expect: !477
vnd-pi-authz: Bearer Agent:htZ2W39EfAPLQd8w9cRT6y 

Authenticated user request

The following example request demonstrates an authenticated user trying to access a resource:

GET /application/headers HTTP/1.1
Host: http://example.com/
Connection: keep-alive
Cache-Control: max-age=0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Cookie: PA.post=eyJraWQiOiJhcCIsImFsZyI6IkVTMjU2In0.eyJ6b25laW5mbyI6IkFtZXJpY2FcL05ld19Zb3JrIiwic3ViIjoiam9lIiwicGhvbmVfbnVtYmVyIjoiKzEgKDQyNSkgNTU1LTEyMTIiLCJlbWFpbF92ZXJpZmllZCI6InRydWUiLCJsb2NhbGUiOiJlbl9VUyIsInByZWZlcnJlZF91c2VybmFtZSI6Im1nc2FtcGxlIiwiZ2l2ZW5fbmFtZSI6Ik1lcmlkaXRoIiwidXBkYXRlZF90aW1lIjoiMjAxMS0wMS0wM1QyMzo1ODo0MiswMDAwIiwiaWF0IjoxNDEwOTk1NDM2LCJuYW1lIjoiTWVyaWRpdGggR29vZCBTYW1wbGUiLCJiaXJ0aGRhdGUiOiIxOTc3LTEyLTMxIiwiZmFtaWx5X25hbWUiOiJTYW1wbGUiLCJnZW5kZXIiOiJmZW1hbGUiLCJwcm9maWxlIjoiaHR0cHM6XC9cL3d3dy5waW5naWRlbnRpdHkuY29tXC9wcm9kdWN0c1wvcGluZ2ZlZGVyYXRlXC8iLCJ3ZWJzaXRlIjoiaHR0cHM6XC9cL3d3dy5waW5naWRlbnRpdHkuY29tXC8iLCJuaWNrbmFtZSI6Ik1lcmkiLCJtaWRkbGVfbmFtZSI6Ikdvb2QiLCJpc3MiOiJQaW5nQWNjZXNzIiwicGljdHVyZSI6Imh0dHBzOlwvXC93d3cucGluZ2lkZW50aXR5LmNvbVwvaW1hZ2VzXC9waW5nLWxvZ28ucG5nIiwiZXhwIjoxNDEwOTk5MDM2LCJwaS5zcmkiOiIyRUpVREtlTk5HZlNEdzdITWkzeEYzYlBSMlUiLCJlbWFpbCI6ImF1c2VyQGV4YW1wbGUuY29tIiwiYWRkcmVzcyI6eyJyZWdpb24iOiJNRSIsImZvcm1hdHRlZCI6IjEyMyBNYWluIFN0cmVldCwgU21hbGx2aWxsZSwgTUUgIFVTQSAxMTIyMyIsInBvc3RhbF9jb2RlIjoiMTEyMjMiLCJsb2NhbGl0eSI6IlNtYWxsdmlsbGUiLCJzdHJlZXRfYWRkcmVzcyI6IjEyMyBNYWluIFN0cmVldCIsImNvdW50cnkiOiJVU0EifSwiYXVkIjoicG9zdCIsImp0aSI6IjY2NjVkYzllLTUxMWMtNDE0Ni05YWFhLTI0ODUzNTA5NTE4MSIsImdyb3VwIjoic2FsZXMifQ.VRsuSs0LBnlHoJ2k-j0BDdLoGeVdqWD35n9ZxFhphEHFe7tfQ6onKAjRdXLR5rtwPBkJHkLaTLD8Yqcsf0izVw
vnd-pi-v: 1.0
X-Forwarded-For: 172.30.3.248
vnd-pi-resource-cache: requested
X-Forwarded-Proto: http
vnd-pi-authz: Bearer Agent:htZ2W39EfAPLQd8w9cRT6y