Groovy script rules and OAuth Groovy script rules must end execution with a Matcher instance. This could either be a Matcher from the list of PingAccess Matchers or from the Hamcrest library. For more information on Hamcrest, see the Hamcrest Tutorial.
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 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(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(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(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:
|
requestXPathMatches(String xPathString, String
xPathValue) |
Validates that the
value returned by the xPathString parameter is
equal to the xPathValue parameter.
Example:
|
inTimeRange(String startTime, String
endTime) |
Validates that the
current server time is between the startTime
and endTime parameters. Example:
|
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:
|
requestHeaderContains(String field, String
value) |
Validates that the HTTP
header field value is equal to the value
parameter. Example:
|
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:
|
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:
|
requestHeaderDoesntContain(String field, String
value) |
Validates that the HTTP
header field value is not equal to the value
parameter. Example:
|
requestBodyContains(String value) |
Validates that the HTTP
body contains the value parameter.
Example:
|
requestBodyDoesntContain(String value) |
Validates that the HTTP
body does not contain the value parameter. Example:
|
containsWebSessionAttribute(String attributeName,
String attributeValue) |
Validates that the
PingAccess token contains the attribute name and value.
Example:
|
containsACRValues(String value) |
Validates that the PingAccess token contains a matching ACR value. |
The following table lists the Matchers available to only the OAuth Groovy rule.
| Matcher | Description |
|---|---|
hasScope(String
scope) |
Validates that the
OAuth access token contains the scope
parameter. Example:
|
hasScopes(String... scopes) |
Validates that the
OAuth access token contains the list of scopes. Example:
|
hasAttribute(String attributeName, String
attributeValue) |
Checks for an attribute
value within the current OAuth2 policy context. Example:
|