PingAccess

Groovy Scripts

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.

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.

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