Backchannel Notification node

The Backchannel Notification node adds data to the backchannel transaction from the backchannel journey, which the Backchannel Status node can read. This lets you send real-time status updates to the main journey from the backchannel journey.

Example

The following example shows how the Backchannel Notification node can be used in an out-of-band authentication journey to keep a help desk agent informed of progress while they’re verifying a user’s identity. The help desk agent can see real-time status updates when the user enters their password and when their credentials have been confirmed.

The example shows two journeys:

The main journey initializes a backchannel authentication journey and displays status updates to the help desk agent.
The backchannel journey is a simple authentication journey that adds status updates to the shared state and uses the Backchannel Notification node to add this data to the backchannel transaction.

Main journey

a The Page node with an Attribute Collector node prompts the help desk agent for the end user’s email address.

b The Identify Existing User node attempts to look up the username by matching the email address to the email address in an identity profile.

The lookup fails if no matching email address is found, or if more than one user profile uses the same email address.

c The Set Backchannel State Properties custom scripted node writes the _id, objectAttributes, and username to the shared state.

This example uses the following configuration:

Attribute list to set: _id
objectAttributes
username
Backchannel nodeState property: backchannel:data

How do I create this custom scripted node?

The following steps provide the minimum configuration required to create this custom scripted node. Learn more in custom scripted nodes.

In the AM admin UI, go to Realms > alpha > Authentication > Node Designer and click Create Node Type.
On the New Node Type page, enter the following details and click Create:

Service Name

setbackchannelstateproperties

Display Name

Set Backchannel State Properties
In the Outcomes field, enter Next.

In the Properties field, add the following JSON object to define the properties for this node:

{
  "attributeListProperty": {
    "title": "Attribute list to set",
    "description": "List of attributes to include in the backchannel nodeState object",
    "type": "STRING",
    "required": true,
    "multivalued": true
  },
  "backchannelStateProperty": {
    "title": "Backchannel nodeState property",
    "description": "Property name set in nodeState for the backchannel journey to consume",
    "type": "STRING",
    "required": true,
    "defaultValue": "backchannel:data",
    "multivalued": false
  }
}

In the Script field, add the following script to define the behavior of the node:

(function () {
  logger.error(scriptName + "Node execution started");

  //Get node properties
  var nodeStateProperty = properties.backchannelStateProperty;
  var attributeList = properties.attributeListProperty;

  //Loop to get and set attributes into the nodeStateProperty nodeState variable
  var out = {};
  for (var i = 0; i < attributeList.length; i++) {
    var k = attributeList[i];
    var v = nodeState.get(k);
    if (v !== null && v !== undefined) out[k] = v;
  }
  nodeState.putShared(nodeStateProperty, out);
    logger.error(scriptName + "Node execution completed");
  action.goTo("Next");
})();

Enable the Error Outcome and click Save Changes to create the custom node.

d The Backchannel Initialize node reads the username from the shared state.

If the username is valid, the node generates a redirect URI to start the backchannel authentication journey. The node writes the redirect URI and the transaction ID of the backchannel transaction to the shared state, and the journey proceeds to the Backchannel Status node.
If the username can’t be read, the journey follows the Error outcome and fails.

e The Backchannel Status node reads the transaction ID and provides status on the authentication request.

This example requires the following configuration:

Record Transaction Data: Enabled
Transaction Data Key: transaction:data

f The Pending Wait node is a Polling Wait node that pauses this journey when the backchannel authentication request has a status of Pending. After 3 seconds, the journey returns to the Backchannel Status node.

g The In Progress Wait node is a Configuration Provider node. It imitates a Polling Wait node and uses a script to display messages from the backchannel journey to the help desk agent when the backchannel authentication has a status of In progress.

Sample Config Provider node script

var message;
var data = nodeState.get("transaction:data");
//Make sure this property name matches the Transaction Data Key configured in the Backchannel Status node
if (data) {
    message = data["journeyStatus"];
//Make sure this property name matches the Journey status property name configured in the Set Front Channel Status node.
} else {
    message = "Authentication in progress...";
}
config = {
    "secondsToWait": 3,
    "spamDetectionEnabled": false,
    "spamDetectionTolerance": 3,
    "waitingMessage": { "en": message },
    "exitable": false,
    "exitMessage": {}
};

h The User Message To Display custom scripted node displays a message to the help desk agent when the backchannel authentication completes successfully.

This example uses the following configuration:

Message to display: User successfully authenticated

How do I create this custom scripted node?

The following steps provide the minimum configuration required to create this custom scripted node. Learn more in custom scripted nodes.

In the AM admin UI, go to Realms > alpha > Authentication > Node Designer and click Create Node Type.
On the New Node Type page, enter the following details and click Create:

Service Name

usermessagetodisplay

Display Name

User Message to Display
In the Outcomes field, enter Success.

In the Properties field, add the following JSON object to define the properties for this node:

{
  "message": {
    "title": "Message to display",
    "description": "Message to display to the user",
    "type": "STRING",
    "required": true,
    "multivalued": false
  }
}

In the Script field, add the following script to define the behavior of the node:

(function () {
  logger.error(scriptName + "Node execution started");

  if (callbacks.isEmpty()) {
    var userMessage = properties.message;
    callbacksBuilder.textOutputCallback(0, userMessage);
  } else {
    logger.error(scriptName + "Node execution completed");
    action.goTo("Success");
  }
})();

Click Save Changes to create the custom node.

Backchannel journey

This is a basic authentication journey that takes credentials and authenticates the user based on their existence in the backend identity store.

Backchannel authentication journey with notifications

a The Page node includes a Display Username node and a Platform Password node. The username has been supplied in the shared state from the main journey. The user needs to enter their password.

b The Set Front Channel Status custom scripted node adds data to the shared state that the Backchannel Notification node can send to the main journey.

This example uses the following configuration:

Journey status shared state key: transaction:notify
Journey status property name: journeyStatus
Journey status message: User has entered their credentials

How do I create this custom scripted node?

The following steps provide the minimum configuration required to create this custom scripted node. Learn more in custom scripted nodes.

In the AM admin UI, go to Realms > alpha > Authentication > Node Designer and click Create Node Type.
On the New Node Type page, enter the following details and click Create:

Service Name

setfrontchannelstatus

Display Name

Set Front Channel Status
In the Outcomes field, enter Success and Error.

In the Properties field, add the following JSON object to define the properties for this node:

{
  "journeyStatusKey": {
    "title": "Journey status shared state key",
    "description": "The shared state key where the message object will be stored (e.g. transaction:notify). This is the top-level key that will be updated in the journey state.",
    "type": "STRING",
    "required": true,
    "defaultValue": "transaction:notify",
    "multivalued": false
  },
  "journeyStatusProperty": {
    "title": "Journey status property name",
    "description": "The name of the property inside the shared state object (e.g. journeyStatus). This defines the field that will hold the message value.",
    "type": "STRING",
    "required": true,
    "defaultValue": "journeyStatus",
    "multivalued": false
  },
  "journeyStatusValue": {
    "title": "Journey status message",
    "description": "The message to store in shared state. This value will be used by downstream nodes (e.g. Backchannel Notification) to update the front-channel experience.",
    "type": "STRING",
    "required": true,
    "defaultValue": "Example Front Channel Message",
    "multivalued": false
  }
}

In the Script field, add the following script to define the behavior of the node:

/**
 * Script to update sharedState with a key and object value retrieved from properties.value of the custom node
 * This sharedState key/value is then used by the Backchannel Notification node to update the front channel state
 * Example property values:
 *   journeyStatusKey      = "transaction:notify"
 *   journeyStatusProperty = "journeyStatus"
 *   journeyStatusValue    = "Front Channel Message"
 *
 * sharedState Result:
 *   ["transaction:notify"] = { journeyStatus: "Front Channel Message" }
 */

var nodeOutcomes = {
    SUCCESS: "Success",
    ERROR: "Error"
};

(function () {
    logger.error(scriptName + ": Node execution started");
    try {
        var stateKey = properties.journeyStatusKey;
        var propertyName = properties.journeyStatusProperty;
        var propertyValue = properties.journeyStatusValue;
        var obj = {};
        obj[propertyName] = propertyValue;
        nodeState.putShared(stateKey, obj);
        logger.error(scriptName + ": Node execution completed");
        action.goTo(nodeOutcomes.SUCCESS);
    } catch (e) {
        logger.error(scriptName + ": Failed to update sharedState. Exception: " + e);
        action.goTo(nodeOutcomes.ERROR);
    }
})();

Click Save Changes to create the custom node.

c The Backchannel Notification node reads the shared state and sends a status update to the main journey to inform the help desk agent that the user has entered their credentials.

d The Data Store Decision node validates the username-password credentials.

e The Set Front Channel Status custom scripted node adds data to the shared state that the Backchannel Notification node can send to the main journey. This is the custom scripted node you created earlier in this example.

This instance of the node uses the following configuration:

Journey status shared state key: transaction:notify
Journey status property name: journeyStatus
Journey status message: User’s credentials are valid

f The Backchannel Notification node reads the shared state and sends a status update to the main journey to inform the help desk agent that the user’s credentials match those stored in the data store.

Availability

Product	Available?
PingOne Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node reads data from the incoming node state using the key specified in the Data Key. The key value must be a JSON object.

Implement a node earlier in the journey to add data to the incoming node state using this key. For example, you could use custom scripted nodes or a Scripted Decision node.

Dependencies

This node has no dependencies.

Configuration

Property Usage

Property	Usage
Data Key	The shared state key that contains the data you want to add to the backchannel transaction. For example `transaction:notify`. This key is used to read data from the incoming node state.

Data Key

The shared state key that contains the data you want to add to the backchannel transaction. For example transaction:notify.

This key is used to read data from the incoming node state.

Outputs

This node doesn’t change the shared state.

Callbacks

This node doesn’t send any callbacks.

Outcomes

Success: The backchannel notification was successfully sent.
Error: An error occurred when sending the backchannel notification.

Errors

The node can log the following errors:

Failed to update backchannel transaction

An error occurred when the node attempted to update the backchannel transaction with the data from the incoming node state.

The node can log the following warnings:

Transaction ID not found in context

The transaction ID is missing from the incoming request context.
Data in state at dataKey data key was not found or incorrect type, not updating transaction.

The Data Key configured for the node doesn’t exist in the incoming node state, or it exists but contains invalid data.

Authentication nodes

Backchannel Notification node

Example

Main journey

Backchannel journey

Availability

Inputs

Dependencies

Configuration

Outputs

Callbacks

Outcomes

Errors