Scripted Decision Node API Functionality

Accessing 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.

The following table lists the methods of the requestHeaders object:

var headerName = "user-agent";

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

Accessing Shared State Data

Scripted Decision Node scripts can get access to the shared state within the tree by using the sharedState and transientState objects.

The following table lists the available methods:

var currentAuthLevel = sharedState.get("authLevel");

var givenPassword = transientState.get("password");

Accessing Profile Data

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

Setting Session Properties

Scripted Decision Node scripts can create session properties by using the Action API, as follows:

var fr = JavaImporter(
  org.forgerock.openam.auth.node.api.Action
)

with (fr) {
  action = Action.goTo("true").putSessionProperty("mySessionProperty","myPropertyValue").build()
}

import org.forgerock.openam.auth.node.api.Action

action =
  new Action.ActionBuilder("true").putSessionProperty("mySessionProperty","myPropertyValue").build();

Add the script to a scripted decision node in your authentication tree. Users that authenticate successfully using that tree 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"
    }
}

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

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

Using Callbacks

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

For example, the following scripts use the NameCallBack callback to request a "Nickname" value from the user, and adds the returned value to the sharedState map for use elsewhere in the authentication tree:

import org.forgerock.openam.auth.node.api.*;
import javax.security.auth.callback.NameCallback;

if (callbacks.isEmpty()) {
  action = Action.send(new NameCallback("Enter Your Nickname")).build();
} else {
  sharedState.put("Nickname", callbacks.get(0).getName());
  action = Action.goTo("true").build();
}

var fr = JavaImporter(
  org.forgerock.openam.auth.node.api,
  javax.security.auth.callback.NameCallback
);
with (fr) {
  if (callbacks.isEmpty()) {
    action = Action.send(new NameCallback("Enter Your Nickname")).build();
  } else {
    sharedState.put("Nickname", callbacks.get(0).getName());
    action = Action.goTo("true").build();
  }
}

For a list of supported callbacks, see "Supported Callbacks".

Adding Audit Information

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

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

For example, the following Groovy script adds the user's email address to the authentication.audit.json audit log file:

var currentUser = sharedState.get("username");
var attributeToRead = "mail";

auditEntryDetail="Extra Audit: " + currentUser + " email address: " +
  idRepository.getAttribute(currentUser,attributeToRead).iterator().next().toString();

outcome = "true";

The code above adds the information to the auditInfo element, for example:

{
  "_id":"f036618e-e318-4134-ac2a-13e860396103-545013",
  "timestamp":"2020-08-13T18:20:25.202Z",
  "eventName":"AM-NODE-LOGIN-COMPLETED",
  "transactionId":"f036618e-e318-4134-ac2a-13e860396103-544998",
  "trackingIds":[
    "f036618e-e318-4134-ac2a-13e860396103-544956"
  ],
  "principal":[
    "demo"
  ],
  "entries":[
    {
      "info":{
        "nodeOutcome":"true",
        "treeName":"Example",
        "displayName":"Audit Entry",
        "nodeType":"ScriptedDecisionNode",
        "nodeId":"13d40add-137c-4564-ad3c-7d98f7c180c1",
        "authLevel":"0",
        "nodeExtraLogging":{
          "auditInfo":"Extra Audit: demo email address: demo@example.com"
        }
      }
    }
  ]
}

For more information about auditing, see Setting Up Audit Logging.