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.

Note:

Through Groovy scripts, PingAccess administrators can perform sensitive operations that could affect system behavior and security.

Matchers

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 OR group membership evaluation.

allOf
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.
allOf(containsWebSessionAttribute("group","sales"), containsWebSessionAttribute("group","managers"))
anyOf
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"))
not
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.

Objects

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.

Debugging/troubleshooting

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.

Info:

Some error messages about Groovy rule failures are only logged if DEBUG level output is enabled for the com.pingidentity logger.