PingGateway 2024.9

StaticRequestFilter

Creates a new request, replacing any existing request. The request can include an entity specified in the entity parameter. Alternatively, the request can include a form, specified in the form parameter, which is included in an entity encoded in application/x-www-form-urlencoded format if request method is POST, or otherwise as (additional) query parameters in the URI. The form and entity parameters cannot be used together when the method is set to POST.

Usage

{
  "name": string,
  "type": "StaticRequestFilter",
  "config": {
    "method": configuration expression<string>,
    "uri": runtime expression<url>,
    "version": configuration expression<string>,
    "headers": {
      configuration expression<string>: [ runtime expression<string>, ... ], ...
    },
    "form": {
      configuration expression<string>: [ runtime expression<string>, ... ], ...
    },
    "entity": runtime expression<string>
  }
}

Properties

"method": configuration expression<string>, required

The HTTP method to be performed on the resource; for example, GET.

"uri": runtime expression<url>, required

The fully-qualified URI of the resource being accessed; for example, http://www.example.com/resource.txt.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a string but a mutable URI.

"version": configuration expression<string>, optional

Protocol version.

Default: "HTTP/1.1"

"headers": map, optional

One or more headers to set for a request, with the format name: [ value, …​ ], where:

  • name is a configuration expression<string> that resolve to a header name. If multiple expressions resolve to the same final string, name has multiple values.

  • value is one or more runtime expression<strings> that resolve to header values.

In the following example, the header name is the value of the system variable defined in cookieHeaderName. The header value is stored in contexts.ssoToken.value:

"headers": {
  "${application['header1Name']}": [
    "${application['header1Value'}"
  ]
}

Default: Empty

"form": map, optional

A form to include in the request and/or application/x-www-form-urlencoded entity, as name-value pairs, where:

  • name is a configuration expression<string> that resolves to a form parameter name.

  • value is one or more runtime expression<strings> that resolve to form parameter values.

When a Request method is POST, form is mutually exclusive with entity.

Examples:

  • In the following example, the field parameter names and values are hardcoded in the form:

    "form": {
  "username": [
    "demo"
  ],
  "password": [
    "password"
  ]
}

  • In the following example, the values take the first value of username and password provided in the session:

    "form": {
  "username": [
    "${session.username[0]}"
  ],
  "password": [
    "${session.password[0]}"
  ]
}

  • In the following example, the name of the first field parameter takes the value of the expression ${application['formName']} when it is evaluated at startup. The values take the first value of username and password provided in the session:

    "form": {
  "${application['formName']}": [
    "${session.username[0]}"
  ],
  "${application['formPassword']}": [
    "${session.password[0]}"
  ]
}

    Default: Empty

"entity": runtime expression<string>, optional

The message entity body to include in a request.

When a Request method is POST, entity is mutually exclusive with form.

Methods are provided for accessing the entity as byte, string, or JSON content. For information, refer to Entity.

Attackers during reconnaissance can use messages to identify information about a deployment. For security, limit the amount of information in messages, and avoid using words that help identify PingGateway.

Default: Empty

Example

In the following example, PingGateway replaces the browser’s original HTTP GET request with an HTTP POST login request containing credentials to authenticate to the sample application. For information about how to set up and test this example, refer to the Quick install.

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "StaticRequestFilter",
          "config": {
            "method": "POST",
            "uri": "http://app.example.com:8081/login",
            "form": {
              "username": [
                "demo"
              ],
              "password": [
                "Ch4ng31t"
              ]
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  },
  "condition": "${find(request.uri.path, '^/static')}"
}

More information

org.forgerock.openig.filter.StaticRequestFilter