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 1st 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:
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.
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.
|