PingAccess

Matcher usage reference

Groovy script rules and OAuth Groovy script rules must end execution with a matcher instance. Matchers provide a framework for establishing declarative rule matching objects.

You can use a matcher from the list of PingAccess matchers or from the Hamcrest library.

  • For more information on Hamcrest, see the Hamcrest Tutorial.

  • For more information on creating and troubleshooting Groovy scripts, and examples of how you might use Hamcrest matchers instead of PingAccess matchers, see Groovy Scripts.

  • For more information on PingAccess matchers, review the following examples and tables.

Matcher string evaluation is case sensitive unless otherwise specified. In the PingAccess matchers table, case insensitivity is called out in a matcher’s description when applicable.

Examples

In the following example, the Groovy script rule inserts a custom HTTP header and the script ends with a call to the pass() matcher. The pass() matcher signals that the rule has passed.

test = "let's get Groovy!"
exc?.response?.header?.add("X-Groovy", "$test")
pass()

In the following example, the OAuth Groovy script rule checks the HTTP method and confirms the OAuth scope, and a matcher is evaluated at the end of each line of execution. The first matcher is the hasScope() matcher, which confirms whether the OAuth access token has the WRITE scope. If it does, the rule passes.

//Get the HTTP method name
def methodName = exc?.request?.method?.methodName()
if (methodName == "POST") {
    hasScope("WRITE")
} else {
    fail()
}

The fail() matcher combination is only evaluated when the methodName does not equal POST. This matcher combination evaluates to false.

PingAccess matchers

The following table lists the PingAccess matchers available for the Groovy script rule and the OAuth Groovy script rule.

Groovy and OAuth Groovy script rule matchers
Matcher Description

pass()

Signals that the rule has passed.

fail()

Signals that the rule has failed.

inIpRange(String cidr)

Validates the source Internet Protocol (IP) address of the request against the cidr string parameter in CIDR notation. When source IP headers defined in the HTTP Requests page are found, the source IP address determined from those headers is used as the source address.

For agents, this value is potentially controlled by the override options on the agent settings.

Example: inIpRange("127.0.0.1/8")

inIpRange(java.net.InetAddress ipAddress, int prefixSize)

Validates the source IP address against the ipAddress and the prefixSize parameters specified individually. When source IP headers defined in the HTTP Requests page are found, the source IP address determined from those headers is used as the source address.

For agents, this value is potentially controlled by the override options on the agent settings.

Example: inIpRange(InetAddress.getByName("127.0.0.1"),8)is equivalent to  inIpRange("127.0.0.1/8")

inIpRange(String cidr, String listValueLocation, boolean fallBackToLastHopIp, String…​ headerNames)

Validates the source IP address in the first of the specified headerNames using the cidr value. Can be specified as part of a Groovy script as a means of overriding the configuration stored in PingAccess for a specific Groovy script rule.

Valid values for the listValueLocation parameter are FIRST, LAST, and ANY. This parameter controls where, in a multivalued list of source IP addresses, the last source should be taken from. If ANY is used, if any of the source IP addresses in a matching header match the CIDR value, the matcher evaluates to true.

Example: inIpRange("127.0.0.1/8", "LAST", true, "X-Forwarded-For", "Custom-Source-IP")

inIpRange(java.net.InetAddress address, int prefixSize, String listValueLocation, boolean fallBackToLastHopIp, String…​ headerName)

Validates the source IP address in the first of the specified headerNames using the address and prefixSize values. In all other respects, this matcher behaves the same as the version that uses a cidr value for comparison.

Example: inIpRange(InetAddress.getByName("127.0.0.1"), 8, "LAST", true, "X-Forwarded-For", "Custom-Source-IP")

requestXPathMatches(String xPathString, String xPathValue)

Validates that the value returned by the xPathString parameter is equal to the xPathValue parameter.

Example: requestXPathMatches("//header[@name='Host']/text()","localhost:3000")

inTimeRange(String startTime, String endTime)

Validates that the current server time is between the startTime and endTime parameters.

Example: inTimeRange("9:00 am","5:00 pm")

inTimeRange24(String startTime, String endTime)

Validates that the current server time is between the specified 24-hour formatted time range between the startTime and endTime parameters.

Example: inTimeRange24("09:00","17:00")

requestHeaderContains(String field, String value)

Validates that the HTTP header field value is equal to the value parameter.

Example: requestHeaderContains("User-Agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36")

requestHeaderContains(Map<String, String> fieldValuesMap, boolean caseSensitive)

This matcher can be case sensitive or case insensitive.

Validates that all of the HTTP header fields map to the associated value. The first fieldValuesMap string contains the HTTP header name, and the second string contains the value to compare the incoming request header value with.

The caseSensitive parameter determines whether a case-sensitive comparison is performed on the value.

The second string in the fieldValuesMap supports Java regular expressions.

If multiple pairs of strings are present in the fieldValuesMap parameter, then all conditions must be met in order for the matcher to pass.

Example: requestHeaderContains(['User-Agent':'Mozilla/5.0', 'Cookie':'JSESSIONID'], false)

requestPostFormContains(Map<String, String> fieldValuesMap, boolean caseSensitive)

This matcher can be case sensitive or case insensitive.

Validates that all of the HTTP form fields maps to the associated value. The first fieldValuesMap string contains the form header name, and the second string contains the value to compare the incoming request header value with.

The caseSensitive parameter determines whether a case-sensitive comparison is performed on the value.

This matcher determines whether to use fields passed in the URL or forms with a content-type header of application/x-www-form-urlencoded.

The second string in the fieldValuesMap supports Java regular expressions.

If multiple pairs of strings are present in the fieldValuesMap parameter, then all conditions must be met in order for the matcher to pass.

Example: requestPostFormContains(['email':'@example.com', 'phonenumber':'720'], false)

requestHeaderDoesntContain(String field, String value)

Validates that the HTTP header field value is not equal to the value parameter.

Example: requestHeaderDoesntContain("User-Agent", "InternetExplorer")

requestBodyContains(String value)

Validates that the HTTP body contains the value parameter.

Example: requestBodyContains("production")

requestBodyDoesntContain(String value)

Validates that the HTTP body does not contain the value parameter.

Example: requestBodyDoesntContain("test")

containsWebSessionAttribute(String attributeName, String attributeValue)

Validates that the PingAccess token contains the attribute name and value.

Example: containsWebSessionAttribute("sub", "sarah")

containsACRValues(String value)

Validates that the PingAccess token contains a matching ACR value.

The following table lists the PingAccess matchers available to only the OAuth Groovy script rule.

OAuth Groovy script rule matchers
Matcher Description

hasScope(String scope)

Validates that the OAuth access token contains the scope parameter.

Example: hasScope("access")

hasScopes(String…​ scopes)

Validates that the OAuth access token contains the list of scopes.

Example: hasScopes("access","portfolio")

hasAttribute(String attributeName, String attributeValue)

This matcher is case insensitive and cannot be made case sensitive.

Checks for an attribute value within the current OAuth2 policy context.

Example: hasAttribute("account","joe")