Locate XML nodes

Overview

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 might be many different WS-Policy assertions that describe elements in the message that must be signed, you can use the Locate XML Nodes filter 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 or encrypted by selecting that element in the Locate XML Nodes filter. This means that only a single signature or 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.

Configuration

As explained earlier, nodes can be selected using any combination of node locations, XPaths, 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 preconfigured 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 check box in the Name column of the table to select the corresponding node. You can select any number of node locations in this manner.

To locate an element that is not already present in the table, click the Add button below the table to add a new node location. 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.

To select this node for encryption purposes, 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 option.

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 option.

XPath expressions

To select nodes that exist under a more complicated element hierarchy, it might 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 check box 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 and enter the XPath expression in the XPath Expression field. For more information on configuring this dialog, see Configure XPath expressions in the API Gateway Policy Developer Guide.

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 option.

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 option.

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.

Extract nodes from Selector Expression enables you to 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 Select configuration values at runtime in the API Gateway Policy Developer Guide.

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, 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, 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 the selected nodes should Overwrite any nodes that might already exist in the specified attribute, or if they should Append to any existing nodes. You can also decide to Reset the contents of the message attribute. Select the appropriate option depending on your requirements.

Related Links