PingAuthorize

Processors

Use value processing on responses returned from attributes or services to transform the resolved value.

Add a value processor when you create or edit an attribute or service. Alternatively, you can define a value processor to reference by name by going to Trust Framework → Processors.

The PingAuthorize Policy Editor supports these value processors:

  • Collection filter

  • Collection transform

  • JSON Path

  • X Path

  • Spring Expression Language (SpEL)

  • Named

You can combine these processors to form a chain of processors.

All processors have a type that indicates what the output data type should be after applying the expression.

You can reorder collapsed value processors by dragging the handles on the left. To reorder using the keyboard, press Tab to go to the processor, press Enter to select the processor, press the up arrow or down arrow to go to the desired location, and press Enter to drop the processor in the new location.

Collection filter

When the data being processed is a collection, you can set a filter to examine each item in the collection and keep only the items that satisfy some condition. A collection filter uses a value processor to yield a true or false for each item in the collection. When true, the original item goes in the resulting collection; when false, it is omitted.

Each item in the collection can optionally be preprocessed by one or more value processors before applying the condition. For example, suppose we received a JSON collection from a service invocation and we want to filter the items by the score field. The input data might look like the following lines:

[
    { "name": "Alice", "role": "Sender",   "score": 72 },
    { "name": "Bob",   "role": "Receiver", "score": 36 },
    { "name": "Carol", "role": "Observer", "score": 47 },
    { "name": "Dave",  "role": "Attacker", "score": 99 }
]

A collection filter processor could achieve this by using a JSON Path preprocessor to extract the score.

$.score

The following SpEL condition yields a true or false decision for each item.

#this > 50

Each list item is, in turn, passed through the preprocessing and the condition. The first item has a score of 72, which is greater than 50, so the condition yields true and the item is retained for the result collection. The second and third items have scores less than 50, so the condition yields false and these items are omitted. The final item also has a score higher than 50 and is retained. The result of the collection filter is:

[
    { "name": "Alice", "role": "Sender",   "score": 72 },
    { "name": "Dave",  "role": "Attacker", "score": 99 }
]

The values produced by the preprocessing and condition are only used to determine inclusion. The final result of a collection filter consists of those original collection items that satisfied the predicate after preprocessing. The following image shows the collection filter in the GUI. Screen capture of a collection filter with a processor to extract the score of each item and check whether it is greater than 50

If the condition or preprocessing produces an error for any item in the input collection (for example, if a score field is missing or is not a number in the source data), the whole collection filter is considered to have failed.

Collection transform

When the data being processed is a collection, you can set a transform to apply a processor or a sequence of processors to each item in the collection.

Assume we have the following input collection:

[
    { "name": "Alice", "role": "Sender",   "score": 72 },
    { "name": "Bob",   "role": "Receiver", "score": 36 },
    { "name": "Carol", "role": "Observer", "score": 47 },
    { "name": "Dave",  "role": "Attacker", "score": 99 }
]

The following JSON Path processor extracts the name field for each item:

$.name

The following SpEL processor converts each name to upper case:

#this.toUpperCase()

Then the resulting collection consists of just the extracted names converted to upper case, preserving the order of the original collection.

[ "ALICE", "BOB", "CAROL", "DAVE" ]

The following image shows the collection transform in the GUI. Screen capture showing a collection transform that extract names and converts them to upper case using two processors

If the item processor produces an error for any item, the overall collection transform processor produces an error.

JSON Path

With JSON Path, you can extract data from JSON objects. For example, assume we have a service that resolves to the following JSON:

{
   "name": "Joe Bloggs",
   "requestedItems": [
      {
         "id": "b5f963fa-111e-49ff-994b-b89a20a2c1d5",
         "price": 125.00
      },
      {
         "id": "84e204dd-44f5-4a84-8e58-972c2a9c80b4",
         "price": 299.99
      }
   ]
}

To extract the price fields of all requested items, we set the value processor to JSON Path with the expression $.requestedItems[*].price.

Learn more about JSON Path expressions at https://github.com/json-path/JsonPath.

X Path

XPath is the XML-equivalent of JSON Path and follows a very similar syntax. Learn more about XPath expressions in the XPath tutorial on w3schools.com.

The Policy Editor only supports the use of XPath 1.0. Functions added in later versions are not available.

SpEL (Spring Expression Language)

With SpEL, you can perform more complicated data processing. Expressions are applied directly to the resolved value. For example, assume you want to search for a substring that matches the following regular expression:

\[[0-9]*\.[0-9]\]

Set the processor to SpEL and set the expression to the following text:

matches(\[[0-9]*\.[0-9]\])

Use curly brackets to interpolate attributes directly into the SpEL expression, which can be useful if you want to combine multiple attribute values into a single value. Learn more in Attribute interpolation.

{{Customer.Age}} - {{State.Drinking Age}} >= 0

You can concatenate interpolated attributes with strings in SpEL expressions. In the following example, a SpEL expression is used to dynamically concatenate a string with a user’s account number to create a transaction verification message:

"Account " + {{Customer.AccountNumber}} + " has been charged."

Be careful not to wrap an interpolated attribute with quotes.

Learn more about SpEL in the Spring Framework documentation.

Learn more about the Java classes available for SpEL processing in Configuring SpEL Java classes for value processing.

Named

Use named value processors to create reusable value processing logic.

Extracting this logic into reusable components helps abstract some of the complexity when you define an attribute or a service. Also, it reduces repetition.

You can still create inline value processors that co-exist with named value processors.

To define a named value processor that you can reference, go to Trust Framework → Processors.

Chained value processors

You can chain processors together to combine data preprocessing steps.

For example, you can extract data using JSON Path and then apply a SpEL processor to the extracted data. Suppose you have a service response that resolves to the following JSON:

{
   "name": "Joe Bloggs",
   "city": "London",
   "country": "UK"
}

Suppose you want to extract the country data and transform the value to United Kingdom, whenever the current value is UK. You would add a JSON Path processor to extract the country value, followed by a SpEL expression to transform the value:

Screen capture of a chain of two value processors, one that extracts the country value and one that transforms it under a specific condition using a SpEL expression

You can make a chained processor reusable by creating it as a named processor. That way, you can implement even more complex processing by using named processors as the building blocks.