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.
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 |
|---|---|
|
|
Signals that the rule has passed. |
|
|
Signals that the rule has failed. |
|
|
Validates the source 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:
|
|
|
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:
|
|
|
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:
|
|
|
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:
|
|
|
Validates that the value returned by the xPathString parameter is equal to the xPathValue parameter. Example:
|
|
|
Validates that the current server time is between the startTime and endTime parameters. Example:
|
|
|
Validates that the current server time is between the specified 24-hour formatted time range between the startTime and endTime parameters. Example:
|
|
|
Validates that the HTTP header field value is equal to the value parameter. Example:
|
|
Note:
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:
|
|
Note:
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. 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:
|
|
|
Validates that the HTTP header field value is not equal to the value parameter. Example:
|
|
|
Validates that the HTTP body contains the value parameter. Example:
|
|
|
Validates that the HTTP body does not contain the value parameter. Example:
|
|
|
Validates that the PingAccess token contains the attribute name and value. Example:
|
|
|
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 |
|---|---|
|
|
Validates that the OAuth access token contains the scope parameter. Example:
|
|
|
Validates that the OAuth access token contains the list of scopes. Example:
|
|
Note:
This matcher is case insensitive and cannot be made case sensitive. |
Checks for an attribute value within the current OAuth2 policy context. Example:
|