Rewriting SOAPAction headers with IBM DataPower Gateway Appliances

Content

Introduction

IBM DataPower Gateway is often used to transform or adapt a back-end SOAP/HTTP Web service to a different Web service interface. In such scenarios, the mediation logic almost always transforms the SOAP messages. But transforming the SOAPAction header is usually forgotten, which leads to problems later during integration testing. Fortunately, DataPower is flexible enough to enable you to easily transform the SOAPAction header, and this article will show you four different ways to do that.

Background

The SOAPAction header is defined as part Web Service Description Language (WSDL) 1.1 specification. Originally, the purpose of this header was to identify the intent of the request -- the operation to be invoked on the back end. Later as part of WS-I Basic Profile V1.1, it was recommended not to depend on it, but some service providers continued to do so. Therefore it is always better when building a mediation layer in front of a SOAP/HTTP Web service to make sure that you correctly rewrite the SOAPAction header as part of your mediation logic.

The soapAction attribute is associated with each operation binding in the WSDL and its value is not necessarily the same as the operation name -- it can be any URI. When the SOAP request is sent over HTTP, an HTTP header named SOAPAction is presented with a value equal to the soapAction attribute of the requested operation, surrounded with double quotes. Listing 1 shows a WSDL snippet with the soapAction attribute defined:

  <wsdl:binding name="MyServiceBinding" type="tns:MyServicePortType">     
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> 
<wsdl:operation name="operation1">              
<soap:operation soapAction="OP1"/>                  
<wsdl:input>                      
<soap:body use="literal"/>                 
</wsdl:input>                 
<wsdl:output>                      
<soap:body use="literal"/>                 
</wsdl:output>             
</wsdl:operation>

When creating a new Web Service Proxy on DataPower, one of the proxy settings is the SOAPAction policy, which is highlighted in Figure 1 below and has three options:

• Lax: Default option. It mandates the SOAPAction header to contain the exact value of the soapAction attribute in the WSDL but it also allows empty SOAPAction values.
• Off: No check will be performed on the SOAPAction header.
• Strict: The SOAPAction header must match the soapAction attribute in the WSDL, or else the request is not permitted.

Figure 1. SOAPAction policy in the proxy settings

This policy affects the service that is exposed by DataPower, not the back-end Web service. The service configuration needs to transform the incoming SOAPAction HTTP header to the value expected by the back-end Web service. The following sections describe different ways to do that.

Solution 1. Using an XSL file

In this solution, you develop an XSL file that uses an extension element called set-http-request-header. This element has two attributes:

• Name: Header name that you want to set. In this use case, set it to SOAPAction.
• Value: Header value to set. It should be the SOAPAction header value for the back-end service.

Here is an example of using this element:

  <?xml version="1.0" encoding="UTF-8"?>  
<xsl:stylesheet version="1.0"      
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      
xmlns:dp="http://www.datapower.com/extensions"      
xmlns:dpconfig="http://www.datapower.com/param/config"      
extension-element-prefixes="dp"      
exclude-result-prefixes="dp dpconfig">         

<xsl:param name="dpconfig:SOAPAction" />     
<dp:param name="dpconfig:SOAPAction">          
<display>SOAPAction header value</display>      
</dp:param>         
<xsl:template match="/">         
<xsl:copy-of select="/*"/>        
<dp:set-http-request-header name="'SOAPAction'"  value="$dpconfig:SOAPAction"/>      
</xsl:template>    
</xsl:stylesheet>

The XSL file above takes the SOAPAction header value as a parameter, so when you configure the transform action, open the Advanced tab, set the SOAPAction header value field, and click Save:

Figure 2. Configuring the SOAPAction header value parameter in the Transform action

This action should be configured in the request rule of your processing policy. In this solution, you may not need to use the exact code shown in Listing 2 above. Specially, if you are going to use one XSL file to set the SOAPAction header depending on which Web service operation is being invoked.

Solution 2. Using a header rewrite action

In this solution, rewrite the SOAPAction header using one of the advanced actions called Header Rewrite. When configuring the request processing rule:

1. Drag the Advanced action icon:

   

2. Select Header Rewrite from the list.
3. Create a new URL Rewrite Policy.
4. Type a name for the policy and select URL Rewrite Direction to Request:

   Figure 3. Configuring header rewrite policy 1

   

5. Open the URL Rewrite Rule tab and click Add. Fill in the values shown in Figure 4 below and then click Apply:

   Figure 4. Adding a new URL rewrite rule

   

   • URL Rewrite Type: The type of URL rewrite rule. header-rewrite indicates that a request header will be rewritten.
   • Match Expression: Perl-compatible regular expression that matches against the value of the header. In Figure 4, .* means that the rule matches any value for the SOAPAction Header.
   • Input Replace Expression: Value of the header after the rule is executed.
6. Apply and save all changes.

In this solution, you can create multiple URL-rewrite rules, each one responsible for transforming the SOAPAction header for a different operation. Obviously, you will need to change the match expression for the rules to be more specific that the one described in Figure 4 above.

Solution 3. Using Web service proxy header injection

In this solution, you don't touch the processing policy. Instead, you configure the SOAPAction header rewrite on the Web service proxy level. Use the following steps:

1. Open you Web service proxy from the Control Panel home page.
2. Open the Headers/Params Tab.
3. Under Header Injection Parameters, click Add.
4. Fill in the values as shown below and click Submit:

   Figure 5. Configuring SOAPAction header injection on a Web service proxy

   

   • Direction indicates when the header should be injected.
   • Back means that the header will be injected when the message travels from the Web service proxy to the back-end service.
5. Click Apply and save the changes.

Solution 4. Using the user agent

In this solution you don't touch the Web service proxy configuration, but you configure the user agent object of the XML manager, which is referenced by the Web service proxy.

1. Open the User Agent object. If you don't know the user agent associated with your Web service proxy, open the Proxy Settings Tab of your Web service proxy, click the … button next to XML Manager, and then click the … button next to the User Agent Configuration.
2. Open the Soap-Action Policy tab.
3. Click Add.
4. In the URL Matching Expression field, type the back-end service URL. In the SOAP Action field, type the SOAPAction header value.
5. Click Apply and save the changes.

Modifying the user agent or the XML manager named default is not recommended because these are used for new services and some existing services may be using them as well. Instead, create a new user agent object and/or an XML manager object before applying the steps above to it.

Conclusion

This article explained several ways to rewrite the SOAPAction header using DataPower. It explained that the SOAPAction header is associated with a Web service operation, and not a Web service interface. Solution 3 inserts the SOAPAction headers into all requests passing through the Web service proxy to the back end. Therefore, if the WSDL that is exposed by the Web service proxy has multiple operations, this solution may not be the best fit. A similar rationale applies to Solution 4 -- if the service back end exposes more than one operation, it may not be the best fit.

Solution 1 and Solution 2 are flexible and don't suffer from SOAPAction header scope like Solutions 3 and 4. Solution 2 is handled through the Web configuration, and doesn't require any XSLT development. However, if you are not comfortable with regular expressions, then Solution 1 is probably a better fit.

Acknowledgements

The author would like to thank Karim Ouda and Mohab El Hilaly for their work reviewing this article.

Related topics