--- title: Matcher usage reference description: 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. component: pingaccess version: 9.0 page_id: pingaccess:reference_guides:pa_matcher_usage_ref canonical_url: https://docs.pingidentity.com/pingaccess/9.0/reference_guides/pa_matcher_usage_ref.html revdate: July 26, 2023 section_ids: pingaccess-matchers: PingAccess matchers --- # 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](http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/CoreMatchers.html). * For more information on Hamcrest, see the [Hamcrest Tutorial](http://code.google.com/p/hamcrest/wiki/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](pa_groovy_scripts.html). * 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. | > **Collapse: Examples** > > In the following example, the Groovy script rule inserts a custom HTTP header *(tooltip: \
> \

A section of an HTTP request or response that conveys additional information relevant to the client or server in the transaction.\

> \
)* 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 *(tooltip: \
> \

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

> \
)* 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](../pingaccess_user_interface_reference_guide/pa_adding_groovy_script_rules.html) and the [OAuth Groovy script rule](../pingaccess_user_interface_reference_guide/pa_adding_oauth_groovy_script_rules.html). > **Collapse: 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) *(tooltip: \
\

The method by which data is sent across the internet from the source host to the destination host.\

\
)* address of the request against the `cidr` string parameter in CIDR notation. When source IP headers defined in the [HTTP Requests](../pingaccess_user_interface_reference_guide/pa_http_requests.html) 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](../pingaccess_user_interface_reference_guide/pa_http_requests.html) 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 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 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](../pingaccess_user_interface_reference_guide/pa_adding_oauth_groovy_script_rules.html). > **Collapse: 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")` |