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 | ||||
|---|---|---|---|---|---|
|
Signals that the rule has passed. |
||||
|
Signals that the rule has failed. |
||||
|
Validates the source Internet Protocol (IP) address of the request against the For agents, this value is potentially controlled by the override options on the agent settings. Example: |
||||
|
Validates the source IP address against the 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 Valid values for the Example: |
||||
|
Validates the source IP address in the first of the specified Example: |
||||
|
Validates that the value returned by the Example: |
||||
|
Validates that the current server time is between the Example: |
||||
|
Validates that the current server time is between the specified 24-hour formatted time range between the Example: |
||||
|
Validates that the HTTP header field value is equal to the Example: |
||||
|
Validates that all of the HTTP header fields map to the associated value. The first The The second string in the If multiple pairs of strings are present in the Example: |
||||
|
Validates that all of the HTTP form fields maps to the associated value. The first The
The second string in the If multiple pairs of strings are present in the Example: |
||||
|
Validates that the HTTP header field value is not equal to the Example: |
||||
|
Validates that the HTTP body contains the 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 Example: |
||
|
Validates that the OAuth access token contains the list of scopes. Example: |
||
|
Checks for an attribute value within the current OAuth2 policy context. Example: |