Oracle® Fusion Middleware
Part 27. Utility Filters

You can use the Locate XML Nodes filter to select a number of nodes from an XML message. The selected nodes are stored in a message attribute, which is typically used by a Signature or XML Encryption filter later in a policy.

The primary use of the Locate XML Nodes filter is when a series of policies is auto-generated by importing a Web services Description Language (WSDL) file that contains WS-Policy assertions. For example, because there may be many different WS-Policy assertions that describe elements in the message that must be signed, the Locate XML Nodes filter can be used to build up the node list of elements. Eventually, this node list is passed into the Sign Message filter (using a message attribute) so that a single Signature can be created that covers all the relevant parts.

However, you can also use this filter in similar cases where the message content that must be signed depends on content of the message. For example, a given policy runs a number of XPath expressions on a message where each XPath expression checks for a particular element. If that element is found, it can be marked as an element to be signed/encrypted by selecting that element in the Locate XML Nodes filter. This means that only a single Signature/XML Encryption filter must be configured, with each path feeding back into this filter and passing in the message attribute that contains the nodes set for each specific case.

As explained earlier, nodes can be selected using any combination of Node Locations, XPaths, and/or Message Attributes. The following sections explain how to use each different mechanism and how to store the selected nodes in a message attribute.

Node Locations:

The simplest way to select nodes is using the pre-configured elements listed in the table on the Node Locations tab. The table is pre-populated with elements that are typically found in secured SOAP messages, including, the SOAP Body, WSSE Security Header, WS-Addressing headers, SAML Assertions, WS UsernameToken, and so on.

The elements selected here are found by traversing the SOAP message as a DOM and finding the element name with the correct namespace and with the selected index position (for example, the first Signature element from the http://www.w3.org/2000/09/xmldsig# namespace).

You can select the checkbox in the Name column of the table to select the corresponding node. You can select any number of Node Locations in this manner.

If you want to locate an element that is not already present in the table, you can add a new Node Location by clicking the Add button below the table. In the Locate XML Nodes dialog, enter the name of the element, its namespace, and its position in the message using the Element Name, Namespace, and Index fields.

If you wish to select this node for encryption purposes, you must select an appropriate Encryption Type. For example, WS-Security Policy mandates that when encrypting the SOAP Body that only its contents are encrypted and not the SOAP Body element itself. This means that the <xenc:EncryptedData> is inserted as a direct child of the SOAP Body element. In this case, you should select the Encrypt Node Content radio button.

However, in most other cases, it is typically the entire node that gets encrypted. For example, when encrypting a <wsse:UsernameToken>, the entire node should be encrypted. In this case, the <EncryptedData> element replaces the <UsernameToken> element. To encrypt the entire node in this manner, select the Encrypt Node radio button.

XPath Expressions:

In cases where you want to select nodes that exist under a more complicated element hierarchy, it may be necessary to use an XPath expression to locate the required nodes. The XPaths table is pre-populated with a number of XPath expressions to locate SOAP elements and common security elements, including SAML Assertions and SAMLP Responses.

To select an existing XPath expression, you can select the checkbox next to the Name of the appropriate XPath expression. You can select any number of XPath expressions in this manner.

To add a new XPath expression, click the Add button. You must enter a name for the XPath expression in the Name field. You can then enter the XPath expression in the XPath Expression field. For more information on configuring this dialog, see the Configuring XPath Expressions topic.

If you wish to select this node for encryption purposes, you must select an appropriate Encryption Type. For example, WS-Security Policy mandates that when encrypting the SOAP Body that only its contents are encrypted and not the SOAP Body element itself. This means that the <xenc:EncryptedData> is inserted as a direct child of the SOAP Body element. In this case, you should select the Encrypt Node Content radio button.

However, in most other cases, it is typically the entire node that gets encrypted. For example, when encrypting a <wsse:UsernameToken>, the entire node should be encrypted. In this case, the <EncryptedData> element replaces the <UsernameToken> element. To encrypt the entire node in this manner, select the Encrypt Node radio button.

Message Attribute:

Finally, you can also retrieve nodes that have been previously stored in a named message attribute. In such cases, another filter extracts nodes from the message and stores them in a named message attribute (for example, node.list). The Locate XML Nodes filter can then extract these nodes and store them in the message attribute configured in the Message Attribute Name field below.

Extract nodes from Selector Expression:

Specify whether to extract nodes from a specified selector expression (for example, ${node.list}). This setting is not selected by default. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store (KPS), or environment variable). For more details, see Selecting configuration values at runtime.

Message Attribute in which to place list of nodes:

At runtime, the Locate XML Nodes filter locates and extracts the selected nodes from the message. It then stores them in the specified message attribute. For example, if you wish to sign the selected nodes, it would make sense to store the nodes in a message attribute called sign.nodeList, which would then be specified in the Sign Message filter. Alternatively, if you wish to encrypt the selected nodes, you could store the nodes in the encrypt.nodeList message attribute, which would then be specified in the XML Encryption Properties filter. The Message Attribute Name setting defaults to the node.list attribute.

Finally, you must specify whether you want the selected nodes to Overwrite any nodes that may already exist in the specified attribute, or if you want to Append to any existing nodes. You can also decide to Reset the contents of the message attribute. Select the appropriate radio button depending on your requirements.