PingGateway

PingAuthorizeFilter

Use the PingAuthorizeFilter with the PingOne Authorize or PingAuthorize Sideband API.

The API moderates requests and responses as follows:

  • Allows requests, optionally instructing PingGateway to edit the requests.

  • Rejects requests, instructing PingGateway on how to respond to the client, such as with an HTTP 403 and a custom message.

  • Instructs PingGateway to update responses from the backend; for example, instructions to remove content from the response body or to add or remove headers.

The filter sends the following elements to the Sideband API for the request:

  • Client IP address

  • Client port

  • HTTP method used

  • URL targeted

  • HTTP version used

  • HTTP headers

  • HTTP content (if the content matches any of the optional includeBodyContentTypes)

The filter sends the following elements to the Sideband API for the response:

  • Original URL queried

  • Original method called

  • HTTP status code

  • HTTP status message

  • HTTP version

  • HTTP headers

  • HTTP content (if the content matches any of the optional includeBodyContentTypes)

Usage

{
  "name": string,
  "type": "PingAuthorizeFilter",
    "config": {
      "gatewayServiceUri": configuration expression<url>,
      "secretsProvider": SecretsProvider reference,
      "gatewayCredentialSecretId": configuration expression<secret-id>,
      "includeBodyContentTypes": [ configuration expression<string> ] || configuration expression<string>,
      "sidebandHandler": Handler reference,
      "accessToken": runtime expression<string>,
      "sharedSecretHeaderName": string
  }
}

Configuration

"gatewayServiceUri": configuration expression<url>, required

The Sideband API URL.

For PingOne Authorize, go to your environment and find the value in Authorization > API gateways > Service URL.

For PingAuthorize, use the PingAuthorize <host>:<port>. Append the base path if it differs from /.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for the credential to access the Sideband API.

"gatewayCredentialSecretId": configuration expression<secret-id>, required

The secret ID of the Sideband API credential.

The secret ID must point to a GenericSecret in the secretsProvider.

For PingOne Authorize, go to your environment, select Authorization > API gateways, and select your gateway to add the credential.

For PingAuthorize, use the same shared secret when setting up the PingAuthorize Sideband API.

"includeBodyContentTypes": array of configuration expression<string>, optional

If any of these content types are present, include the body of the request or response in the request to the Sideband API.

Including the body in every request and response can impact the HTTP exchange latency.

Default: Don’t send the request body to the Sideband API.

"sidebandHandler": Handler reference, optional

An HTTP client handler to use to contact the Sideband API.

The handler sends requests and responses to the Sideband API. It then processes authorization decisions to accept, reject, or rewrite requests and responses.

Default: ForgeRockClientHandler

"accessToken": runtime expression<string>, optional

The access token to send to the Sideband API.

Default: none, PingGateway takes the access token from the request’s Authorization header.

"sharedSecretHeaderName": string, optional

The header name set in the Sideband API to pass the shared secret.

Set this value when using a custom shared secret header to authenticate to the PingAuthorize Sideband API.

When using the filter with PingOne Authorize, use the default value.

Default: CLIENT-TOKEN

More information

org.forgerock.openig.ping.PingAuthorizeFilter