PingAM 7.5.0

Request Header node

The Request Header node lets you insert values from request headers into configurable node state properties. This lets you customize journeys based on the request header values.

Compatibility

Product Compatible?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node takes its inputs from one or more request headers and maps these values to properties in the node state. For multi-valued headers, the node delimits headers with a comma (,) and assigns the value to the node state property as a comma-delimited list.

The node doesn’t read input from the state.

The node has no required predecessor nodes.

Dependencies

None.

Configuration

Property Usage

Allowed headers

List the header names the node can obtain from the URL and map them to a property in the node state:

  1. Click Add.

  2. In the Key field, enter the query parameter name.

  3. In the Value field, enter the node state property that will hold the value of this request header.

    This field sets an allowlist of headers the node can pull into the node state. Exercise caution when you create this list to avoid injecting harmful data into the node state.

If a provided request header isn’t in this list, the node ignores it.

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Allowed headers to be delimited

The allowed headers that can take multiple values and whose values you want to store in the node state in a comma-delimited list; for example, ["yellow", "green", "red"].

Enter the header name in the Add value field and click Add.

If you don’t delimit the values of a multi-valued header, the node stores the values in the node state as a single string value; for example, ["yellow, green, red"] .

To edit an entry, click its pencil icon ().

To remove an entry, click its delete icon ().

Outputs

  • If the Allowed headers setting has one or more values, the node adds the values of the listed request headers to the corresponding properties in the node state.

  • If the Allowed headers to be delimited setting has a value but that header isn’t provided in the request, the node sets an empty list ([]) in the corresponding node state property.

  • If an allowed header is also listed in the Allowed headers to be delimited, the node sets the values of that header in the node state as a comma-delimited list.

  • The node performs no decoding or sanitization on the header value. It simply passes the value into the node state as a string.

Values stored in the node state can override values in the authentication journey.

Take special care when you configure this node so that you don’t unintentionally override parameters such as usernames and passwords.

The output of this node isn’t under the control of the node itself. Encode sensitive values appropriately, either at node output, or before the values are used later in the journey.

Outcomes

Single outcome that passes an updated node state to the next node in the journey.

Errors

  • No headers configured – this node is redundant

    The node logs this error if you include it in a journey but don’t configure any Allowed headers.

  • Cannot delimit header if it is not configured as a header to be stored in node state

    The node logs this error if you add a header to the list of Allowed headers to be delimited but not to the list of Allowed headers.

Examples

Use the Request Header node to customize a journey based on the values of specific request headers. The following scenarios illustrate how this node might be used:

Customized branding

An organization has several brands that use the same journey. Use this node to customize the brand the user sees, based on the request header.

Consider the following authentication journey:

Authentication journey using Request Header node

  1. The configuration of the Request Header node maps the brand header to a property in the node state named stateBrand

    Request Header node in a login flow

  2. The REST request to access the journey includes one of the following headers:

    • --header "brand: yellow"

    • --header "brand: red"

    • --header "brand: regular"

  3. The Request Header node obtains the value of the brand header and sets that value in the stateBrand property in the node state; for example, stateBrand=yellow

  4. The journey progresses to the scripted decision node that includes the following script:

    var brand = JSON.parse(nodeState.get('stateBrand'));

if (brand.indexOf("yellow") >= 0) {
  outcome = "yellow";
} else if (brand.indexOf("red") >= 0) {
  outcome = "red";
} else {
  outcome = "regular";
}

  5. The script routes the journey to one of three outcomes; yellow, red, or regular, depending on the value of the stateBrand property.

  6. The outcomes direct the user to a custom branded Login journey configured in an Inner Tree Evaluator node; for example:

    Inner tree evaluator node in query parameter journey

  7. Each Inner Tree Evaluator node routes the end user to a login journey that uses a custom brand.

Redirection from an external system

An external system redirects a user to this authentication journey. The external system must share information about the user with the journey. Use the Request Header node to obtain the relevant request headers and inform the journey of their values.