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.

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

Accessing Shared State Data

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

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 interface. The following examples set the outcome to true, and add a custom session property:

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

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

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

action =
  Action.goTo("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:

Using Callbacks

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

Example:

The following scripts use the NameCallBack callback to request a "Nickname" value from the user, and adds the returned value to the nodeState 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 {
  nodeState.putShared("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 {
    nodeState.putShared("Nickname", callbacks.get(0).getName())
    action = Action.goTo("true").build()
  }
}

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

Accessing Credentials and Secrets

Scripts used in a scripted decision node can access the secrets configured in AM secret stores.

For example, a script can access credentials or secrets defined in a file system secret volume in order to make outbound calls to a third-party REST service, without hard-coding those credentials in the script.

Adding 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 to the authentication audit logs. For JavaScript, the variable must be a string.

Example:

The following scripts add the user's email address to the authentication.audit.json audit log file:

var currentUser = nodeState.get("username").asString()
var email = idRepository.getAttribute(currentUser,"mail").iterator().next().toString()

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

outcome = "true"

var currentUser = nodeState.get("username").asString()
var email = idRepository.getAttribute(currentUser,"mail").iterator().next().toString()
var detailStr = ("Extra Audit: " + currentUser + " email address: " + email).toString()

auditEntryDetail = detailStr

outcome = "true"

AM records the audit string in the auditInfo field of the authentication audit log entry:

{
  "_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.