IG 2023.2

Scripts

IG uses Groovy 4 for scripting. For more information, refer to the Groovy Language Documentation.

Use scripts with the following object types:

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

{
  "name": string,
  "type": scriptable object type,
  "config": {
    "type": string,
    "file": configuration expression<string>,  // Use either "file"
    "source": [ string, ... ],                 // or "source", but not both.
    "args": map or configuration expression<map>,
    "clientHandler": Handler reference
  }
}

Properties

"type": string, required

The Internet media type (formerly MIME type) of the script, "application/x-groovy" for Groovy

"file": configuration expression<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>, 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:

"source": [
    "Response response = new Response(Status.OK)",
    "response.entity = 'foo'",
    "return response"
]
"args": map or configuration expression<map>, optional

A map of one or more data pairs with the format Map<String, String>, where:

  • The key is the name of a configuration parameter in a script

  • The value is a string to use in the script, or a configuration expression that evaluates to the string

The following formats are allowed:

{
  "args": {
    "string": "configuration expression<string>",
    ...
  }
}
{
  "args": "configuration expression<map>"
}

In the following example, the property is a map whose values are scalars, arrays, and objects:

{
  "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:

    response.status = Status.valueOf(418, reason[1])

    For information about the 418 status coderefer to RFC 7168: 418 I’m a Teapot.

  • The following example configures arguments as strings and numbers for a ScriptableThrottlingPolicy:

    "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:

    if (attributes.rate.status == status) {
  return new ThrottlingRate(rate, duration)
}

  • The following example configures arguments that reference a SampleFilter defined in the heap:

    {
  "heap": [
    {
      "name": "SampleFilter",
      "type": "SampleFilter",
      "config": {
        "name": "X-Greeting",
        "value": "Hello world"
      }
    }
  ]
}

    In the following example, the property is a map whose value is an expression to pass SampleFilter to the script:

    {
  "args": {
    "filter": "${heap['SampleFilter']}"
  }
}

    The script can then reference SampleFilter as filter.

"clientHandler": ClientHandler reference, optional

A Handler 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.

openig

An implicit object that provides access to the environment when expressions are evaluated.

attributes

The attributes 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 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, refer to JwtValidator.Builder.

constraints

The constraints object, all its static methods, constant(String), and claim(String).

Use this object for JWT validation with the customizer property of JwtValidationFilter.

claim(String) must be followed by one of the following methods: asString(), asInteger(), asLong(), asDouble(), asBoolean(), as(yourCustomJsonValueTransformer)

context

The processing context.

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<string, context> object. For information, refer to Contexts.

request

The HTTP request.

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 parameters

For more information, refer to the Deprecated section of the Release Notes.
globals

This object is a Map that holds variables that persist across successive invocations.

http

An embedded client for making outbound HTTP requests, which is an org.forgerock.http.Client.

If a "clientHandler" is set in the configuration, then that Handler is used. Otherwise, the default ClientHandler configuration is used.

For information, refer to Handlers.

ldap (deprecated)
The LdapClient class and the ldap script binding are deprecated. For more information, refer to the Deprecated section of the Release Notes.

The ldap object provides an embedded LDAP client.

Use this client to perform outbound LDAP requests, such as LDAP authentication.

logger

The logger 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, refer to Logging in 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 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:

More information

Copyright © 2010-2023 ForgeRock, all rights reserved.