Identity Cloud

Scripted decision node API

The scripted decision node lets you write a server-side script in JavaScript to determine the path the authentication journey takes.

These scripts have access to a number of bindings, which provide the context to help you make the decision.

The primary role of a scripted decision node is to specify the possible paths a user can take. There are two methods to define these paths within the script:


The simplest method is to assign one or more string values to the outcome variable.

if (...) {
  outcome = "true"
} else {
  outcome = "false"

When configuring the scripted decision node in an authentication journey, add the two outcomes true and false, and connect them to other parts of the journey, so that journey evaluation can continue.

You can specify as many outcomes as required in your scripts; for example, you might have hours, days, and months. Be sure to specify each possible outcome when designing your authentication journey.


You can use the Action interface to define the script outcome and/or specify an operation to perform.


var fr = JavaImporter(

if (...) {
  // Set outcome to "true", and create and populate a custom session property:
  action = fr.Action.goTo("true").putSessionProperty("customKey", "customValue").build()
  // Set outcome to "false". If supported by the UI, the error message is displayed:
  action = fr.Action.goTo("false").withErrorMessage("Friendly error description.").build()

You can also use the Action interface for other functionality:

For more information on the Action interface, see Action in the AM Javadoc.

An outcome specified as an Action takes precedence over the value set for the outcome variable:

action = Action.goTo("false").build() // Tree continues along "false" outcome.

outcome = "true" // No effect.

For more information on specifying outcomes when using the scripted decision node, see Scripted Decision node.

The following table lists the bindings accessible to scripted decision node scripts:

Table 1. Scripted decision node bindings
Binding Information


Add information to the AM audit logs.

See Audit information.


Request additional data from the user, by sending any of the supported callbacks.

See Callbacks.


If the user has previously authenticated and has a session, use this variable to access the properties of that session.

The user will only have an existing session when performing a session upgrade. Any properties that may have been added by nodes earlier in the current journey will not appear on the user’s new session until the authentication journey is completed, and are therefore not available to the existingSession variable.

See Access existing session properties.


Make outbound HTTP calls.


Access the data stored in the user’s profile.

See Access profile data.


Write information to the AM debug logs.


Return the name of the realm to which the user is authenticating as a string.

For example, authenticating to the top-level realm returns a string value of / (forward-slash). Authenticating to a subrealm of the top level realm might return /subRealm.


Access the HTTP headers provided in the login request.

See Access request header data.


Access the HTTP request parameters provided in the login request.

See Access request parameter data.


Access the secrets configured in an AM instance.


Access data set by previous nodes in the journey, or store data to be used by subsequent nodes.

See Access shared state data.

Access request header data

Scripted Decision node scripts can access the headers provided by the login request by using the methods of the requestHeaders object.

Note that the script has access to a copy of the headers. Changing their values does not affect the request itself.


String[] requestHeaders.get(String HeaderName)

Return a java.util.ArrayList of the values in the named request header, or null, if the property is not set. Note that header names are case-sensitive.


var headerName = "user-agent"

if (requestHeaders.get(headerName).get(0).indexOf("Chrome") !== -1) {
    outcome = "true"
} else {
    outcome = "false"

Access request parameter data

Scripted Decision node scripts can access any query parameters provided by the login request by using the methods of the requestParameters object.

Note that the script has access to a copy of the parameters. Changing their values does not affect the request itself.


String[] requestParameters.get(String ParameterName)

Return a java.util.ArrayList of the values in the named request parameter, or null, if the parameter is not available.


var service
var authIndexType = requestParameters.get("authIndexType")

if (authIndexType && String(authIndexType.get(0)) === "service") {
    service = requestParameters.get("authIndexValue").get(0)

In JavaScript, the values stored in requestParameters have a typeof of object, and represent the java.lang.String class. Convert the value to a string in order to use strict equality comparisons.

Access shared state data

Scripted Decision node scripts can get access to the shared state within the journey by using the nodeState object.


JsonValue nodeState.get(String Property Name)

Returns the value of the named property. The value may come from the transient, secure, or shared states, in that order. For example, if the same property is available in several states, the method will return the value of the property in the transient state first.

If the property is not set, the method returns null.

Note that property names are case-sensitive.


var currentAuthLevel = nodeState.get("authLevel").asString()
var givenPassword = nodeState.get("password").asString()
nodeState nodeState.putShared(String PropertyName, String ProperyValue)

Sets the value of the named shared state property. Note that property names are case-sensitive.


try {
  var currentAuthLevel = nodeState.get("authLevel").asString()
} catch (e) {
  nodeState.putShared("errorMessage", e.toString())
nodeState nodeState.putTransient(String PropertyName, String ProperyValue)

Sets the value of the named transient state property. Note that property names are case-sensitive.


nodeState.putTransient("sensitiveKey", "sensitiveValue")

Access profile data

Scripted decision nodes can access profile data through the methods of the idRepository object.


Set idRepository.getAttribute(String UserName, String AttributeName)

Return the values of the named attribute for the named user.

Void idRepository.setAttribute(String UserName, String AttributeName, Array Attribute Values)

Set the named attribute as specified by the attribute value for the named user, and persist the result in the user’s profile.


var username = nodeState.get("username")
var attribute = "mail"

idRepository.setAttribute(username, attribute, ["", ""])
Void idRepository.addAttribute(String UserName, String AttributeName, String Attribute Value)

Add an attribute value to the list of attribute values associated with the attribute name for a particular user.


var username = nodeState.get("username")
var attribute = "mail"

// Add a value as a String.
idRepository.addAttribute(username, attribute, "")
logger.error(idRepository.getAttribute(username, attribute).toString())
// > ERROR: [,]

// Get the first value.
logger.error(idRepository.getAttribute(username, attribute).iterator().next())
// > ERROR:

// Get a value at the specified index.
logger.error(idRepository.getAttribute(username, attribute).toArray()[1])
// > ERROR:

logger.error(idRepository.getAttribute(username, "non-existing-attribute").toString())
// > ERROR: []: If no attribute by this name is found, an empty Set is returned.

Set session properties

Scripted Decision node scripts can create session properties by using the Action interface. The following example sets the outcome to true, and adds a custom session property:

var goTo = org.forgerock.openam.auth.node.api.Action.goTo

action = goTo("true").putSessionProperty("mySessionProperty","myPropertyValue").build()

Add the property name to the Allowlisted Session Property Names list in the Session Property Whitelist Service; otherwise, it will not be added to sessions.

For more information on this service, see Session Property Whitelist Service.

Add the script to a scripted decision node in your authentication journey. Users that authenticate successfully using that journey will have the property added to their session, as shown in the following output when introspecting a session:

    "username": "15249a65-8f9a-4063-9586-a2465963cee4",
    "universalId": "id=15249a65-8f9a-4063-9586-a2465963cee4,ou=user,o=alpha,ou=services,ou=am-config",
    "realm": "/alpha",
    "latestAccessTime": "2020-10-22T15:01:14Z",
    "maxIdleExpirationTime": "2020-10-22T15:31:14Z",
    "maxSessionExpirationTime": "2020-10-22T17:01:13Z",
    "properties": {
        "AMCtxId": "dffed74d-f203-469c-9ed2-34738915baea-5255",
        "mySessionProperty": "myPropertyValue"

Access existing session properties

Scripted decision node scripts can access any existing session properties during a session upgrade request, by using the existingSession object.

The following table lists the methods of the existingSession object:


String existingSession.get(String _Property Name)

Return the string value of the named existing session property, or null, if the property is not set. Note that property names are case-sensitive.

If the current request is not a session upgrade and does not provide an existing session, the existingSession variable is not declared. Check for a declaration before attempting to access the variable.


if (typeof existingSession !== 'undefined')
    existingAuthLevel = existingSession.get("AuthLevel")
    logger.error("Variable existingSession not declared - not a session upgrade.")


The scripted decision node can use callbacks to provide or request additional information during the authentication process.


The following script uses the NameCallBack callback to request a "Nickname" value from the user, and adds the returned value to the nodeState object for use elsewhere in the authentication journey:


var fr = JavaImporter(

with (fr) {
  if (callbacks.isEmpty()) {
    action = Action.send(new NameCallback("Enter Your Nickname")).build()
  } else {
    nodeState.putShared("Nickname", callbacks.get(0).getName())
    action = Action.goTo("true").build()

For a list of supported callbacks, see Supported callbacks.

Audit information

The scripted decision node can add information to audit log entries, by using the auditEntryDetail variable.

AM appends the value of the variable, which can be either plain text, or a JSON object, to the authentication audit logs.


The following JavaScript adds the user’s email address to the authentication.audit.json audit log file:

var currentUser = nodeState.get("username")
var attributeToRead = "mail"

auditEntryDetail="Extra Audit: " + currentUser + " email address: " +
outcome = "true"

The code above adds the information to the auditInfo element in the audit log entry:

        "displayName":"Audit Entry",
          "auditInfo":"Extra Audit: demo email address:"
Copyright © 2010-2022 ForgeRock, all rights reserved.