Scripted decision node API

The scripted decision node lets you write a server-side script, in JavaScript or Groovy, 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:

outcome

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 tree, add the two outcomes true and false, and connect them to other parts of the tree, so that tree 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.

Action

You can use the Action interface to define the script outcome and/or specify an operation to perform, for example, by chaining with ActionBuilder functions.

Action.ActionBuilder functions:

Method Information

Method	Information
`public ActionBuilder putSessionProperty(String key, String value)`	Add a session property. Refer to Setting session properties.
`public ActionBuilder removeSessionProperty(String key)`	Remove an existing session property.
`public ActionBuilder withDescription(String description)`	Set a description for the action.
`public ActionBuilder withErrorMessage(String message)`	Set an error message to display to the end user when the journey reaches the Failure node.
`public ActionBuilder withIdentifiedIdentity(AMIdentity id)` `public ActionBuilder withIdentifiedIdentity(String username, IdType id)`	Set the identity, authenticated or not, of the user or agent verified to exist in an identity store. Use these methods to record the type of identified user. If the advanced server property, `org.forgerock.am.auth.trees.authenticate.identified.identity` is set to true, AM uses the stored identified identities to decide who to log in. This lets the authentication tree engine correctly resolve identities that have the same username. For more information, refer to advanced server properties.
`public ActionBuilder withLockoutMessage(String message)`	Set an error message to display to the end user when the account is locked or inactive.
`public ActionBuilder withStage(String stage)`	Set a stage name to return to the client to aid the rendering of the UI. The property is only sent if the script also sends callbacks.

public ActionBuilder putSessionProperty(String key, String value)

Add a session property.

Refer to Setting session properties.

public ActionBuilder removeSessionProperty(String key)

Remove an existing session property.

public ActionBuilder withDescription(String description)

Set a description for the action.

public ActionBuilder withErrorMessage(String message)

Set an error message to display to the end user when the journey reaches the Failure node.

public ActionBuilder withIdentifiedIdentity(AMIdentity id)

public ActionBuilder withIdentifiedIdentity(String username, IdType id)

Set the identity, authenticated or not, of the user or agent verified to exist in an identity store.

Use these methods to record the type of identified user. If the advanced server property, org.forgerock.am.auth.trees.authenticate.identified.identity is set to true, AM uses the stored identified identities to decide who to log in.

This lets the authentication tree engine correctly resolve identities that have the same username.

For more information, refer to advanced server properties.

public ActionBuilder withLockoutMessage(String message)

Set an error message to display to the end user when the account is locked or inactive.

public ActionBuilder withStage(String stage)

Set a stage name to return to the client to aid the rendering of the UI. The property is only sent if the script also sends callbacks.

For the full API, refer to ActionBuilder.

Example:

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

if (...) {
  // Set outcome to "true", and create and populate a custom session property:
  action = fr.Action.goTo("true").putSessionProperty("customKey", "customValue").build()
}
else
{
  // 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:

Setting session properties
Using Callbacks

For more information on the Action interface, refer to 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, refer to Scripted Decision node.

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

Scripted decision node bindings
Binding	Information
`auditEntryDetail`	Add information to the AM audit logs. Refer to Adding audit information.
`callbacks`	Request additional data from the user, by sending any of the supported callbacks. Refer to Using Callbacks.
`existingSession`	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 tree will not appear on the user’s new session until the authentication tree is completed, and are therefore not available to the `existingSession` variable. Refer to Accessing existing session properties.
`httpClient`	Make outbound HTTP calls. Refer to Accessing HTTP Services.
`idRepository`	Access the data stored in the user’s profile. Refer to Accessing profile data.
`logger`	Write information to the AM debug logs. Refer to Debug logging.
`realm`	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`.
`requestHeaders`	Access the HTTP headers provided in the login request. Refer to Accessing request header data.
`requestParameters`	Access the HTTP request parameters provided in the login request. Refer to Accessing request parameter data.
`secrets`	Access the secrets configured in an AM instance. Refer to Accessing credentials and secrets.
`nodeState`	Access data set by previous nodes in the tree, or store data to be used by subsequent nodes. Refer to Accessing shared state data.

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.

Methods

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.

Example:

var headerName = "user-agent"

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

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.

Methods

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.

Example:

JavaScript
Groovy

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

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

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

if (authIndexType && 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.

Accessing shared state data

A script can access the shared state of the tree with the methods of the nodeState object.

There are three types of state:

Shared: Non-sensitive state.
Transient: Sensitive state.

Transient state data is never sent back to the user’s browser in a callback so doesn’t need to be encrypted. The transient state is for sensitive data and for data not required after the next callback.
Secure: Encrypted sensitive state.

Secure state data is sent back to the user’s browser encrypted as part of the shared state object.

Transient state data is promoted to secure state data when:

A callback to the user is about to occur.
A downstream node is detected in the journey, requesting data in the transient state as script input.

Unless the downstream node explicitly requests the secure state data by name, the authentication journey removes it from the node state after processing the next callback.

For example, a node in a registration journey stores a user’s password in transient state. The node sends a callback to the user before an inner tree node, downstream in the journey, consumes that password. As part of the callback, the journey assesses what to add to the secure state. It does this by checking the state inputs that downstream nodes in the journey require. Nodes that only request * are ignored, as this would result in putting everything that’s in transient state into secure state, and retaining sensitive information longer than necessary.

If a downstream node requires the password, it must therefore explicitly request it as state input, even if it lists the * wildcard as input.

Methods

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

Example:

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.

Example:

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.

Example:

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

Accessing profile data

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

Methods

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.

Example:

JavaScript
Groovy

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

idRepository.setAttribute(username, attribute, ["user.0@a.com", "user.0@b.com"])

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

idRepository.setAttribute(username, attribute, ["user.0@a.com", "user.0@b.com"] as String[])

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.

Example:

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

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

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

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

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

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:

JavaScript
Groovy

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 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, refer to Session Property Whitelist Service.

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:

Methods

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.

Example:

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.

Example:

The following scripts use 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 tree:

Groovy
JavaScript

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, refer to Supported callbacks.

Accessing credentials and secrets

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

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

Methods

String secrets.getGenericSecret(String Secret ID)

Returns the value of the specified secret ID.

If the secret ID is defined at the realm level, its value is returned; otherwise, the script returns the value defined at the global level.

Only secret IDs that begin with the string scripted.node. are accessible to scripts.

For more information on creating secret IDs in a secret store, refer to Secret stores.

Use the following functions to format the returned secret value:

getAsBytes()

Retrieve the secret value in byte[] format.

getAsUtf8()

Retrieve the secret value in UTF-8 format.

Example:

The following example scripts show how to get the value (passwd) from a secret ID named scripted.node.secret.id. They use the value in a basic authentication header to access the http://httpbin.org/basic-auth/{user}/{passwd} service:

JavaScript
Groovy

var username = "demoUser"
var password = secrets.getGenericSecret("scripted.node.secret.id").getAsUtf8()

var auth = java.util.Base64.getEncoder().encodeToString(java.lang.String(username + ":" + password).getBytes())

var request = new org.forgerock.http.protocol.Request()
request.setMethod("GET")
request.setUri("http://httpbin.org/basic-auth/demoUser/passwd")
request.getHeaders().add("content-type","application/json; charset=utf-8")
request.getHeaders().add("Authorization", "Basic " + auth)

var response = httpClient.send(request).get()
var jsonResult = JSON.parse(response.getEntity().getString())
logger.error("Script result: " + JSON.stringify(jsonResult))
if (jsonResult.hasOwnProperty("authenticated")) {
    logger.error("outcome = success")
    outcome = "success"
}  else {
    logger.error("outcome = failure")
    outcome = "failure"
}

def username = "demoUser"
def password = secrets.getGenericSecret("scripted.node.secret.id").getAsUtf8()

def auth = java.util.Base64.getEncoder().encodeToString((username + ":" + password).getBytes())

def request = new org.forgerock.http.protocol.Request()
request.setMethod("GET")
request.setUri("http://httpbin.org/basic-auth/demoUser/passwd")
request.getHeaders().add("content-type","application/json; charset=utf-8")
request.getHeaders().add("Authorization", "Basic " + auth)

def response = httpClient.send(request).get()
if (response.status.successful) {
    logger.error("outcome = success")
    outcome = "success"
}  else {
    logger.error("outcome = failure")
    outcome = "failure"
}

To use these sample scripts, you may need to add the following classes to the class allowlist property in the AUTHENTICATION_TREE_DECISION_NODE scripting engine configuration:

org.mozilla.javascript.ConsString
java.util.Base64
java.util.Base64$Encoder

Refer to Security.

Adding audit information

Use a script to add information to audit log entries with the auditEntryDetail variable.

AM appends the value of the variable to the authentication audit logs.

For JavaScript, the variable must be a string. This example adds the username and email address to the log entry:

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

var detailStr = ("Extra Audit: [" + username + "] Email address: " + email).toString();
auditEntryDetail= detailStr;

outcome = "true";

AM records the audit string in the entries > info > nodeExtraLogging > auditInfo field of the authentication log entry:

{
    "_id": "31a9caa2-1439-4088-813f-a60c5f083a45-7725962",
    "timestamp": "2022-12-13T17:22:14.818Z",
    "eventName": "AM-NODE-LOGIN-COMPLETED",
    "transactionId": "31a9caa2-1439-4088-813f-a60c5f083a45-7725948",
    "trackingIds": [
        "31a9caa2-1439-4088-813f-a60c5f083a45-7725576"
    ],
    "principal": [
        "bjensen"
    ],
    "entries": [
        {
            "info": {
                "nodeOutcome": "true",
                "treeName": "Example",
                "displayName": "Audit Entry",
                "nodeType": "ScriptedDecisionNode",
                "nodeId": "275a8aeb-7a61-4c70-acc2-decb1e0bc139",
                "authLevel": "0",
                "nodeExtraLogging": {
                    "auditInfo": "Extra Audit: [bjensen] Email address: bjensen@example.com"
                }
            }
        }
    ],
    "realm": "/alpha",
    "component": "Authentication"
}

For more information about auditing, refer to Audit logging.

Access Management 7.2.2

Scripted decision node API

Accessing request header data

Methods

Accessing request parameter data

Methods

Accessing shared state data

Methods

Accessing profile data

Methods

Setting session properties

Accessing existing session properties

Methods

Using Callbacks

Accessing credentials and secrets

Methods

Adding audit information