--- title: Backchannel Initialize node description: 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. component: auth-node-ref version: latest page_id: auth-node-ref::backchannel-initialize canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/backchannel-initialize.html superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/backchannel-initialize.html section_ids: example: Example main_journey: Main journey backchannel_authentication_journey: Backchannel authentication journey availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes errors: Errors --- # Backchannel Initialize node 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](backchannel-status.html), this node lets you implement *backchannel authentication* from within a journey. Find more information in [Backchannel authentication](https://docs.pingidentity.com/pingoneaic/am-authentication/backchannel-authentication.html). ## Example 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 ![backchannel nodes main journey](_images/backchannel-nodes-main-journey.png) a The Collect User to Login node is a [Scripted Decision node](scripted-decision.html). The script writes the attributes required for the backchannel authentication into the shared state. > **Collapse: Sample Scripted Decision node script** > > 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. > > ```bash > 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"; > } > ``` 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](message.html) (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](config-provider.html). * When the backchannel authentication is `In progress`, the journey proceeds to the In Progress Poll node (f), which is a [Polling Wait node](polling-wait.html). * When the backchannel authentication completes successfully, the journey proceeds to the Display Tree Results node (g), which is a [Scripted Decision node](scripted-decision.html). e The Configuration Provider node imitates a [Polling Wait node](polling-wait.html) that uses a script to display the backchannel redirect URI as long as the backchannel authentication request is in a `Pending` state. > **Collapse: Sample Config Provider node script** > > ```bash > 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](polling-wait.html) 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](scripted-decision.html) that displays the outcome of the backchannel authentication journey. > **Collapse: Sample Scripted Decision node script** > > ```bash > /* > - 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](failure.html) as it is not in itself an authentication journey. | ### Backchannel authentication journey ![backchannel nodes sub journey](_images/backchannel-nodes-sub-journey.png) 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](display-username.html) and a [Platform Password node](platform-password.html). 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](cloud/identity-store-decision.html). The main journey polls for completion of this subjourney. When this journey completes, the main journey continues. ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne Advanced Identity Cloud | Yes | | PingAM (self-managed) | Yes | | Ping Identity Platform (self-managed) | Yes | ## 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 This node has no dependencies. ## Configuration | 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 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](scripted-decision.html) to achieve this. | | Custom Redirect URL | If Redirect URL Type is `Custom`, set this field to the custom redirect URL for the authentication journey. | | Max Time (Seconds) | The maximum number of seconds to wait for the backchannel journey to complete before timing out. This lets you set a specific timeout for each backchannel journey, depending on the expected completion time for the journey. This value doesn't affect the authentication session timeout.If you don't set a value here, the backchannel journey times out after the Time to Live set for the realm.You can change this under Native Consoles > Access Management > Realms> *Realm Name* > Services > Transaction Authentication Service > Time to Live. | | Allow Retry | When enabled, the end user can retry the backchannel journey if it fails. There's no maximum *number* of retries, but the retry window ends after the configured `Max Time`.If you disable this option, the backchannel authentication token goes into the `Failure` state the first time the backchannel journey fails. In this case, calls to the [Backchannel Status node](backchannel-status.html) go to the Failure outcome.Default: Enabled | ## Outputs The node writes the following to the shared state: | 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. | ## 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: ```none Error retrieving subject from node state. ``` * If the node can't initialize the backchannel authentication journey, it logs the following error: ```none Error initializing back channel transaction. ```