Backchannel Initialize node

Advanced Identity Cloud

The Backchannel Initialize node lets you start a separate journey that runs asynchronously, possibly by a different user or agent. The node takes an incoming user ID and generates a URL to a journey where the identified user or agent authenticates.

Together with the Backchannel Status node, this node lets you implement backchannel authentication from within a journey. Find more information in the documentation on Backchannel authentication for Advanced Identity Cloud.

Availability

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

Product

Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Ping Identity Platform (self-managed)

Inputs

This node optionally reads the user ID of the subject the journey’s being initialized for from the incoming node state. The user ID is stored in the nodeState key specified in the Subject Name Key property.

Dependencies

None

Configuration

Property Usage

Property	Usage
Journey	The asynchronous journey to initialize. Select a journey from the list of configured journeys.
Subject Type	The type of subject to initialize the journey for: User The subject is a user identity. Agent The subject is a web agent or Java agent. None Setting the Subject Type to `None` means any subject can log in using the initialized journey.
Subject Name Key	The `nodeState` key that contains the user ID of the subject you’re initializing the journey for. This property is ignored if the Subject Type is `None`.
Data Object Key	The node state key that contains the data object (if present) to pass to the journey at the root level of the shared state.
Redirect URL Type	The type of redirect URL to save to node state: By default, the base URL of the redirect URI is retrieved from the incoming HTTP request. Get The node redirects the user to a URL based on the base URL service. The redirect uses a GET request to the `/XUI/Login` endpoint. Post The node redirects the user to a URL based on the base URL service. The redirect uses a POST request to the `authenticate` endpoint. Custom The node redirects the user to the URL specified in the Custom Redirect URL field. None If the none of the redirect URL mechanisms (`Get`, `Post`, or `Custom`) meet your business requirements, you can use the transaction ID stored in state to make your own redirect URL outside of the functionality of this node. Connect this output to a Scripted Decision node to achieve this.
Custom Redirect URL	If Redirect URL Type is `Custom`, set this field to the custom redirect URL for the authentication journey.

Journey

The asynchronous journey to initialize.

Select a journey from the list of configured journeys.

Subject Type

The type of subject to initialize the journey for:

User: The subject is a user identity.
Agent: The subject is a web agent or Java agent.
None: Setting the Subject Type to None means any subject can log in using the initialized journey.

Subject Name Key

The nodeState key that contains the user ID of the subject you’re initializing the journey for.

This property is ignored if the Subject Type is None.

Data Object Key

The node state key that contains the data object (if present) to pass to the journey at the root level of the shared state.

Redirect URL Type

The type of redirect URL to save to node state:

By default, the base URL of the redirect URI is retrieved from the incoming HTTP request.

Get: The node redirects the user to a URL based on the base URL service. The redirect uses a GET request to the /XUI/Login endpoint.
Post: The node redirects the user to a URL based on the base URL service. The redirect uses a POST request to the authenticate endpoint.
Custom: The node redirects the user to the URL specified in the Custom Redirect URL field.
None: If the none of the redirect URL mechanisms (Get, Post, or Custom) meet your business requirements, you can use the transaction ID stored in state to make your own redirect URL outside of the functionality of this node. Connect this output to a Scripted Decision node to achieve this.

Custom Redirect URL

If Redirect URL Type is Custom, set this field to the custom redirect URL for the authentication journey.

Outputs

The node writes the following to the shared state:

Shared state key Information

Shared state key	Information
`backchannel-transaction`	The transaction ID of the backchannel authentication request.
`backchannel-redirectUri`	The generated redirect URI.
`backchannel-data`	An optional data object with additional information about the authenticating user.

backchannel-transaction

The transaction ID of the backchannel authentication request.

backchannel-redirectUri

The generated redirect URI.

backchannel-data

An optional data object with additional information about the authenticating user.

Outcomes

Created: The journey follows this outcome path if the node was able to create the backchannel authentication request.
Unknown Subject: The journey follows this outcome path if the subject in the incoming node state doesn’t match an identity object in the backend identity store.
Error: The journey follows this outcome path if the node can’t retrieve the subject from the node state.

Errors

If the node can’t retrieve the subject from the incoming state, it logs the following warning:
```
Error retrieving subject from node state.
```
If the node can’t initialize the backchannel authentication journey, it logs the following error:
```
Error initializing back channel transaction.
```

Examples

This example uses the Backchannel Initialize and Backchannel Status nodes to implement backchannel authentication.

The example shows two journeys:

The main journey initializes a backchannel authentication journey.
The backchannel journey is a simple authentication journey.

Main journey

a The Collect User to Login node is a Scripted Decision node. The script writes the attributes required for the backchannel authentication into the shared state.

Sample Scripted Decision node script

Advanced Identity Cloud
PingAM

The script queries the backend identity object to get the userId, then writes that and the attributes required for the backchannel authentication into the shared state.

if (callbacks.isEmpty()) {
    // Request callbacks
    callbacksBuilder.nameCallback("User to authenticate");
} else {
    // Callbacks returned from browser, save username and password
    var username = callbacks.getNameCallbacks().get(0);
    var queryRes = openidm.query("managed/alpha_user", {
        "_queryFilter": `/userName eq '${username}'`
    }, ["*", "_id"]);
    var userId = queryRes.result[0]._id
    var identity = idRepository.getIdentity(userId);
    nodeState.putShared("backchannel-user", identity.getName());
    nodeState.putShared("backchannel-data", {
        "username": username,
        "objectAttributes": {
            "userName": username,
            "_id": userId
        }
    });
    nodeState.putShared("_id", userId);
    outcome = "outcome";
}

Not yet available in PingAM

b The Backchannel Initialize node reads the value of the backchannel-user key from the shared state. This key contains the userName:

If the userName is available and 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.
If the userName can be read but the user or agent isn’t valid, the journey proceeds to a Message node (c) and redirects the user to the start of the journey to attempt gathering data again.

d The Backchannel Status node reads the transaction ID and provides status on the authentication request:

If the backchannel authentication request is Pending, the journey proceeds to the Display Redirect URL Poll node (e), which is a Configuration Provider node.
When the backchannel authentication is In progress, the journey proceeds to the In Progress Poll node (f), which is a Polling Wait node.
When the backchannel authentication completes successfully, the journey proceeds to the Display Tree Results node (g), which is a Scripted Decision node.

e The Configuration Provider node imitates a Polling Wait node that uses a script to display the backchannel redirect URI as long as the backchannel authentication request is in a Pending state.

Sample Config Provider node script

var uri = nodeState.get("backchannel-redirectUri").asString();
config = {
    "spamDetectionTolerance": 3,
    "spamDetectionEnabled": true,
    "exitMessage": {},
    "waitingMessage": {
        "en": uri
    },
    "secondsToWait": 5,
    "exitable": true
};

After 5 seconds, the journey returns to the Backchannel Status node.
If the journey exits before it returns to the Backchannel Status node, the user is redirected to the start of the main journey to attempt gathering data again.
If the Configuration Provider node detects spam or misconfiguration, the main journey follows the failure outcome path.

f The In Progress Poll node is a Polling Wait node that pauses the main journey until the Backchannel journey is complete.

After 8 seconds, the journey returns to the Backchannel Status node.
If the journey exits before it returns to the Backchannel Status node, the user is redirected to the start of the main journey to attempt gathering data again.
If the node detects spam, the main journey follows the failure outcome path.

g The Display Tree Results node is a Scripted Decision node that displays the outcome of the backchannel authentication journey.

Sample Scripted Decision node script

/*
- Data made available by nodes that have already executed are available in the sharedState variable.
- The script should set outcome to either "true" or "false".
*/
if (callbacks.isEmpty()) {
    var sessionProperties = nodeState.get("backchannel-sessionProperties");
    callbacksBuilder.textOutputCallback(0, sessionProperties);
} else {
    outcome = "outcome";
}

This journey always ends on the Failure node as it is not in itself an authentication journey.

Backchannel authentication journey

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

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 Identity Store Decision node assesses the user credentials. Find more information on this node and its outcomes in Identity Store Decision node.

The main journey polls for completion of this subjourney. When this journey completes, the main journey continues.

Auth node reference