PingGateway 2024.9

Reference

This guide describes configuration options for PingGateway. It is for PingGateway designers, developers, and administrators.

For API specifications, refer to the appropriate Javadoc.

The examples in this guide use some of the following third-party tools:

Reserved routes

By default, PingGateway reserves all paths starting with /openig for administrative use, and only local client applications can access resources exposed under /openig.

PingGateway uses an ApiProtectionFilter to protect reserved routes. By default, the ApiProtectionFilter allows access to reserved routes only from the loopback address. To override this behavior, declare a custom ApiProtectionFilter in the top-level heap. For an example, refer to the CORS filter described in Set up the UMA example.

For information about how to change the base for administrative routes, refer to Change the base location.

Reserved field names

PingGateway reserves all configuration field names that contain only alphanumeric characters.

If you must define your own field names, for example, in custom decorators, use names with dots, ., or dashes, -. Examples include my-decorator and com.example.myDecorator.

Field value conventions

PingGateway configuration uses JSON notation.

This reference uses the following terms when referring to values of configuration object fields:

array

JSON array.

boolean

Either true or false.

certificate

java.security.cert.Certificate instance.

configuration token

Configuration tokens introduce variables into the server configuration. They can take values from Java system properties, environment variables, JSON and Java properties files held in specified directories, and from properties configured in routes. For more information, refer to JSON Evaluation.

duration

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and negative durations are not supported. The following units can be used in durations:

  • indefinite, infinity, undefined, unlimited: unlimited duration

  • zero, disabled: zero-length duration

  • days, day, d: days

  • hours, hour, h: hours

  • minutes, minute, min, m: minutes

  • seconds, second, sec, s: seconds

  • milliseconds, millisecond, millisec, millis, milli, ms: milliseconds

  • microseconds, microsecond, microsec, micros, micro, us, µs: microseconds

  • nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

enumeration

A collections of constants.

expression

See Expressions.

configuration expression

Expression evaluated at configuration time, when routes are loaded. See Configuration Expressions.

runtime expression

Expression evaluated at runtime, for each request and response. See Runtime Expressions.

instant

An instantaneous point on the timeline, as a Java type. For more information, see Class Instant.

JsonValue

An object (JsonObject), an array (JsonArray), a number (JsonNumber), a string (JsonString), true (JsonValue.TRUE), false (JsonValue.FALSE), or null (JsonValue.NULL).

lvalue-expression

Expression yielding an object whose value is to be set.

Properties whose format is lvalue-expression cannot consume streamed content. They must be written with $ instead of #.

map

An object that maps keys to values. Keys must be unique, and can map to at most one value.

number

JSON number.

object

JSON object where the content depends on the object’s type.

pattern

A regular expression according to the rules for the Java Pattern class.

pattern-template

Template for referencing capturing groups in a pattern by using $n, where n is the index number of the capturing group starting from zero.

For example, if the pattern is \w+\s*=\s*(\w)+, the pattern-template is $1, and the text to match is key = value, the pattern-template yields value.

reference

References an object in the following ways:

  • An inline configuration object, where the name is optional.

  • A configuration expression that is a string or contains variable elements that evaluate to a string, where the string is the name of an object declared in the heap.

    For example, the following temporaryStorage object takes the value of the system property storage.ref, which must a be string equivalent to the name of an object defined in the heap:

    {
  "temporaryStorage": "${system['storage.ref']}"
}
secret-id

String that references a secret managed by the Commons Secrets API, as described in Secrets.

The secret ID must conform to the following regex pattern: Pattern.compile("(\\.[a-zA-Z0-9])*");

string

JSON string.

url

String representation for a resource available via the Internet. For more information, refer to Uniform Resource Locators (URL).