Examples

In the following example, the Simple Groovy rule inserts a custom HTTP header, and the script ends with a call to the Matcher pass(). 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 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 used is the hasScope() Matcher that confirms if the OAuth access token has the WRITE scope. If this is true, 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 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.

Matcher Description

pass()

Signals that the rule has passed.

fail()

Signals that the rule has failed.

inIpRange(String cidr)

Validates the source IP address of the request against the cidrstring 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 also potentially controlled by the override options on the gent 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 also 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)

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)

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.

Note:

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.

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)

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

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