Scripting environment

PingOne Advanced Identity Cloud supports scripts written in JavaScript.

The scripting environment implements a scripting engine for each of the context types that are executed on the server. There are two versions of the scripting engine: next-generation and legacy.

Access Java classes

Scripts can only import Java classes on the allowlist. PingOne Advanced Identity Cloud defines an allowlist per script type.

Legacy scripts

To access Java classes in a script, use the JavaImporter:

var fr = JavaImporter(
    org.forgerock.openam.auth.node.api.Action,
    javax.security.auth.callback.NameCallback
);

if (callbacks.isEmpty()) {
    action = fr.Action.send(
      new fr.NameCallback("Enter Your First Name"),
      new fr.NameCallback("Enter Your Last Name")
    ).build();
} else {
    nodeState.putShared("FirstName", callbacks.get(0).getName());
    nodeState.putShared("LastName", callbacks.get(1).getName());
    action = fr.Action.goTo("true").build();
}

View the Java class allowlist

To view the Java class allowlist for a particular context type:

Get an access token for the appropriate realm with the appropriate scopes. Learn more in Get an access token.

Run the following REST command:

$ curl 'https://<tenant-env-fqdn>/am/json/global-config/services/scripting/contexts/<context-value>/engineConfiguration' \(1)
--header 'authorization: Bearer <access-token>' (2)
{
  "_id": "engineConfiguration",
  "_rev": "-733065873",
  "propertyNamePrefix": "esv.",
  "serverTimeout": 0,
  "useSecurityManager": true,
  "maxThreads": 50,
  "coreThreads": 10,
  "whiteList": [
    "com.google.common.collect.ImmutableList",
    "…"
  ], (3)
  "idleTimeout": 60,
  "queueSize": 10,
  "blackList": [
    "java.lang.Class",
    "…"
  ],
  "_type": {
    "_id": "engineConfiguration",
    "name": "Scripting engine configuration",
    "collection": false
  }
}

1	Replace <context-value> with appropriate context value for the script you are working on. Learn more about context values in Manage scripts over REST.
2	Replace <access-token> with the access token.
3	The `whitelist` field shows all the classes currently on the allowlist.

Add a missing Java class to the allowlist

If required, you can request to have Java classes added to the allowlist. Learn more in How do I get Java classes added to the allowlist in Advanced Identity Cloud for scripting purposes? in the Ping Identity Knowledge Base.

To reduce the need to allowlist Java classes, consider migrating your scripts to use the next-generation scripting engine, which includes enhanced built-in script bindings for accessing many common script operations and the ability to include third-party software with library scripts.

Next-generation scripts

To enhance security, the next-generation scripting engine doesn’t support a configurable allowlist for Java classes.

Instead, check if next-generation bindings provide the functionality you need or implement the functionality as a reusable library script.

For example, use the callbacksBuilder binding for callback functionality:

if (callbacks.isEmpty()) {
  // Request callbacks
  callbacksBuilder.nameCallback(
    "First Name", "First Name");
  callbacksBuilder.nameCallback(
    "Last Name", "Last Name");
} else {
  // Callbacks returned
  var firstName =
    callbacks.getNameCallbacks().get(0);
  var lastName =
    callbacks.getNameCallbacks().get(1);

  nodeState.putShared("FirstName", firstName);
  nodeState.putShared("LastName", lastName);

  action.goTo("true");
}

Learn more about next-generation bindings and library scripts in:

In cases where reimplementation isn’t possible, you can request the functionality to be included as a secure script binding in a future release.

Supported libraries

PingOne Advanced Identity Cloud uses the Mozilla Rhino JavaScript engine version 1.7.14 to run JavaScript. Rhino has limited support for ES6 / ES2015 (JavaScript version 1.7).

Learn more in Rhino ES2015 Support.

Thread pools

The scripting engine defines a thread pool for each script type.

Each script executes in an individual thread. The scripting engine allocates threads until it reaches a maximum of 50 threads per pool. When the scripting engine reaches the maximum number of threads, it queues scripts until a thread becomes available.

When a script has either completed or remained idle for more than 60 seconds, the script engine terminates the thread and makes it available to the pool.