The Scripting Environment

AM supports scripts written in either JavaScript, or Groovy [1], and the same variables and bindings are delivered to scripts of either language.

You can use a script to check the version of the JavaScript engine AM is using. You could temporarily add the following script to a Scripted Decision node, for example, to output the engine version to the debug log:

var rhino = JavaImporter(
  org.mozilla.javascript.Context
)

var currentContext = rhino.Context.getCurrentContext()
var rhinoVersion = currentContext.getImplementationVersion()

logger.error("JS Script Engine: " + rhinoVersion)

outcome = "true"

Note

Ensure the following are listed in the Java class whitelist property of the scripting engine.

  • org.mozilla.javascript.Context

  • org.forgerock.openam.scripting.timeouts.*

To view the Java class whitelist, go to Configure > Global Services > Scripting > Secondary Configurations. Select the script type, and on the Secondary Configurations tab, click engineConfiguration.

For information on the capabilities of the JavaScript engine AM uses, see the Mozilla MDN Docs.

You can use a script to check the version of the Groovy scripting engine AM is using. You could temporarily add the following script to a Scripted Decision node, for example, to output the engine version to the debug log:

logger.error("Groovy Script Engine: " + GroovySystem.version)

outcome = "true"

Note

Ensure the following are listed in the Java class whitelist property of the scripting engine.

  • groovy.lang.GroovySystem

To view the Java class whitelist, go to Configure > Global Services > Scripting > Secondary Configurations. Select the script type, and on the Secondary Configurations tab, click engineConfiguration.

For information on the capabilities of the Groovy engine AM uses, see Apache Groovy.

To access the functionality AM provides, import the required Java class or package, as follows:

var fr = JavaImporter(
    org.forgerock.openam.auth.node.api,
    javax.security.auth.callback.NameCallback
);
with (fr) {
    ...
}
import org.forgerock.openam.auth.node.api.*;
import javax.security.auth.callback.NameCallback;

You may need to whitelist the classes you use in scripts. See "Security".

You can use scripts to modify default AM behavior in the following situations, also known as contexts:

Client-side Authentication

Scripts that are executed on the client during authentication. Client-side scripts must be in JavaScript.

Server-side Authentication

Scripts are included in an authentication module within a chain and are executed on the server during authentication.

Authentication Trees

Scripts are included in an authentication node within a tree and are executed on the server during authentication.

Policy Condition

Scripts used as conditions within policies.

OIDC Claims

Scripts that gather and populate the claims in a request when issuing an ID token or making a request to the userinfo endpoint.

OAuth 2.0 Access Tokens

Scripts that modify the key-value pairs contained within access tokens before they are issued to a client.

AM implements a configurable scripting engine for each of the context types that are executed on the server.

The scripting engines in AM have two main components: security settings, and the thread pool.

Diagram of the scripting environment within AM.

Learn more:



[1] Scripts used for client-side authentication must be in written in JavaScript.

Read a different version of :