Pushed authorization requests endpoint

The PingFederate authorization server (AS) can provide a pushed authorization requests (PAR) endpoint /as/par.oauth2. OAuth 2.0 clients can use the PAR endpoint to securely initiate authorization flows.

When the PAR endpoint is enabled, a client can push an authorization request payload to the AS with a direct back-channel request. This is a more secure method of sending sensitive data, such as personally identifiable information, than sending it with a browser on the front channel. The payload contains parameters that are application/x-www-form-urlencoded formatted. The PAR endpoint can accept all parameters that usually comprise an authorization request and any additional parameters needed for client authentication. It also can accept signed requests.

The PAR endpoint only accepts the HTTP POST method.

After the AS validates the request and saves the payload, it returns the request_uri parameter to serve as a reference to the payload. The response also indicates the lifetime of the request URI. The default lifetime is 60 seconds.

Sample request for a request_uri to the PAR endpoint

  POST /as/par.oauth2 HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

  response_type=code
  &client_id=s6BhdRkqt3
  &state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Sample response with a request_uri from the PAR endpoint

  HTTP/1.1 201 Created
  Cache-Control: no-cache, no-store
  Content-Type: application/json

  {
    "expires_in": 60,
    "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2"
  }

Subsequently, the client uses the front channel to request an authorization code or token, sending the request_uri parameter to the AS authorization endpoint. The AS uses the request URI to look up the request payload and continue the authorization flow as usual. The AS accepts a particular request URI only once.

Sample request for an authorization code or token to the authorization endpoint

  GET /as/authorization.oauth2?client_id=s6BhdRkqt3
    &request_uri=urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1
  Host: as.example.com

To let OAuth clients use the PAR endpoint, you must enable PAR on the AS. Additionally, you can configure individual clients so that they must use the PAR endpoint to initiate authorization flows. For more information about PAR settings, see Configuring authorization server settings and Configuring OAuth clients.

When PAR is enabled on the AS, the well-known endpoint /.well-known/openid-configuration includes these PAR parameters in responses:

pushed_authorization_request_endpoint contains the PAR endpoint
require_pushed_authorization_requests indicates whether the AS requires clients to use PAR

PingFederate can decrypt encrypted request objects, which are described in the .net/specs/openid-connect-core-1_0.html//[OpenID Connect 1.0 specification]. Request objects with asymmetric encryption must be encrypted using the public keys that PingFederate exposes at /pf/JWKS. Request objects with symmetric encryption need a key derived from the client’s configured client secret and the client secret must be stored in a reversible format with, for example, symmetric encrypted ID tokens or hash-based message authentication code (HMAC) ID tokens. You can configure PingFederate to accept only request objects that are encrypted by enabling the front-channel-encryption-required setting in jwt-request-object-options.xml.

For more information about the PAR protocol, see OAuth 2.0 Pushed Authorization Requests on the IETF website.

PingFederate Server

Pushed authorization requests endpoint