PAAP agent request

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.

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.

These header examples are considered semantically equivalent.

The syntax for the vnd-pi-agent value conforms to a dictionary in this specification, https://datatracker.ietf.org/doc/rfc8941/, where member-values are constrained to be an sh-string item.

For more information, see Agent inventory logging.

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.

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

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:

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.

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.

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.

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.

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.

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

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.

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

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