Processing SOAP Messages
This chapter provides an overview of SOAP and WS-Security features. It covers these topics:
•Introducing SOAP and WS-Security Features
•Enabling SOAP Header Processing
•Configuring SOAP Namespaces
•Handling Large Messages
•Processing SOAP Attachments
•Dynamic Service Routing with WS-Addressing
Introducing SOAP and WS-Security Features
The ACE XML Gateway provides extensive support for the SOAP protocol and the Web Service (WS) standards. SOAP is a message-transfer protocol for invoking remote procedures by sending XML messages over commonly available transports, most often by HTTP.
SOAP is defined by W3C recommendations, W3C Note 08 May 2000 (http://www.w3.org/TR/SOAP/) and W3C Recommendation 24 June 2003 (http://www.w3.org/TR/soap12-part0/).
The ACE XML Gateway and Manager include tools and capabilities that significantly ease the task of implementing a secure, reliable service-oriented system. This chapter provides an overview of support for SOAP and WS-Security technologies and how they can be used to deploy secure network services.
SOAP Version and Feature Support
The ACE XML Gateway supports SOAP versions 1.1 and 1.2. Note the following points regarding the support of SOAP and Web Service (WS) specifications:
•WS-Security 1.0 is supported, along with all four inter-operability scenarios described by the OASIS document Web Services Security: SAML Interop 1 Scenarios.
•The ACE XML Gateway supports SOAP Versioning, and reports VersionMismatch faults when a message version is incorrect. The ACE XML Gateway does not, however, support the Upgrade message.
•It supports the use of SOAP header endpoint targeting through the use of roles, which enable messages to specify who should process which headers, and relaying, which enables messages to specify whether particular headers should be passed along to subsequent receivers.
•The ACE XML Gateway supports SOAP 1.2-style Content-Type declarations (
application/soap+xml), including the optional
action parameter. It also supports SOAP 1.2-style Fault elements.
•While the ACE XML Gateway can validate and generate WS-Security UsernameToken elements, it does not support nonce caching, HMAC keys, or XRML. Also, it supports the SAML profile and X.509 certificates in SOAP messages, but does not support PKIPath.
SOAP Message Format
A SOAP message has an envelope (required), SOAP headers (optional), and SOAP body (required). The SOAP envelope is an XML element whose name in the SOAP Envelope namespace is "Envelope." The Envelope element may contain a SOAP header (that is, an element whose name in the SOAP Envelope namespace is "Header") and it must contain a SOAP Body (that is, an element whose name in the SOAP Envelope namespace is "Body").
SOAP messages can conform to either of two styles:
•SOAP RPC style is more rigid, requiring that parameters to a SOAP routine be encoded sequentially in the body of the message in a specified format.
•SOAP Document style is more flexible, permitting any valid XML document as the body of the message. The presumption is that the structure and validity of individual SOAP Document messages are validated by XML Schema.
In most cases, users of SOAP services do not need to know the details of the SOAP message formats. It's sufficient to know which style and encoding a client or service expects and what headers are expected.
SOAP and WS-Security
SOAP itself makes no guarantees about the security or reliability of SOAP messages. To address these issues, the Organization for the Advancement of Structured Information Standards (OASIS) developed the Web Services Security (WS-Security) and Web Services Utility (WS-Utility) standards. These standards specify extensions to SOAP intended to improve security and reliability.
The SOAP features most often used to protect networks are:
1. Digital signatures—SOAP messages can transport XML elements together with digital signatures; the ACE XML Gateway can use the signatures to validate the signed elements.
2. Content-level encryption—SOAP messages may transport all or part of their contents as encrypted elements.
3. WS-Security username and password tokens—the WS-Security standard provides a method for securely transporting username and password information that SOAP messages can use to authenticate themselves.
4. SOAP timestamps—a SOAP message can be marked with a timestamp that indicates the message creation time, expiration time, and when received by a particular intermediary.
Web Service features are usually conveyed in the message as SOAP headers. The ACE XML Gateway can process SOAP headers by validating and removing them from the message or by transforming them as needed by the backend systems. Under some circumstances, however, you may need certain SOAP headers to be accepted and passed-through to the destination unchanged.
This chapter describes how to set up and use SOAP and Web Service features.
Enabling SOAP Header Processing
SOAP headers are elements of SOAP messages that contain special processing instructions or other types of information applicable to the message. SOAP header elements are defined by specifications such as WS-Security and WS-Utility, and may contain a timestamp, XML signature, or WSS UsernameToken credential.
Note In addition to formally defined header types, SOAP messages can carry custom SOAP headers. The ACE XML Manager interface differentiates formally specified headers and custom headers with the terms "known headers" and "user-specified headers," respectively.
To have the ACE XML Gateway process SOAP headers in incoming messages, the SOAP Header processing option needs to be enabled in the virtual service settings. Unless the WSDL used to generate the service definition included SOAP header requirements, this option is disabled by default and SOAP headers are passed through unprocessed.
A WSDL can specify header requirements using the
soap:header element in the input or output element of an operation binding definition. When you import a WSDL with this requirement, SOAP header processing is enabled for those services by default. Also, as indicated in the Advanced Options page for the SOAP header processing settings, a user-specified header is configured for each of the headers required in the WSDL. If the WSDL does not specify headers, you will need to enable header processing directly to have the ACE XML Gateway validate and process SOAP headers.
Enabling header processing directs the ACE XML Gateway to consume SOAP headers in incoming messages. Enabling processing alone doesn't impose requirements for particular headers to be present, but if present, the headers are processed for validity and removed from the outgoing message (unless it is a WS-Addressing header, in which case it is passed through by default).
Note To specify that a SOAP header must be present for the message to be accepted, use the Advanced SOAP Processing settings.
Follow these steps to enable SOAP header processing:
Step 1 While logged in to the web console as an
Administrator user or as a
Privileged user with the
Routing role, click the Virtual Services link in the navigation menu.
Step 2 Click on the name of the virtual service object that handles the SOAP messages for which you want to process headers.
Step 3 In the Incoming Request section, click the Edit link in the SOAP Header Processing pane.
Step 4 Click the Process header elements for SOAP checkbox.
Step 5 From the Role menu, choose the role attribute value of headers for which you want to perform processing.
If you choose a SOAP role, the ACE XML Gateway examines SOAP headers only if they indicate that role. A SOAP role attribute identifies the intended processor of a particular header. If a receiver or an intermediary that relays SOAP messages has a SOAP role assigned to it, and it finds headers in a SOAP message assigned to that role, it processes the header. You can separately configure the SOAP role assigned to each handler. If "no role" is selected, the handler processes only headers that do not have a role attribute.
Step 6 Using the other controls on the page, specify how you want headers to be processed. The WSU Timestamp settings include Timestamp Expires and Timestamp Created and Timestamp Expires values differ by more than. If you enable these option, messages with timestamp properties that do not meet the requirements indicated are rejected. For information on XML Encryption and XML Signature, see Chapter 12, "XML Encryption and XML Signature."
Step 7 When finished, click Save Changes to commit your changes to the working policy.
Advanced SOAP Header Settings
When you turn on SOAP header processing, SOAP headers in the message must be valid. The advanced SOAP header settings let you further require that a header be present. In particular, the settings let you configure how the ACE XML Gateway handles custom headers, WS-Security headers, Timestamp headers, as well as headers in the message that are not described as known or user headers.
For service definitions created as a result of WSDL import, settings for custom headers may be configured automatically based on the content of the WSDL. If the WSDL contains custom SOAP header requirements, the corresponding settings in the header requirements section of the policy are populated to reflect the header requirement. (Also, SOAP header processing is enabled by default as well.)
To open the SOAP header advanced options for a virtual service, click the advanced options link in the SOAP Header Processing pane (if SOAP header processing settings have already been modified) or the Advanced SOAP Header Processing link at the bottom of the SOAP Header Processing page.
The page is organized into these areas: Extra Headers, Known Headers, and User-Specified Headers.
Extra headers are headers that appear in the message that are not specified by name in the policy configuration (as known or user-defined headers). For extra headers, you can specify whether the header is accepted and how the ACE XML Gateway should regard the
mustUnderstand attribute. If a SOAP header has the attribute
MustUnderstand set to true, then SOAP Intermediaries and destination nodes are required to process that header. A SOAP node that receives a message with
MustUnderstand set in one of its headers must reject the message and send back a SOAP Fault response if it doesn't understand the header. The ACE XML Gateway can be configured either to enforce the
MustUnderstand attribute or to ignore it.
If the receiving handler has been assigned a particular SOAP role then it enforces the
MustUnderstand only for headers targeted to that role. Headers targeted to other roles are ignored, regardless of whether they include
For a known SOAP header, you can specify whether a header is optional, required, or forbidden. By default, the headers are optional and processed. Processing means that the ACE XML Gateway consumes the header. For example, a security header with a signature is validated for correctness. You can turn off processing or specify alternative output handling for the header if desired, such as passing the header through to the outgoing message.
By describing custom headers, you can set requirements for those headers. The custom header specification has settings for the namespace of the header, local name, and role.
In addition to defining the header by name, you can specify whether it is required and sent in the outbound message. As with extra headers, you can also configure how the ACE XML Gateway should handle the "must understand" attribute in the header.
Notice that for service definitions generated as a result of WSDL import using a WSDL that includes SOAP header specifications, any custom SOAP headers that were in the WSDL will be automatically specified as User-Specified headers.
Applying XSLT to Headers
An XSLT can be applied to the header before or after the ACE XML Gateway has processed it. When creating an XSLT to be applied to a SOAP header, keep in mind the following points:
•The XSLT is applied relative to the entire SOAP message, not just the header element. Therefore, XPaths in the XSLT need to reference paths in the document relative to the root Envelope document root element, that is,
This allows you to access content in the body of the message, for example, to be output to the header.
•The output of the XSLT is placed in the message as a direct child of the
<soap:Header> element. Therefore, if the result is intended to be a child of the
<wsse:Security> header, then the XSLT should output the
<wsse:Security> header as the root element. This allows you to change the name, namespace, attributes, and so on, of the header if needed.
•The result of the XSLT should be valid XML. It can have any number of child elements, but it should have only a single root note, such as:
If the result has multiple peer root nodes, such as the following example, only the first one will be used:
Configuring SOAP Namespaces
The namespaces the ACE XML Gateway uses for outbound WS-Security and WS-Utility elements in SOAP messages are configurable. The namespace settings appear in the ACE XML Gateway Settings page, which is accessible from the System Management page. The configuration fields are in the SOAP XML Namespace Configuration settings area of the page. Enter the namespaces needed for outbound messages in the fields. After you make this change, the ACE XML Gateway applies the namespaces to WS Security and WS Utility elements of SOAP messages.
Note that the way in which the Gateway applies these values varies depending on whether the incoming request already uses namespaces or not:
•If the incoming request uses namespaces but not the ones you configured, the ACE XML Gateway applies the namespaces you entered to outgoing requests. However, when it gets the corresponding response, it uses the namespaces that were specified by the original request before sending the response to the consumer. In this way, the consumer gets messages that use the same namespace as the original request, while the protected service sees the configured namespace.
•If the incoming request does not specify a namespace, the ACE XML Gateway uses the namespace you specified both in the outgoing request to the protected service and in the outgoing response sent to the consumer.
These rules are applied independently to WS-Security and WS-Utility elements. If, for example, the incoming response specifies a WS-Security namespace but not a WS-Utility namespace, then the consumer sees the WS-Security namespace from the request, but sees the WS-Utility namespace from the ACE XML Manager configuration.
Handling Large Messages
For Flex Path services, the ACE XML Gateway uses special processing techniques that enables it to handle very large messages. The ACE XML Gateway can handle SOAP attachments and HTTP Post XML messages of up to 8GB in size (in the standard hardware configuration).
By default, the Flex Path handles message larger than 10MB as large messages. Large message handling involves special processing techniques that include a stream-oriented processing approach and hard-disk utilization.
Note Reactor handling can process large messages without special handling. Message size in Reactor is limited only by the amount of RAM available for a single process on the appliance (just under 2GB in most hardware configurations). However, there are default threat defense settings applicable to Reactor message processing that limit message size to 10MB by default. You can increase this value on the I/O process advanced settings page.
The types of operations you can apply to large message traffic include schema validation, well-formedness checking, and content screening. The ACE XML Gateway can also verify XML signatures over large message attachments (if the signature is within the SOAP portion of the message, and not within the large attachment). Also, the ACE XML Gateway SDK provides programmatic access to the content of large message attachments, so that you can apply custom validation or processing to the attachment content.
Note Operations that require messages to be processed in-memory, such as XML encryption or decryption or features the require resolution of XPaths, cannot be applied to large message.
Large messages often take the form of SOAP attachments. However, large message support in the ACE XML Gateway applies to other formats as well, such as HTTP Post XML messages. Large XML messages received in response to HTTP Post or HTTP Get are supported as well.
However, processing of SOAP messages in which the SOAP Envelope portion of the message (as opposed to attachment size) is larger than around 30MB is not supported. This restriction applies to SOAP messages and not to other types of messages with XML payloads or SOAP attachments due to the manner in which the ACE XML Gateway validates SOAP messages.
There are no specific steps for enabling Gateway support for large messages. They are supported by default. However, parameters governing large message handling can be tuned based on your requirements. In particular, the message size that induces large message handling can be tuned based on your needs and the type of traffic the ACE XML Gateway will see (the most relevant factor being the likelihood of concurrent large message traffic).
For information on tuning the ACE XML Gateway's handling of large messages, contact your Cisco support representative.
Note You can configure automated compression for large responses delivered to clients that indicate acceptance of GZIP compressed data in their request. The response size threshold at which the Gateway compresses the response is configurable. For more information, see "Compressing Responses" section on page 15-164.
Processing SOAP Attachments
A SOAP message may contain message attachments in the form of MIME- or DIME-encoded data. Attachments are commonly used to transmit data that is not native ASCII, such as images or PDF files.
The ACE XML Gateway can recognize and validate SOAP attachments. Among other tasks, it can:
•Require or forbid attachments in incoming messages.
•Enforce a minimum and maximum size limit upon attachments.
•Compress or decompress attachments.
•Transform attachments from DIME format to MIME, and vice versa.
•Subject attachments to custom handling through SDK extensions.
The ACE XML Gateway can process messages that use MTOM (Message Transmission Optimization Mechanism) message encoding. MTOM, and its related specification XOP (XML-binary Optimized Packaging), is a method for optimizing SOAP Document messages that contain large Base64-encoded portions.
Note For information on SOAP Attachment data types, see W3C note "SOAP Messages with Attachments" (http://www.w3.org/TR/SOAP-attachments).
Processing Incoming SOAP Attachments
You can use the SOAP Attachments/MTOM Handling editor to specify how to handle incoming attachments. In the editor, you can specify whether attachments are required, their size limit, whether to validate their contents, and more.
To configure processing of incoming SOAP attachments:
Step 1 While logged into the web console as an
Administrator user or as a
Privileged user with the
Access Control role, set the active subpolicy to the one that provides the handler or service descriptor to edit.
Step 2 Click the Virtual Services link in the navigation menu.
Step 3 Click on the name of the virtual service object to edit.
Step 4 Click the Edit link in the Incoming SOAP Attachments banner on the information page for the specified handler or service descriptor.
For a basic virtual service, click the edit link next to SOAP Attachment Validation under Request Processing or Response Processing.
Step 5 In the Edit SOAP Attachments page, specify whether to accept SOAP attachments:
•To reject messages that carry SOAP attachments (the default), pick the Reject SOAP messages with attachments item from the menu that appears at the top of the Edit SOAP Attachments page.
•To accept SOAP attachments, pick any of the Accept... items from the menu that appears at the top of the Edit SOAP Attachments page.
The menu displays the item you picked. If you chose to accept SOAP attachments, the editor presents additional controls that you can use to configure global attachment processing and type-specific attachment specifications.
Step 6 To apply content-screening rules to incoming attachments, click the Apply content screening rules to attachments checkbox.
With this option, the ACE XML Gateway applies the content-screening rules enabled in the Content Screening Defaults page to incoming SOAP attachments.
Step 7 To decompress incoming attachments, click the Decompress any compressed attachments checkbox.
If enabled, the ACE XML Gateway decompresses incoming SOAP attachments that are compressed. The ACE XML Gateway can compress or decompress attachments in ZIP or GZIP format.
Step 8 For each kind of SOAP attachment the handler is to accept, create an attachment specification, as follows:
a. Click the Add Another Attachment Specification button.
The Attachments with Content-Type pane appears.
b. Pick an attachment type from the Attachments with Content-Type menu.
To specify an attachment type that does not appear in the menu, choose the custom attachment type and type the name of the attachment type in the field next to the menu. When specifying your custom type, use a format similar to that of the others in the list.
To accept attachments of any type, pick the any unspecified MIME type attachment type.
c. Type into the Require at least fields the minimum and maximum numbers of SOAP attachments an incoming message can have.
To specify unlimited attachments (the default) enter 0 (zero) for both values.
d. Type into the Limit attachment size fields the minimum and maximum permissible size of an individual SOAP attachment, expressed as a number of kilobytes (KB).
You can use the Add Another Attachment Specification button at the bottom of the page to add as many attachment specifications as you need. To remove an attachment specification, click its Remove button.
If the Add Another Attachment Specification button is not available, go to the next step.
Step 9 Click Save Changes to commit your changes to the working policy.
Compressing Outgoing SOAP Attachments
The ACE XML Gateway can compress outgoing message attachments. To compress outgoing SOAP attachments, take the following steps:
Step 1 While logged into the web console as an
Administrator user or as a
Privileged user with the
Access Control role, set the active subpolicy to the one that contains the virtual service, if not already active.
For more information, see "Working with Subpolicies" section on page 26-240.
Step 2 Click the Virtual Services link in the navigation menu.
Step 3 Click on the name of the virtual service object to edit.
The ACE XML Manager web console displays the settings page for the service.
Step 4 Click the Edit link next to Outgoing SOAP Attachments on the information page for the specified handler or service descriptor.
For basic virtual service objects, click the Edit link next to SOAP Attachments Compression under either Request Processing or Response Processing.
Step 5 To have the ACE XML Gateway compress SOAP attachments before sending messages, check the Compress... checkbox in the Edit SOAP Attachments page.
Step 6 Click the Save Changes button to commit your changes to the working policy.
Processing MTOM Messages
In standard SOAP Document messages, binary message content appears within the envelope of the message in Base64-encoded format. With MTOM (Message Transmission Optimization Mechanism) the binary data is processed into raw bytes, which decreases the number of bytes needed to represent the data, and placed outside the envelope as a message attachment.
When it receives an optimized MTOM message, the ACE XML Gateway can reconstitute the data, re-encoding it as Base64 data and inserting it back into the envelope of the message. It can then apply usual SOAP validation and processing measures to the data, such as XML encryption or decryption or XML Signature validation. Responses to a client that sends an MTOM-encoded request are MTOM-encoded.
Instead of processing MTOM content in this manner, the Gateway can simply:
•Block messages with MTOM data
•Pass through MTOM-optimized data
Note While they cannot be mapped to other types of exceptions, MTOM-related exceptions from a backend service are passed through to the client.
By default, messages with attachments and MTOM encoded messages are blocked. To instead permit or process MTOM encoded messages, follow these steps:
Step 1 In the Virtual Services page, open the settings page for the virtual service for which you want to configure MTOM handling.
Step 2 Next to the SOAP Attachments/MTOM Handling heading, click the enable link (or edit, if the settings have already been changed from their default).
Step 3 In the SOAP Attachments/MTOM Handling page, choose from these options:
•Accept and Decode MTOM messages—To have the gateway reconstitute MTOM optimized message content into Base64 format. Once this configuration change is applied and deployed, other processing and validation settings for the virtual service are applicable to the decoded MTOM content.
•Accept both MIME- and DIME-encoded SOAP messages with attachments—To have the gateway accept optimized MTOM but not decode it. Messages can be screened so that only messages with MTOM attachments are accepted by adding an attachment specification, and choosing either:
–any unspecified MIME type for MTOM as well as any other attachment type.
–application/xop+xml to accept only MTOM encoded attachments.
Note To pass through the MTOM message with attachments intact, SOAP attachments output must be enabled for the virtual service.
Step 4 Click Save Changes.
When you deploy the configuration, the ACE XML Gateway processes MTOM messages as configured. Specifically, when Accept and Decode MTOM messages is selected, the ACE XML Gateway checks the SOAP Envelope of incoming messages to this virtual service for
<xop:Include> elements (which indicate the presence of optimized MTOM content). For each element it finds, it checks the list of attachments looking for an attachment whose Content-ID matches the "href" attribute value of the XOP include element (after the "cid" identifier).
For example, the element:
Would match an attachment that had the header:
If a match is found, the content of the attachment is base-64 encoded and used to replace the <xop:Include> element in the SOAP Envelope, with the attachment accordingly removed.
Dynamic Service Routing with WS-Addressing
This section describes how to use WS-Addressing with the ACE XML Gateway. It covers these topics:
•What is WS-Addressing?
•WS-Addressing Support in the ACE XML Gateway
•Using WS-Addressing with Static Routing
•Using WS-Addressing for Dynamic Routing
What is WS-Addressing?
WS-Addressing is a W3C specification for incorporating addressing information within SOAP messages. WS-Addressing defines a format for including addressing information as a SOAP header.
One goal of WS-Addressing is to remove dependencies between SOAP and any particular network protocol. An example of such a dependency is the SOAPAction header. SOAPAction is an HTTP header that SOAP messages are required to have in SOAP 1.1 (it is optional in later specifications).
With WS-Addressing, the SOAPAction and other addressing information is carried within the SOAP envelope. Addressing information is thereby entirely contained within the message content, without depending upon an HTTP header. As a result, a message is independent of a particular transport protocol, and can potentially traverse multiple transport mechanisms en route to its destination (for example, as an email message and then as an HTTP request or response).
The following listing shows a sample WS-Addressing header.
Example 11-1 Sample WS-Addressing header
<?xml version="1.0" encoding="UTF-8"?>
The sample begins with a declaration of the WS-Addressing namespace. The ACE XML Gateway supports these namespaces for WS-Addressing headers:
The ACE XML Gateway WS-Addressing features rely in particular on the
Action header elements:
To identifies the endpoint for the message.
Action contains the URI of the actor to whom the request is addressed. This is equivalent to the SOAPAction HTTP header.
If the incoming request contains a WS-Addressing header, the gateway requires the header to contain both a
Action element. It performs validation on the other headers as well, if present, such as
Unlike other types of SOAP headers, WS-Addressing headers are passed through to the outgoing message by default.
WS-Addressing Support in the ACE XML Gateway
The ACE XML Gateway supports WS-Addressing in several ways. In a standard SOAP service definition, you can enable WS-Addressing header processing. The ACE XML Gateway can then rewrite the header value with information appropriate for the backend service interface.
In this routing configuration, the destination for a virtual service is static; the destination URL is set in the policy configuration, even if branched routing makes several alternative destinations possible. Another way to route messages with WS-Addressing is to have the ACE XML Gateway route to a backend destination dynamically, based on the contents of the WS-Addressing header. The backend service destination does not need to be specified in the policy—it is determined strictly by the content of the incoming
This scenario is shown in Figure 11-1.
Figure 11-1 WS-Addressing dynamic routing
When it receives a message with an WS-Addressing header, the ACE XML Gateway forwards the processed request to the resource identified in the
To field of the header. Note that the gateway only supports destinations drawn from the
To element that are HTTP or HTTPS addresses. Addresses for other types of protocols, such as
mailto, are not supported.
You can impose restrictions on the destinations to which the gateway will route traffic, so that only HTTPS destinations are permitted or only destinations to a specific domain (by regular expression matching), for example.
Using WS-Addressing with Static Routing
Any SOAP service definition in the ACE XML Gateway policy can be configured for WS-Addressing header processing. To do so, use the advanced SOAP header processing settings for the request or response in the SOAP service settings. WS-Addressing heading options appear under the Known Header types, where there are options for the
To element and, in request settings, the
As with other types of SOAP headers, you can make the headers required, optional, or forbidden. You can also specify transformation of the header by XSLT (for more information, see "Advanced SOAP Header Settings" section).
In a request, the gateway provides the following custom handling options for the
•Rewrite with the destination service URL, replaces the contents of the
To element with the destination URL, as drawn from the service interface settings in the service descriptor. The address is composed by the hostname and service path for the service.
•Rewrite with the destination SOAP Action, replaces the contents of the
Action element with the SOAPAction specified in the service interface for this service definition.
To destination and
Action values to be rewritten in the outgoing message, the incoming message must arrive with the WS-Addressing headers. If it does not, this setting has no effect.
Using WS-Addressing for Dynamic Routing
To implement dynamic addressing, you use a WS-Addressing service descriptor in your service definition. SOAP RPC and SOAP Document handlers can route to a WS-Addressing-based SOAP service descriptor.
Figure 11-2 Routing to a WS-Addressing Service Descriptor
The settings of a WS-Addressing service descriptor does not include a backend service URL. Instead, the destination URL is taken from the
To element of the incoming request. As long as the URL meets the requirements you specify, the message is sent to the URL by the gateway.
Note By default, the SOAP headers used in a WS-Addressing service descriptor to route messages are retained in the outgoing message.
The general steps for using WS-Addressing dynamic routing in the ACE XML Gateway are:
Step 1 In the Virtual Services browser, create the handler that defines the consumer interface for the WS-Addressing service. The handler must be either a SOAP Document or SOAP RPC protocol handler.
Note WS-Addressing cannot be implemented with basic virtual service objects. The virtual service must be composed of a handler and service descriptor pair.
Step 2 Create a service descriptor. For the protocol, choose either:
•SOAP Document with WS-Addressing Routing if routing from a SOAP Document handler.
•SOAP RPC with WS-Addressing Routing if routing from a SOAP RPC handler.
Step 3 In the Name field, type a descriptive name for the service descriptor. The name must be unique for service descriptors.
Step 4 Configure the service interface for the WS-Addressing service descriptor. The settings are similar to other SOAP service descriptors, except for the following settings:
•SOAPAction controls how the gateway generates the SOAPAction HTTP header for the outgoing request. For this header, you can have the ACE XML Gateway:
–pass through incoming SOAPAction value—If the incoming request contains a SOAPAction HTTP header, its value is passed through to a SOAPAction HTTP header in the outgoing request.
–use value from WS-Addressing Action element—The WS-Addressing Action element specifies by URL the service a request is intended for. If present in the incoming request, its value is used to populate the SOAPAction HTTP header.
–use fixed value—Use a value you specify in the policy. Enter the value in the text field that appears when this option is selected.
–use value from XPath—Use a value drawn from a location in the incoming request identified by XPath.
–use value from HTTP header—Use the value from a named HTTP header in the incoming request.
•Destination settings are used to constrain the permitted backend destinations to which the gateway will route requests. Control the destination with these options:
–Only allow HTTPS destinations, regardless of any other restrictions—Directs the gateway to block messages for which the
To value is not an HTTPS address. To refine the restriction further, specify additional requirements with the Restrict to destinations option.
–Restrict to destinations—Specifies limitations on the backend destinations to which the gateway will route messages. You can indicate acceptable destinations by URL or using a regular expression for pattern matching. If the regular expression matches the destination value, the message is routed to that destination.
–Forbid Destinations identifies backend services to which messages should never be sent by the Gateway, regardless of the destination value specified by the WSA header. It is suggested, for example, that you specify the localhost as a forbidden address in the WSA configuration to prevent the possibility of a message looping scenario.
•Remote Server Cert sets requirements for the server certificate that the gateway will accept when making the connection to the backend server. You can thereby limit dynamic routing to backend servers that provide trusted certificates only, for example. From the certificate authority certificates list, select the certificates of the CAs to be accepted as certificate signers.
The Timeout, SOAP Version, and Service Time Threshold settings are the same as for other types of SOAP service descriptors.
Step 5 Click Continue.
Step 6 Configure requirements for the request and response messages if desired. For more information, see "Creating Service Descriptors" section on page 5-43.
When finished, the Service Descriptor settings page appears. You can now configure routing to the new WS-Addressing service descriptor from a handler. The handler does not need to have SOAP header processing enabled, although in most cases it will be enabled for other SOAP features.
You can set requirements for the incoming headers in the Advanced SOAP Header Processing settings page for the request. On that page, you can set the WSA header options (for
Action) to required, so that messages without the headers are not accepted by this handler. Do not attempt to configure rewriting for the
Action elements, since their content is rewritten by the service descriptor. Configuring these settings will produce a policy compilation error.
When finished, deploy the policy to make the service available at the gateway. Notice that events associated with a WS-Addressing service are identified in the event log by the "WSAddress" term.