Building XPath expressions for WS-Security

JAX-RPC and JAX-WS WS-Security configurations use XML-based SOAP messages to exchange information between applications. You can use an XPath expression to select specific elements in a SOAP message to sign or encrypt.

Before you begin

If you want to sign or encrypt elements in a Simple Object Access Protocol (SOAP) message, you can use XPath expressions to select the specific elements in the message. SOAP 1.1 and SOAP 1.2 messages differ in format and therefore require separate XPath expressions to select elements from each version of the message. The JAX-WS runtime environment supports both SOAP 1.1 and SOAP 1.2., so you must add two XPath expressions to the WS-Security policies for each element that you want to select: one for SOAP 1.1, and one for SOAP 1.2. The JAX-RPC runtime environment supports only SOAP 1.1, so you must add only the SOAP 1.1 version of the XPath expression to the WS-Security policies.

The differences in the format of SOAP 1.1 and SOAP 1.2 messages are highlighted in the following scenario of selecting the Timestamp element from SOAP messages in a JAX-WS WS-Security configuration.

The following example shows a SOAP 1.1 message with a Timestamp element.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsu:Timestamp wsu:Id="Timestamp-16" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsu:Created>2012-01-11T12:55:41.781Z</wsu:Created>
        <wsu:Expires>2012-01-11T15:42:21.781Z</wsu:Expires>
      </wsu:Timestamp>
    </wsse:Security>
  </soapenv:Header>
</soapenv:Envelope>

The following example shows a SOAP 1.2 message with a Timestamp element.

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
  <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsu:Timestamp u:Id="uuid-169b0950-217e-48af-9057-ea832e0c7e19-14" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsu:Created>2009-09-08T14:08:36.224Z</wsu:Created>
        <wsu:Expires>2009-09-08T14:13:36.224Z</wsu:Expires>
      </wsu:Timestamp>
    </wsse:Security>
  </soapenv:Header>
</soapenv:Envelope>

The XPath expressions that select SOAP message elements are in the WS-Security default policies that contain configuration information for XML Digital Signature. In a JAX-WS WS-Security configuration, the XPath expressions appear in pairs, with one XPath expression for each supported version of SOAP.

The following example shows the XPath expressions that select the Timestamp element from the SOAP 1.1 and SOAP 1.2 messages in the previous examples. The first XPath expression selects Timestamp from the SOAP 1.1 message, and the second XPath expression selects Timestamp from the SOAP 1.2 message.

/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Envelope']
/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Header']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd' and local-name()='Timestamp']

/*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Envelope']
/*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Header']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd' and local-name()='Timestamp']

The first two lines of the XPath expressions for each version are different, and the last two lines of the XPath expressions are the same. The difference between the two XPath expressions is the namespace in the Envelope and Header elements. The namespaces in the XPath expressions correspond to the namespaces in the SOAP 1.1 and SOAP 1.2 messages.

About this task

This task describes how to build XPath expressions that are used to select an element to sign or encrypt in WS-Security. JAX-WS security configurations require separate XPath expressions for both SOAP 1.1 and SOAP 1.2, while JAX-RPC security configurations require XPath expressions only for SOAP 1.1.

If you want to select a SOAP message element that is commonly used in WS-Security, see option 1 to build XPath expressions using pre-built code segments. Otherwise, proceed to option 2 to learn how to build custom XPath expressions for other elements.

Avoid trouble Avoid trouble: The XPath expression examples in this task are shown across multiple lines for formatting and clarity. When adding your completed XPath expressions into WS-Security, you must enter the complete XPath expression as a single line.gotcha

Procedure

  1. Build a common XPath expression using pre-built code segments.
    1. Build the part of the XPath expression that points to the SOAP Security header.
      • SOAP 1.1:
        /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Envelope']
        /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Header']
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
      • SOAP 1.2:
        /*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Envelope']
        /*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Header']
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
    2. Add the part of the XPath expression that corresponds to the element that you want to sign or encrypt. The XPath expression lines for commonly used elements are shown in the following list.
      • UsernameToken
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='UsernameToken']
      • BinarySecurityToken (LTPA, X.509, Kerberos, and so on.)
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and localname()='BinarySecurityToken']
      • SAML 1.1 Assertion (encryption only)
        /*[namespace-uri()='urn:oasis:names:tc:SAML:1.0:assertion' and local-name()='Assertion']
      • SAML 2.0 Assertion (encryption only)
        /*[namespace-uri()='urn:oasis:names:tc:SAML:2.0:assertion' and local-name()='Assertion'] 
      • SecurityTokenReference in the Security header (for STR-Transform)
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' 
        and local-name()='SecurityTokenReference'] 
      • SecurityTokenReference within a Signature element
        /*[namespace-uri()='http://www.w3.org/2000/09/xmldsig#' and local-name()='Signature']
        /*[namespace-uri()='http://www.w3.org/2000/09/xmldsig#' and local-name()='KeyInfo']
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='SecurityTokenReference']
      • Timestamp
        /*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd' and local-name()='Timestamp']
      • Signature (encryption only)
        /*[namespace-uri()='http://www.w3.org/2000/09/xmldsig#' and local-name()='Signature']
  2. Build a custom XPath expression.
    1. Locate the element you want to select within the structure of the SOAP message.

      For example, the following SOAP message contains the element CreditCardNumber.

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Header>
          <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <ns1:myToken xmlns:ns1="http://token/space" value="tokenValue"/>
          </wsse:Security>
        </soapenv:Header>
        <soapenv:Body>
          <ns2:CreditCardNumber xmlns:ns2="http://bank/space" value="1234"/>
        </soapenv:Body>
      </soapenv:Envelope>

      If you want to select CreditCardNumber, isolate only the elements of the SOAP message that surround it. The following example shows the structure of the SOAP message that is relevant to selecting CreditCardNumber.

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
          <ns2:CreditCardNumber xmlns:ns2="http://bank/space" value="1234"/>
        </soapenv:Body>
      </soapenv:Envelope>
    2. Write one XPath segment for each element in the SOAP message structure that contains the target element. Each XPath segment must include the namespace and local name of its corresponding element put into the following format:
      /*[namespace-uri()='http://namespace/url' and local-name()='ElementName']

      For example, the following XPath segment corresponds to the Envelope element from the example in the previous step.

      /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Envelope']

      If the element does not contain a namespace, it inherits the namespace of the element that contains it. For example, the Body element uses the namespace from the Envelope element.

    3. Combine the XPath segments into one complete expression. The segments should be ordered from the outermost element to the innermost element, which is the element that you are selecting.

      The following example shows the complete XPath expression that selects the CreditCardNumber element from the example in the first step.

      /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Envelope']
      /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' and local-name()='Body']
      /*[namespace-uri()='http://bank/space' and local-name()='CreditCardNumber']

Results

You built an XPath expression that selects an element of a SOAP 1.1 or SOAP 1.2 message header.

Example

The following example shows a complete SOAP 1.2 XPath expression that selects a UsernameToken.
/*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Envelope']
/*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' and local-name()='Header']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='Security']
/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' and local-name()='UsernameToken']

What to do next

Enter the complete XPath expression into the WS-Security policy configuration as a single line of text.
Task topic    

Terms and conditions for information centers | Feedback

Last updated: April 20, 2014 08:46 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_wssec_xpath
File name: twbs_wssec_xpath.html