Groovy scripts provide advanced rule logic that extends PingAccess rule development beyond the capabilities of the packaged rules.
Groovy scripts have access to important PingAccess runtime objects, such as the Exchange and PolicyContext objects, which the scripts can interrogate and modify. Groovy script rules are invoked during the request processing phase of an exchange, allowing the script to modify the request before it is sent to the server. Groovy script rules are also invoked during the response, allowing the script to modify the response before it is returned to the client. See Groovy for more information about Groovy.
Through Groovy scripts, PingAccess administrators can perform sensitive operations that could affect system behavior and security.
Groovy scripts 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.
The following are Hamcrest method examples for constructing access control policies
with the web session attribute rule using evaluations such as an
group membership evaluation.
- Matches if the examined object matches all of the specified matchers. In this example, the user needs to be in both the sales and managers groups for this rule to pass.
- Matches any of the specified matchers. In this example, the rule passes if the user is in any of the specified groups.
anyOf(containsWebSessionAttribute("group","sales"), containsWebSessionAttribute("group","managers"), containsWebSessionAttribute("group","execs"))
- Inverts the logic of a matcher to not match. In this example, the rule fails if the user is in both the sales and the managers groups.
not(allOf(containsWebSessionAttribute("group", "sales"), containsWebSessionAttribute("group", "managers")))
See Matchers for more information.
The following objects are available in Groovy. For more information on an object, click the link.
- Exchange Object
- Contains the HTTP request and the HTTP response for the transaction processed by PingAccess.
- PolicyContext Object
- Contains a map of objects needed to perform policy decisions. The contents of the map vary based on the context of the current user flow.
- Request Object
- Contains all information related to the HTTP request made to an application.
- Response Object
- Contains all information related to the site HTTP response.
- Method Object
- Contains the HTTP method name from the request made to an application.
- Header Object
- Contains the HTTP header information from the request made to an application or the HTTP header from a Site response.
- Body Object
- Contains the HTTP body from the application request or the HTTP body from the site response.
- OAuthToken Object
- Contains the OAuth access token and related identity attributes.
- Logger Object
- Configure and view the state of logging.
- MediaType Object
- Contains information related to the media type.
Groovy script rules are evaluated when saved to ensure that they are syntactically valid. If a Groovy script rule fails to save, hover over the information icon to view additional information about the reason for the failure.
If a rule fails when it is run, information about the failure is added to the <PA_HOME>/log/pingaccess.log file.
Some error messages about Groovy rule failures are only logged if
DEBUG level output is enabled for the