Advanced Identity Cloud

Configuration Provider node

The Configuration Provider node is a scripted node that dynamically imitates another node and replaces it in the journey.

The script builds a map of configuration properties matching settings for the imitated node. The Configuration Provider node uses the settings to imitate the other node.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

The specific shared state inputs depend on your script and the configuration it builds. The shared state data must include all required Script Inputs properties.

In other words, shared state data must include whatever the Script requires to prepare configuration data for the imitated node.

Dependencies

To use this node, you need to prepare a script that provides values for the settings of the imitated node.

  1. Choose the type of node to imitate

  2. Get a template script

  3. Configure the script

Choose the type of node to imitate

The imitated node must have a defined set of outcomes.

This can be a variable set of outcomes from a predefined list, such as the Polling Wait node, or a fixed set of outcomes, such as the Message node.

You can’t use a node type whose outcomes are defined entirely by configuration, such as the Scripted Decision node.

Get a template script

Use the REST API to get the required configuration properties for the imitated node.

  1. Call the following API endpoint with the configProviderScript action to get a template script for the type of node you want to imitate:

    /realm-config/authentication/authenticationtrees/nodes/node-type?_action=configProviderScript
    bash

    For example, the following request returns a base64-encoded template script for a Polling Wait node:

    $ curl \
--request POST \
--header "Authorization: Bearer access-token"\
--header "Content-Type: application/json" \
"https://tenant-env-fqdn/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/PollingWaitNode?_action=configProviderScript"
{
  "script":"LyoqCiAqIFRoZSBmb2xsb3dpbmcgc2.."
}
    bash

  2. Decode the script value, for example, by using an online base64 decoder.

    The decoded output shows the required properties. For example, a request for the Polling Wait node generates the following template script:

    config = {
  "secondsToWait" : 8,
  "spamDetectionEnabled" : false,
  "spamDetectionTolerance" : 3,
  "waitingMessage" : { },
  "exitable" : false,
  "exitMessage" : { }
};
    json

Configure the script

Use the imitated node’s properties to create a Configuration Provider Node or Configuration Provider Node (Next-Gen) type script.

Learn more in Auth scripting.

  1. Base your script on the config-provider-node.js sample.

    Your script must have a config object. This object must define the configuration properties that match the settings of the imitated node.

    For example, a script for the Email Suspend node has the following structure:

    config = {
  "emailTemplateName" : "registration",
  "emailAttribute" : "mail",
  "emailSuspendMessage" : {
    "en" : "An email has been sent to the address you entered. Click the link in that email to proceed."
  },
  "objectLookup" : false,
  "identityAttribute" : "userName"
};
    json

    A Configuration Provider node script can use either the next-generation or legacy script engine. It has access to all the common bindings available for its script type. You can use these to help you set the values of the configuration properties.

    Refer to the example for a script that uses shared state data to set the node configuration.

  2. Save your script, and select it from the list when you configure the node’s Script property.

Configuration

Property Usage

Script

Select the script you created for this node. The list displays legacy and next-generation Configuration Provider scripts.

Click to open a script editor and create a new script.

Node Type

Select the type of node to imitate. The list is restricted to node types with outcomes that are fixed or variable based on predefined values.

Script Inputs

Optionally, limit the shared state data properties in the shared state input to the selected Script.

Default: * (Any available shared state property)

Outputs

The outputs match those of the imitated node.

Outcomes

The Configuration Provider node inherits the outcomes of its configured Node Type. Connect these as you would the outcomes of the imitated node.

Nodes with a variable set of outcomes inherit all the possible outcomes even if runtime configuration makes them unreachable. Connect these outcomes to the Failure node.

This node also has a Configuration failure outcome. The Configuration failure outcome arises when:

  • The Configuration Provider node failed to build the configuration map.

  • The configuration map is missing required values.

  • The configuration map is invalid.

Errors

In addition to the messages from the imitated node, this node can log the following:

Warnings

  • Failed to collect inputs of contained node: node-type

    A required input property was missing.

  • Failed to get outcome provider for node type.

    The Node Type outcomes were missing.

Errors

  • Failed to configure node: node-type

    This corresponds to the Configuration failure outcome.

To troubleshoot HTTP errors this node causes, refer to the Errors section of the imitated node.

Examples

In the following example, the Configuration Provider node imitates a Message node.

The Configuration Provider settings are the following:

Script

A script to configure a Message node dynamically.

The script assigns values to the required properties, accessing the username from shared state data to set the message:

config = {
    "message": {"en-GB": `Hi ${nodeState.get("username")}. Please confirm you are over 18.`},
    "messageYes": {"en-GB": "Confirm"},
    "messageNo": {"en-GB": "Deny"},
    "stateField" : null
}
json
Node Type

Message Node

Script Inputs

username

The default, *, also works because username is one of the available shared state properties.

The Configuration Provider node is part of a journey where the user enters their username and password before getting the message screen, so their username is in the shared state data. Notice the outcomes of the node include those of the Message node (True, False):

Journey with a [.label]#Configuration Provider# node

When the journey reaches the Configuration Provider node, the script for the node retrieves the username and dynamically configures the node. The Configuration Provider node, imitating a Message node, prompts the user with the message:

A [.label]#Configuration Provider# node imitating a [.label]#Message# node

  • When the user clicks Confirm, the journey continues to the Increment Login Count node.

  • When the user clicks Deny, the journey continues to the Failure node.

  • If the configuration process fails, the node triggers the Configuration failure outcome and the journey continues to the Failure node. In this case, you can find the reason for the failure in the logs.