--- title: Scripts description: Use scripts with the following object types: component: pinggateway version: 7.2 page_id: pinggateway:reference:Scripts canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/Scripts.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-02T16:30:54Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/Scripts.html section_ids: Scripts-usage: Usage Scripts-properties: Properties Scripts-availableob: Available objects Scripts-impclass: Imported classes Scripts-moreinfo: More information --- # Scripts Use scripts with the following object types: * [ScriptableFilter](Filters.html#ScriptableFilter), to customize flow of requests and responses * [ScriptableHandler](Handlers.html#ScriptableHandler), to customize creation of responses * [ScriptableThrottlingPolicy](ThrottlingPolicies.html#ScriptableThrottlingPolicy), to customize throttling rates * [ScriptableAccessTokenResolver](AccessTokenResolvers.html#ScriptableAccessTokenResolver) to customize resolution and validation of OAuth 2.0 access tokens * `ScriptableResourceAccess` in [OAuth2ResourceServerFilter](Filters.html#OAuth2ResourceServerFilter), to customize the list of OAuth 2.0 scopes required in an OAuth 2.0 access token When a script is accessed, IG compiles and then caches the script. Unless the script is changed, IG continues to use the cached version. After updating a script that is used in a route, leave at least one second before processing a request. The Groovy interpreter needs time to detect and take the update into account. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you are writing scripts or Java extensions, never use a `Promise` blocking method, such as `get()`, `getOrThrow()`, or `getOrThrowUninterruptibly()`, to obtain the response.A promise represents the result of an asynchronous operation. Therefore, using a blocking method to wait for the result can cause deadlocks and/or race issues. | ## Usage ```json { "name": string, "type": scriptable object type, "config": { "type": string, "file": configuration expression, // Use either "file" "source": [ string, ... ], // or "source", but not both. "args": map, "clientHandler": Handler reference } } ``` ## Properties * `"type"`: *[string](preface.html#definition-string), required* The Internet media type (formerly MIME type) of the script, "application/x-groovy" for Groovy * `"file"`: *configuration expression<[string](preface.html#definition-string)>* Path to the file containing the script; mutually exclusive with `"source"`. Relative paths are with respect to to the base location for scripts. The base location depends on the configuration. The base location for Groovy scripts is on the classpath when the scripts are executed. If some Groovy scripts are not in the default package, but instead have their own package names, they belong in the directory corresponding to their package name. For example, a script in package `com.example.groovy` belongs under `openig-base/scripts/groovy/com/example/groovy/`. - `"source"`: *array of [strings](preface.html#definition-string)>, required if `file` is not used* The script as one or more strings; mutually exclusive with `file`. The following example shows the source of a script as an array of strings: ```json "source": [ "Response response = new Response(Status.OK)", "response.entity = 'foo'", "return response" ] ``` - `"args"`: *[map](preface.html#definition-map), optional* A name-value map of `configuration parameter:script parameters`, where: * `configuration parameter` is a string * `script parameters` is one or more configuration expressions that resolve to strings Examples: * The following example configures arguments as a map whose values can are scalars, arrays, and objects: ```json { "args": { "title": "Coffee time", "status": 418, "reason": [ "Not Acceptable", "I'm a teapot", "Acceptable" ], "names": { "1": "koffie", "2": "kafe", "3": "cafe", "4": "kafo" } } } ``` * A script can access the args parameters in the same way as other global objects. The following example sets the response status to `I'm a teapot`: ```groovy response.status = Status.valueOf(418, reason[1]) ``` For information about the 418 status code see [RFC 7168: 418 I'm a Teapot](https://www.rfc-editor.org/rfc/rfc7168#section-2.3.3). * The following example configures arguments as strings and numbers for a ScriptableThrottlingPolicy: ```json "args": { "status": "gold", "rate": 6, "duration": "10 seconds" } ``` The following lines set the throttling rate to 6 requests each 10 seconds when the response status is `gold`: ```groovy if (attributes.rate.status == status) { return new ThrottlingRate(rate, duration) } ``` * The following example configures arguments that reference a SampleFilter defined in the heap: ```json { "heap": [ { "name": "SampleFilter", "type": "SampleFilter", "config": { "name": "X-Greeting", "value": "Hello world" } } ] } ``` The following line uses an expression in the args parameter to pass SampleFilter to the script: ```json { "args": { "filter": "${heap['SampleFilter']}" } } ``` The script can then reference SampleFilter as `filter`. - `"clientHandler"`: *ClientHandler [reference](preface.html#definition-reference), optional* A [Handler](Handlers.html) for making outbound HTTP requests to third-party services. In a script, `clientHandler` is wrapped within the global object `http`. Default: The default ClientHandler. ## Available objects The following global objects are available to scripts: * Any parameters passed as args You can use the configuration to pass parameters to the script by specifying an args object. The args object is a map whose values can be scalars, arrays, and objects. The args object can reference objects defined in the heap by using expressions, for example, `"${heap['ObjectName']}"`. The values for script arguments can be defined as configuration expressions, and evaluated at configuration time. Script arguments cannot refer to `context` and `request`, but `context` and `request` variables can be accessed directly within scripts. Take care when naming keys in the args object. If you reuse the name of another global object, cause the script to fail and IG to return a response with HTTP status code 500 Internal Server Error. - All heap objects The heap object configuration, described in [Heap Objects](RequiredConfiguration.html#heap-objects). * `openig` An implicit object that provides access to the environment when expressions are evaluated. - `attributes` The [attributes](../_attachments/apidocs/org/forgerock/services/context/AttributesContext.html) object provides access to a context map of arbitrary attributes, which is a mechanism for transferring transient state between components when processing a single request. Use `session` for maintaining state between successive requests from the same logical client. * `builder` For ScriptableJwtValidatorCustomizer only. Used by the ScriptableJwtValidatorCustomizer and [JwtValidationFilter](Filters.html#JwtValidationFilter) to create constraints to test JWT claims and sub-claims. The purpose of the ScriptableJwtValidatorCustomizer is to enrich the `builder` object. For information about methods to enrich the `builder` instance, see [JwtValidator.Builder](../_attachments/apidocs/org/forgerock/openig/tools/jwt/validation/JwtValidator.Builder.html). - `constraints` The [constraints](../_attachments/apidocs/org/forgerock/openig/tools/jwt/validation/Constraints.html) object, all its static methods, `constant(String)`, and `claim(String)`. Use this object for JWT validation with the `customizer` property of [JwtValidationFilter](JwtValidationFilter.html). `claim(String)` must be followed by one of the following methods: `asString()`, `asInteger()`, `asLong()`, `asDouble()`, `asBoolean()`, `as(yourCustomJsonValueTransformer)` * `context` The processing [context](../_attachments/apidocs/org/forgerock/services/context/Context.html). This context is the leaf of a chain of contexts. It provides access to other Context types, such as SessionContext, AttributesContext, and ClientContext, through the `context.asContext(ContextClass.class)` method. - `contexts` a map\ object. For information, see [Contexts](RequestsResponsesContexts.html#Contexts). * `request` The HTTP [request](../_attachments/apidocs/org/forgerock/http/protocol/Request.html). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `request.form` method, used in scripts to read or set query and form parameters, is deprecated. Use the following replacement settings:* `Request.getQueryParams()` to read query parameters * `Entity.getForm()` to read form parameters * `Entity.setForm()` to set form parametersFor more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | * `globals` This object is a [Map](http://docs.groovy-lang.org/latest/html/groovy-jdk/java/util/Map.html) that holds variables that persist across successive invocations. - `http` An embedded client for making outbound HTTP requests, which is an [org.forgerock.http.Client](../_attachments/apidocs/org/forgerock/http/Client.html). If a `"clientHandler"` is set in the configuration, then that Handler is used. Otherwise, the default ClientHandler configuration is used. For details, see [Handlers](Handlers.html). * `ldap` (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The `LdapClient` class and the `ldap` script binding are deprecated. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | The [ldap](../_attachments/apidocs/org/forgerock/openig/ldap/LdapClient.html) object provides an embedded LDAP client. Use this client to perform outbound LDAP requests, such as LDAP authentication. - `logger` The [logger](https://www.slf4j.org/api/org/slf4j/Logger.html) object provides access to a unique SLF4J logger instance for scripts, where the logger instance is named with the script name. For information about logging for scripts, see [Logging In Scripts](../maintenance-guide/logging.html#logging-scripts). * `next` The object named `next` refers to the next element in the chain, which can be the following filter or the terminal handler. If the next object in the chain is a filter, IG wraps it in a handler. - `session` The [session](../_attachments/apidocs/org/forgerock/http/session/SessionContext.html) object provides access to the session context, which is a mechanism for maintaining state when processing a successive requests from the same logical client or end user. Use `attributes` for transferring transient state between components when processing a single request. ## Imported classes The following classes are imported automatically for Groovy scripts: * [org.forgerock.http.Client](../_attachments/apidocs/org/forgerock/http/Client.html) * [org.forgerock.http.Filter](../_attachments/apidocs/org/forgerock/http/Filter.html) * [org.forgerock.http.Handler](../_attachments/apidocs/org/forgerock/http/Handler.html) * [org.forgerock.http.protocol.Header](../_attachments/apidocs/org/forgerock/http/protocol/Header.html) * [org.forgerock.openig.http.filter.throttling.ThrottlingRate](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ThrottlingRate.html) * [org.forgerock.http.util.Uris](../_attachments/apidocs/org/forgerock/http/util/Uris.html) * [org.forgerock.util.AsyncFunction](../_attachments/apidocs/org/forgerock/util/AsyncFunction.html) * [org.forgerock.util.Function](../_attachments/apidocs/org/forgerock/util/Function.html) * [org.forgerock.util.promise.NeverThrowsException](../_attachments/apidocs/org/forgerock/util/promise/NeverThrowsException.html) * [org.forgerock.util.promise.Promise](../_attachments/apidocs/org/forgerock/util/promise/Promise.html) * [org.forgerock.services.context.Context](../_attachments/apidocs/org/forgerock/services/context/Context.html) * org.forgerock.http.protocol.\* * [org.forgerock.http.oauth2.AccessTokenInfo](../_attachments/apidocs/org/forgerock/http/oauth2/AccessTokenInfo.html) * [org.forgerock.json.JsonValue](../_attachments/apidocs/org/forgerock/json/JsonValue.html), and all its static methods, including `json(Object)`, `array(Object…​)`, `object(fields…​)`, and `field(String, Object)` * [org.forgerock.openig.util.JsonValues](../_attachments/apidocs/org/forgerock/openig/util/JsonValues.html) and all its static methods. * [org.forgerock.openig.tools.jwt.validation.Constraints](../_attachments/apidocs/org/forgerock/openig/tools/jwt/validation/Constraints.html) and all its static methods. ## More information * [ScriptableFilter](Filters.html#ScriptableFilter), [org.forgerock.openig.filter.ScriptableFilter](../_attachments/apidocs/org/forgerock/openig/filter/ScriptableFilter.html), and [org.forgerock.http.Filter](../_attachments/apidocs/org/forgerock/http/Filter.html) * [ScriptableHandler](Handlers.html#ScriptableHandler), [org.forgerock.openig.handler.ScriptableHandler](../_attachments/apidocs/org/forgerock/openig/handler/ScriptableHandler.html), and [org.forgerock.http.Handler](../_attachments/apidocs/org/forgerock/http/Handler.html) * [ScriptableThrottlingPolicy](ThrottlingPolicies.html#ScriptableThrottlingPolicy), [org.forgerock.openig.filter.throttling.ScriptableThrottlingPolicy.Heaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ScriptableThrottlingPolicy.Heaplet.html), and [org.forgerock.openig.filter.throttling.ThrottlingPolicy](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ThrottlingPolicy.html) * `ScriptableResourceAccess` in [OAuth2ResourceServerFilter](Filters.html#OAuth2ResourceServerFilter), [org.forgerock.openig.filter.oauth2.ScriptableResourceAccess](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/ScriptableResourceAccess.html), and [org.forgerock.http.oauth2.ResourceAccess](../_attachments/apidocs/org/forgerock/http/oauth2/ResourceAccess.html) * `ScriptableAccessTokenResolver` in [OAuth2ResourceServerFilter](Filters.html#OAuth2ResourceServerFilter), [org.forgerock.openig.filter.oauth2.ScriptableAccessTokenResolver](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/ScriptableAccessTokenResolver.html), and [org.forgerock.http.oauth2.AccessTokenResolver](../_attachments/apidocs/org/forgerock/http/oauth2/AccessTokenResolver.html) * `ScriptableJwtValidatorCustomizer` in [JwtValidationFilter](Filters.html#JwtValidationFilter) and [org.forgerock.openig.filter.jwt.ScriptableJwtValidatorCustomizer](../_attachments/apidocs/org/forgerock/openig/filter/jwt/ScriptableJwtValidatorCustomizer.html)