Core Security Patterns: Best Practices and Strategies for J2EE, Web Services, and Identity Management

Message Interceptor Gateway

Problem

You want to use a single entry point and centralize security enforcement for all incoming and outgoing XML messages.

In a Web services communication, allowing XML traffic to directly access the service endpoint creates the danger of content-level and XML-based external attacks from unauthorized parties. Web services traffic uses and tunnels through HTTP and HTTP/SSL ports of a firewall. Traditionally, network firewalls and intrusion detection systems provide protection to network traffic limited to connection attacks based on IP addresses, TCP ports, protocols, and packets. They do not offer application-endpoint security and lack support for providing protection against XML-based message attacks and content-layer vulnerabilities such as buffer overflow, malicious data injection, and virus attachments.

For the enforcement of XML-based security mechanisms and access control policies, it is very important to the exposed Web service endpoints and WSDL descriptions that a security entry point for all inbound requests and outbound responses is established. In addition, you should also require monitoring, logging, and recording of audit trails for the XML traffic. As a result, you need to intercept the XML traffic, look inside the XML content, and ensure that appropriate security and policy actions are taken based on the messages before letting them access the service endpoint. In most scenarios, you must intercept messages for performing content-level processing operations, including authentication, authorization, auditing, encryption/decryption, signature validation, compression/decompression, transformation, routing, and management functions mandated by the service endpoint.

Forces

• You want to block and prevent all direct access to the exposed service endpoints.

• You want to provide a single entry point, a centralized security point, and a policy enforcement point for invoking all target service endpoints.

• You want to intercept all XML traffic and inspect the complete XML message and attachments before processing at the service endpoint.

• You want to verify for message integrity and confidentiality during its transit, particularly for eavesdropping and tampering.

• You want to enforce transport-layer security using two-way SSL/TLS (mutual authentication) to achieve end-to-end data privacy and confidentiality of the communication.

• You want to protect the exposed WSDL descriptions from public access and prevent revealing operations.

• You want to apply message inspection and filter mechanisms on the XML traffic based on content, payload size, and message representation.

• You want to centralize enforcement of identity, role, and policy-based access control for all exposed services.

• You want to integrate existing identity-provider infrastructure for authentication and authorization.

• You want to monitor and identify XML-based replay and DoS attacks by tracking and verifying the IP addresses, hostnames, message timestamps, and other message sender-specific information.

• You want to verify and validate all incoming and outgoing messages for interoperability, current standards, and regulatory compliance.

• You want to enforce centralized logging, monitoring, and management of all XML-based transports, sessions, transactions, and exchanged data.

• You want to track usage, failures, and other service-level statistics, such as metering and billing.

• You want to provide support for verifying and validating incoming and outgoing messages based on XML security standards such as OASIS WS-Security, XML digital signatures, XML Encryption, SAML, XACML, and XrML.

Solution

The Message Interceptor Gateway pattern is a proxy infrastructure providing a centralized entry point that encapsulates access to all target service endpoints of a Web services provider. It acts as a controller that aggregates access and enforces security mechanisms on the XML traffic by making use of identity and access management infrastructure. It secures the incoming and outgoing XML traffic by securing the communication channels between the service endpoints.

The Message Interceptor Gateway accesses the network traffic using a packet sniffer mechanism that inspects the network packets for HTTP and XML headers. Once it encounters a packet with HTTP and XML headers, it off-loads the message to further processing using XML validation mechanisms. The XML validation mechanism is similar to the regular expression matching process for XML, which checks the given XML message against standard XML Schemas meant for verifying XML for well-formedness, structural integrity, and standards compliance. After validation and before allowing the user to access the service, the Message Interceptor Gateway communicates with the Message Inspector pattern for verification of mandated message-level security mechanisms, such as the user's identity and associated security policies that confirm the user's access privileges. Figure 11-3 illustrates the representation of a Message Interceptor Gateway in the Web services architecture.

The Message Interceptor Gateway pattern can be an XML-aware security appliance or a Web proxy infrastructure service that allows intercepting inbound and outbound XML Web services traffic and enforcing consistent security and policies to all its exposed service endpoints and targeting service requesters.

In effect, a Message Interceptor Gateway must handle tasks such as:

• Intercepting all incoming and outgoing XML traffic and verifying XML messages for integrity and confidentiality.

• Applying transport-level security mechanisms such as SSL/TLS for initiating secure communication.

• Identifying the communicating peer and authenticating them via X.509 server certificate or X.509 Mutual authentication of server and client.

• Applying data integrity at the transport-level using HTTP over SSL/TLS to ensure that the data in transit is not intercepted or tampered with by unauthorized parties.

• Applying data confidentiality at the transport-level using HTTP over SSL/TLS to ensure that the data in transit is not available for viewing or disclosed to unauthorized parties.

• Ensuring that a message received is unique and valid by verifying the IDs, timestamps, and receiving order, and making sure it is not resubmitted in a replay attack.

• Disallowing messages initiated from unauthorized parties and untrusted hosts by verifying IP addresses, protocols, service endpoints, message formats, and so on.

• Protecting access to WSDL descriptions with authentication and access control.

• Validating and verifying incoming XML messages for well-formedness, XML schema, and compliance with standards such as OASIS WS-Security and SAML Token profile.

• Validating and verifying the representation of XML digital signatures and XML Encryption.

• Verifying incoming messages for message correlation ID, timestamps, and expiration.

• Detecting content-based attacks such as virus attachments, abnormal messages, and malformed messages that can cause service endpoint crash or failure.

• Interfacing with the Message Inspector, identity provider, and PKI infrastructures to enforce authentication, authorization, and other security policies.

• Enforcing authentication and authorization decisions to the service callers.

• Initiating automated response that alert administrators of detected security breaches and malicious activities.

• Logging and recording auditable trails for monitoring and diagnosing activities.

Structure

Figure 11-4 shows a class diagram of the Message Interceptor Gateway pattern.

Participants and Responsibilities

Figure 11-5 shows the sequence diagram for Message Interceptor Gateway. It shows the interaction of the various participants of the Message Interceptor Gateway pattern for a basic operation that intercepts the XML traffic and then verifies XML data before processing at its service endpoint. The basic components of this pattern are discussed in the list that follows.

The key participants of the pattern are as follows:

Client. The client of the Message Interceptor Gateway is a Web service endpoint that initiates XML traffic or responds to a service request. In a Web services communication, the client can be a service provider or a requester endpoint that encapsulates an application or a Web browser that is capable of posting an XML message.

RequestMessage. The Request message represents a SOAP RPC message or an XML document that is subject to all the required security processing tasks carried out by the Message Interceptor Gateway. Based on the request message, the service endpoint may allow or deny further processing of the message.

Message Interceptor Gateway. The Message Interceptor Gateway is the primary role object of this pattern. It acts as the security enforcement point by encapsulating access to all target service endpoints of a service provider or requester. It facilitates infrastructure services that can provide a secure single entry and exit point by intercepting inbound requests and outbound responses of Web services traffic. This ensures transport-layer security by addressing data integrity and confidentiality at the transport-level; identifying message uniqueness via timestamps, correlation and ordering; validating for standards compliance; and enforcing communicating peer authentication and authorization policies as required by the service endpoint infrastructure. It also ensures logging and recording audit trails of all incoming and outgoing messages.

Message Inspector. The Message Interceptor Gateway makes use of a Message Inspector pattern in a secondary role to provide message-level security processing. It also acts as a security decision point with the authentication and authorization policy decisions, message and element-level verification and validation, logging, and auditing that are required by the service provider endpoint or the message handler intermediary.

Identity Provider. The Identity Provider represents a service or user repository that contains all information required for authentication and authorization of an identity accessing a service.

ServiceEndpoint. The ServiceEndpoint represents the target object and the ultimate consumer of the message that the client asks to do message processing.

Response Message. The Response Message represents the SOAP RPC call or XML document that is sent by the Message Interceptor Gateway. It represents the results of processing the message or an acknowledgement message that lets the client know that the request was received.

Strategies

XML-Aware Security Appliance (XML Firewall) Strategy

The role of the Message Interceptor Gateway can be applied using an XML-aware security appliance referred to as an XML firewall. It complements the role of the network firewall infrastructure by adding support for securing XML message traffic that can be deployed downstream behind firewalls or load balancers. It resides in a DMZ environment and runs as an XML-aware firewall or proxy intermediary that encapsulates access to all exposed service endpoints and WSDL descriptions. The XML firewall appliance can provide functionalities by playing the role of a secure entry and exit point to incoming and outgoing XML traffic. It does this by enforcing secure communication using SSL/TLS, centralized security, and access control that protects the underlying service endpoints. Depending on the vendor solution, it provides support and services for the following: ensuring XML message well-formedness, XML schema validation, content-filtering for viruses and non-compliant messages, identifying and verifying user authentication tokens, signing and validating XML digital signatures, encrypting and decrypting using XML encryption, enforcing XML-based access control policies, ensuring WSDL protection, auditing, logging, providing standards-based security interoperability via compliance with Web services security specifications such as XML digital signature, XML Encryption, OASIS WS-Security, SAML Token profile, REL Token profile, WS-I security profile, and so on.

Intercepting Web Agent Strategy

Most Web services vendors provide pluggable agents that can act as a proxy infrastructure or a security intermediary to secure access to their exposed service endpoints and WSDL descriptions. The agent resides as a pluggable module configured on a Web server or an application server running on a bastion host in a DMZ environment. The agent interfaces with an underlying security provider infrastructure that manages the identity information and access control policies. The agent provides a security layer to the Web services endpoint by intercepting all incoming service requests and outbound responses and by enforcing centralized access control and policy rules for all exposed service endpoints. The identity information, roles, and access-control policies reside on an identity provider infrastructure. Figure 11-6 shows a conceptual representation of Web agent infrastructure strategy.

In addition, depending on vendor implementation the agent may provide support and services for the following: ensuring XML message well-formedness, XML schema validation, content-filtering for viruses and noncompliant messages, identifying and verifying user authentication tokens, signing and validating XML digital signatures, encrypting and decrypting XML Encryption, enforcing XML-based access-control policies, ensuring WSDL protection, auditing, logging, enabling standards-based security interoperability, and ensuring conformance to Web services security specifications such as XML digital signature, XML Encryption, OASIS WS-Security, SAML Token profile, XACML, and WS-I security profile.

Consequences

Using the Message Intercept Gateway pattern helps in intercepting XML traffic in order to perform message-level security operations, including authentication, authorization, auditing, encryption/decryption, signature validation, compression/decompression, transformation, routing, and management. All these functions can be carried out before processing the message at its ultimate endpoint.

Message Interceptor Gateway ensures transport-level security and peer authentication, which verify message uniqueness and standards compliance. At the transport-level, it guarantees data integrity, data confidentiality, non-repudiation, auditability, and traceability. It also safeguards the service endpoint from attacks such as XML DoS, man-in-the-middle, untrusted hosts, brute-force message replay, malicious payloads, and non-compliant messages.

In addition to the above, the Message Interceptor Gateway pattern provides the following benefits to the service endpoint:

• Centralized control. The Message Interceptor Gateway acts as a controller offering a centralized control and processing subsystem for enforcing security-related tasks across all exposed service endpoints. It offers centralized management of related services, including authentication, authorization, faults, encryption, audit trails, metering, billing, and so on.

• Modularity and maintainability. Restricting direct access, centralizing all security mechanisms, enforcing access-control policies, and off-loading security tasks from the service endpoints keeps the underlying application interfaces unpolluted with security-handling methods and saves application processing time and resources. This enhances a service with a modular subsystem designated for security and reduces complex tasks, which results in better maintainability of the overall Web services security infrastructure.

• Reusability. The Message Interceptor Gateway pattern encapsulates and protects all direct access to underlying service endpoints, facilitating a common reusable solution that helps in protecting multiple service endpoints.

• Extensibility. The Message Interceptor Gateway pattern offers extensibility by allowing you to incorporate more mechanisms and functionalities related to transport-level and message-level security, thereby reducing tight coupling or integration with the underlying service endpoint infrastructure.

• Ease of migration. The security layer provided by the Message Interceptor Gateway pattern makes it easier for the underlying service endpoint to have a different security provider implementation. The service-requesting clients or the service provider have no knowledge about the security layer.

• Improved testability. The Message Interceptor Gateway pattern infrastructure separates the security architectural model from the underlying service endpoint. This improves ease of testability and extensibility of the security architecture.

• Network responsiveness. Implementing the Message Interceptor Gateway pattern with a combination of XML firewall and Web services security infrastructure often demonstrates significant performance gains in latency and message throughput. Using a software-only implementation has more processing overhead and impacts network performance.

• Additional expertise required. Implementing and managing the Message Interceptor Gateway pattern often requires strong familiarity and skills related to XML-aware and network appliances.

Security Factors and Risks

• High availability. The Message Interceptor Gateway pattern and every component that interacts with it must provide high availability. It becomes very important to ensure 100 percent availability so that it can be better than that of the weakest link in the overall Web services architecture. Failure to provide high availability may result in monetary loss and security vulnerabilities.

• Fault tolerance. The Message Interceptor Gateway pattern is also expected to be fault-tolerant in order to support security and to enhance reliability and performance of the infrastructure. When a failure is detected, it must be transparently replaced with a redundant infrastructure that does not jeopardize any existing inbound requests and any intermediate processing states. There must be a recovery mechanism that can perform all operationswithout skipping or bypassing any security mechanisms that are currently in placeread all outstanding service requests and paused requests with intermediate state and forward them for further processing by the Message Interceptor Gateway pattern.

Reality Checks

Choosing the right strategy: XML firewall or an Intercepting Web agent? Using an Intercepting Web agent infrastructure provided by a Web services security provider could meet the target Web services endpoint-specific requirements for Web services security standards compliance as well as transport-level and message-level security mechanisms. Using software interfaces to incorporate SSL/TLS, signature validation, and encryption and decryption is usually resource-intensive and incurs processing overheads. It can also affect the performance of the overall architecture. Adopting a combination of an XML firewall appliance strategy and the Intercepting Web Agent strategy would help in achieving the performance and high-availability goals, particularly while handling a large number of connections, binary security tokens, and larger message payloads.

Is the Message Interceptor Gateway pattern performance too slow? Intercepting all XML traffic and handling security-related tasks within an intermediary often degrades performance. In such cases, one could revisit the Message Interceptor Gateway pattern with the Message Inspector pattern or use load-balancing strategies, adding multiple Interceptor gateways to alleviate the degradation.

Related Patterns

Message Inspector [Web Services Tier]. The Message Inspector pattern is used to verify and validate the quality of message-level security mechanisms applied to XML Web services.

Secure Message Router [Web Services Tier]. The Secure Message Router pattern allows secure communication with multiple partner endpoints using message-level security and identity-federation mechanisms.

Message Inspector

Problem

You want to verify and validate the quality of message-level security mechanisms applied to XML Web services.

In a Web-service communication, an incoming message should not be received unless it is confirmed and proven to be safe for further processing. The incoming messages may be client requests or response messages. These messages may contain malicious content or XML messages from unauthorized parties, which are a potential threat to the service provider.

Traditional security mechanisms such as firewalls and packet filtering systems do not secure and verify the content and cannot handle these threats. Message-level security mechanisms are required to secure the XML messages and to handle XML-related security attacks. It is necessary to adopt and deploy an XML standards-based security framework and consistently enforce it before processing messages. This involves pre- and post-processing XML messages by parsing the incoming content. This is done by verifying and validating for processing requirements and then making authentication and authorization decisions based on the message sender or receiver. As a result, it becomes mandatory to inspect the message, particularly for the purpose of identifying the sender and verifying whether the sender confirms its identity. Verification of whether the identity is authorized to send the message, the content has been secured and unaltered during transit, and the content is legitimate and does not contain any malicious information is also necessary.

Integrating message-level security mechanisms with an application service endpoint creates a direct dependency between the service and the XML security implementation. Such code dependencies in application components add complexity and make it tedious to process the application-specific content. It is also tedious when applying changes to security mechanisms in the content.

Thus, a common solution for implementing a series of message-level tasks related to identifying, verifying, and validating XML-based security before and after receiving the message is required. These tasks must be carried out as part of pre-processing or post-processing tasks to ensure that there are no security risks and vulnerabilities associated with the message. Some of these tasks determine whether it is necessary to process the message or to discontinue processing it based on required schemas, constraints, compliance, and specific processing requirements.

Forces

You want to use a common solution for message-level security tasks, such as examining the structure and content and verifying and determining the uniqueness, confidentiality, integrity, and validity of messages before the application endpoint starts processing them.

• You want to proactively identify and potentially limit messages upon receipt based on applied security token profiles and assertions representing the identity and policies.

• You want to monitor and identify message replay and XML-based DoS attacks by tracking and verifying encrypted communication, security tokens, XML digital signatures, message correlation, message expiry, or timestamps.

• You want to verify and validate messages at the element level to identify parameter tampering and message injection attacks via XPATH and XQUERY expressions.

• You want to verify messages for interoperability and standards compliance to guarantee that the applied security mechanisms of the incoming and outgoing messages work seamlessly in all usage scenarios.

• You want to enforce a centralized logging based on the security actions and decisions made on the received messages.

• You want to provide a uniform API mechanism for managing message-level security and processing the security headers in accordance with various XML security standards, such as OASIS WS-Security, XML digital signatures, XML Encryption, SAML Token profile, and REL Token profile.

Solution

Use the Message Inspector pattern as a modular or pluggable component that can be integrated with infrastructure service components that handle pre-processing and post-processing of incoming and outgoing SOAP or XML messages. The Message Inspector combines a chain of tasks intended for identifying message-level security headers, dissecting the header elements, and verifying the message for the key security requirements specified by the service provider. It acts as a Security Decision Point for enforcing all the security policies applicable to accessing a service endpoint, that is, a Web service provider or requester.

In effect, you are able to integrate a set of tasks, including:

• Verifying and validating a SOAP message and its populated headers for standards compliance, such as OASIS WS-Security, SAML Token profile, WS-I Basic Security Profile, REL Token profile, and so forth.

• Identifying the data origin by identification and authentication of the message payload and its elements using OASIS WS-Security and XML digital signature mechanisms.

• Verifying the message for data integrity and validating for accuracy and consistency (for example, that the message parts are not modified or deleted by unauthorized parties) using OASIS WS-Security or XML digital signature mechanisms.

• Verifying the message for data confidentiality to ensure that the message is not viewed by unauthorized parties during transit or processing at intermediaries using OASIS WS-Security or XML Encryption mechanisms.

• Validating and verifying the representation of XML digital signatures, including recalculating the digests by applying the digest algorithm and recalculating the signature using the key information.

• Decrypting and verifying the encrypted data to support the underlying service or prior to further processing by the service endpoint.

• Looking up an XKMS service provider to locate public keys intended for verifying and validating signatures.

• Verifying the messages for correlation IDs, timestamps, and expiration.

• Verifying and validating the business data for required length and data format to avoid buffer overflow attacks and to restrict malicious data insertion attacks.

• Interacting with the identity provider to enforce authentication and authorization.

• Enforcing authentication and authorization decisions based on the message sender's content (such as username/Password, SAML assertions, REL licenses and BinarySecurityTokens such as certificates and Kerberos tickets) and associated security policies.

• Ensuring the XML message conformity based on a given XML Schema, DTD, or XPATH expression to ensure that the content conforms to the security specifications.

• Detecting data injection attacks by identifying malicious schema definitions, XPATH/XQUERY expressions, SQL, cross-site scripting and malformed URLs.

• Initiating automated response upon detection of security breaches and malicious activities.

• Logging and recording audit trails for the monitoring and diagnosis of activities and for the reconstruction of events after a security issue.

Using the Message Inspector pattern eliminates the need for the service endpoint to perform complex message-level security operations, particularly looking up processes with an identity provider, accessing XKMS service, and creating decrypted business documents. These operations are quite resource-intensive (that is, they require excessive utilization of CPU, memory, and network bandwidth). To eliminate these overheads, this pattern provides a mechanism for off-loading these tasks to an intermediary by abstracting all message-level security-specific dependencies required by the service provider application. The Message Inspector pattern can be implemented as a SOAP intermediary that integrates a set of message handlers working in sequence to perform a chain of message-level security tasks required by the service endpoint, such as identification, verification, validation, and extraction of security-specific headers and associated data represented in the message. An XML-aware security appliance that is capable of performing message-level and element-level validation and verification can also be incorporated. It is strongly recommended that the Message Inspector pattern does not cache any data during execution or any data from the message sender that might be needed later.

Structure

Figure 11-7 shows the class diagram for the Message Inspector pattern.

Participants and Responsibilities

Figure 11-8 shows the sequence diagram for the Message Inspector pattern and the various participants.

The key participants of the pattern are as follows:

• Client. The Client is any service requester that needs to invoke a Web-service endpoint. The client initiates a request message represented as method names with parameter values or XML documents. The client can be any type of application or a Web service that can create and send XML messages according to Web-services standards.

• Request Message. The Request message represents a SOAP RPC message or an XML document that is verifiable by all the required security processing tasks carried out by the Message Inspector. Based on the request message, the service provider endpoint may allow or deny further processing of the message.

• Message Inspector. The Message Inspector is the primary role object and main class of this pattern. It implements all the methods intended for message-level security processing. The Message Inspector parses the message requests to determine what needs to be done. It makes use of a series of operations to verify and validate the messages for all security-related processing. In a typical scenario, it acts as a security decision point that provides authentication and authorization policy decisions, message and element-level verification and validation, and logging and auditing functionalities required by the service-provider endpoint or the message-handler intermediary.

• Message Interceptor Gateway. The Message Interceptor Gateway is the secondary role object of this pattern. It provides infrastructure services that can intercept inbound requests and outbound responses to ensure transport-layer security, message integrity and confidentiality, standards compliance. It also enforces authentication and authorization policies required by the service-provider endpoint or the subsequent message-handler intermediary.

• Identity Provider. The Identity Provider represents a service or user repository that contains all information required for authentication and authorization of an identity accessing a service.

• ServiceEndpoint. The ServiceEndpoint represents the target object and the ultimate consumer of the message that the client asks to do message processing.

• Response Message. The Response Message represents the SOAP RPC call or XML document that is sent by the Message Interceptor Gateway or service endpoint. It represents the results after processing the message or an acknowledgement message that lets the client know that the request was received.

Strategies

XML-Aware Security Appliance Strategy

The role of Message Inspector can be off-loaded or delegated to an XML-aware security appliance (XML firewall or XML processing appliance) that is capable of verifying, validating, and processing XML security headers obtained from inbound and outbound Web services traffic. The XML appliance coexists with the Message Interceptor Gateway and acts as a SOAP intermediary or a proxy infrastructure that enforces policies and makes security decisions on behalf of the underlying application service provider or requester. The XML appliance can provide all the Message Inspector functionality, including support and services for XML schema validation, XML parsing, XPath and XQuery handling, identifying and verifying user authentication tokens, applying and validating XML digital signatures, XML Encryption and decryption, XML-based access-control policies, auditing, and logging. It also enables security interoperability based on Web services security standards and specifications. The interoperability requirements must adhere to WS-I Basic Security Profile and associated security standards and specifications, such as XML digital signature, XML Encryption, OASIS WS-Security, SAML, REL, IETF, and so on.

Adopting XML-aware appliances and firewalls can ensure handling of multiple XML security operations at wire speed, which results in a performance gain over software-based solutions. In addition to an XML appliance, it is often good to have a programmatic interface (using the Message Handler Chain strategy discussed in the next section) to enforce verification and validation of messages at the element level for legitimate data, particularly its parameter length, type, and format. Doing this can detect and avoid replay of selected parts of messages, buffer overflows, infinite parsing loops, and malicious data injection using SQL, XSL, XPATH, and XQUERY expressions.

Figure 11-9 shows the sequence diagram for the XML-Aware Security Appliance Strategy.

Figure 11-9 illustrates a client sending a request to an endpoint. The request is intercepted by the Message Interceptor Gateway. After interception, the message is redirected to an XML appliance for verification, validation, and processing of message-level security information. In addition, the XML appliance may connect and interact with an identity provider to verify the request for authentication and authorization credentials.

Message-Handler Chain Strategy

Message Inspector can be represented by plugging in a message-handler chain that can represent a series of operations intended for enforcing message-level security in Web services. These operations include verifying user identity, validating messages for standards compliance, validating signatures, providing PKI lookups, encrypting and decrypting data, verifying timestamps, correlating messages, parsing XML, verifying element-level data, auditing, and logging.

In a Web services communication, each handler represents functionality such as pre-processing or post-processing of inbound requests or outbound responses. Each handler can be implemented to support a security operation that is configured and associated with a service requester client or a services provider server, or both. At runtime, a handler has the ability to access the message header or its body and introduce an operation that can verify, validate, or modify the target message. Multiple message handlers can be grouped together as an ordered group or with a designated sequence representing a set of message processing operations and shared data. It is important that Message Handlers should make use of a dedicated Fault handler that captures all errors and exceptions from the respective operations and returns a response that sanitizes those exceptions in such a way that it does not reveal the internal functionalities and failures. All message handlers are implemented as stateless and they should not cache results of an operation or any data that the client might need at a later point. This helps message handlers to avoid potential threading and concurrency issues.

A message handler chain, including a series of security operations, can be represented as a Message Inspector for a service provider or service requester. During service invocation, each handler completes its operation and then passes the result to the next handler in the chain. When the handler chain completes processing, the message is delegated to the application service endpoint for further processing. In a J2EE-based Web services environment, message handlers can be built using JAX-RPC and SAAJ APIs. Message handlers can also be used for verifying SOAP attachments for potential virus or content-related vulnerabilities, Trojan horses, and malicious data attachments. The message handler chain strategy can make use of the Secure Logger Pattern (Web tier) and Audit Interceptor Pattern (Business tier) to ensure recording of audit trails.

Figure 11-10 shows the sequence diagram for the Message Handler Chain Strategy and the various participants.

The Client sends a request message to its intended service endpoint. The request message is intercepted using the Message Interceptor Gateway pattern for verification and validation of the message for security requirements. The Message Interceptor Gateway makes use of a Message Inspector for initiating message-level security processing. The Message Inspector is represented as a MessageHandlerChain that defines a series of message handlers tasked to apply and perform the sequence of message-level security processing required by the service endpoint. Once the defined operations are complete, the MessageHandlerChain returns a result that verifies all message-level security requirements, such as authentication, authorization, signature verification, and so forth. Based on the results, the message will be allowed or denied further processing.

Example 11-1 is a source code example (LoggingHandler.java) that shows the implementation of a Logging handler using Apache Axis. The logging handler receives all incoming message requests, verifies and validates them for XML Signature using Apache XML security kit, and then logs them using the Apache logging framework (log4j).

Example 11-1. LoggingHandler.java

package com.csp.inspector.handler; import org.apache.axis.*; import org.apache.axis.components.logger.LogFactory; import org.apache.axis.handlers.BasicHandler; import org.apache.axis.utils.Messages; import org.apache.commons.logging.Log; import org.apache.xml.security.signature.XMLSignature; import org.apache.xml.security.utils.Constants; import org.apache.xpath.CachedXPathAPI; import org.w3c.dom.Document; import org.w3c.dom.Element; import java.io.FileWriter; import java.io.PrintWriter; public class LogHandler extends BasicHandler { // 1. Initialize the logger static Log log = LogFactory.getLog(LogHandler.class.getName()); // 2. Initialize Apache XML Security library static { org.apache.xml.security.Init.init(); } // 3. Initiate message verification public void invoke(MessageContext msgContext) throws AxisFault { try { System.out.println("Starting message verification"); Message inMsg = msgContext.getRequestMessage(); Message outMsg = msgContext.getResponseMessage(); // 4. Verify the incoming message for XML signature Document doc = inMsg.getSOAPEnvelope().getAsDocument(); String BaseURI = "http://xml-security"; CachedXPathAPI xpathAPI = new CachedXPathAPI(); Element nsctx = doc.createElement("nsctx"); nsctx.setAttribute("xmlns:ds", Constants.SignatureSpecNS); Element signatureElem = (Element) xpathAPI.selectSingleNode(doc, "//ds:Signature", nsctx); // 5. Ensure that the document is digitally signed if (signatureElem == null) { System.out.println("The document is not signed"); return; } // 6. Validate the signature XMLSignature sig = new XMLSignature(signatureElem, BaseURI); boolean verify = sig.checkSignatureValue(sig.getKeyInfo().getPublicKey()); System.out.println("Message verification complete."); System.out.println("The signature is" + (verify ? " " : " not ") + "valid"); } catch (Exception e) { throw AxisFault.makeFault(e); } } // 7. Log messages to a file public void onFault(MessageContext msgContext) { try { Handler serviceHandler = msgContext.getService(); String filename = (String) getOption("filename"); if ((filename == null) || (filename.equals(""))) throw new AxisFault("Server.NoLogFile", "No log file configured for the LogHandler!", null, null); FileWriter fw = new FileWriter(filename, true); PrintWriter pw = new PrintWriter(fw); pw.println("====================="); pw.println("= " + Messages.getMessage("fault00")); pw.println("====================="); pw.close(); } catch (Exception ex) { log.error(ex); } } }

For more information about implementing and deploying message handlers using Apache Axis, refer to the architecture guide available at http://ws.apache.org/axis/java/architecture-guide.html. To implement XML security using Java, refer to the Apache XML security kit installation and API guide available at http://xml.apache.org/security/Java/. At the time of this writing, preparation of the JSR-105: XML Digital Signature APIs and JSR-106: XML Digital Encryption APIs specifications is still in progress; there are no current standard API mechanisms available for representing XML security using Java.

Identity Provider Agent Strategy

Most identity-provider vendors offer pluggable agents for enforcing XML-based security policies and rules on Web service endpoints. The agent plays the role of a Message Inspector pattern, performing message-level security tasks. These tasks include verifying user identity information, validating messages for standards compliance, validating signatures, making PKI lookups, encrypting and decrypting message elements, auditing, and logging. The agent resides as a modular component in the Web-services provider infrastructure or as a reverse proxy to a Web server that listens to inbound and outbound SOAP messages. The agent protects the service endpoint by intercepting the communication and processing the messages for security and access-control decisions by interacting with the underlying identity provider. The identity provider delivers all the access control and policy decisions made for the inbound requests and outbound responses.

Figure 11-11 shows the sequence diagram for the Identity Provider Agent Strategy and the various participants.

The Client sends a request message to its intended service endpoint. The request message is intercepted using the Message Interceptor Gateway in order to verify and validate the message for security requirements. The Message Interceptor Gateway delegates the request to an identity provider agent residing as a proxy infrastructure component that supports an underlying identity provider. The identity provider initiates the message-level security processing as required by the service endpoint. It takes responsibility for performing key security operations, such as authentication, authorization, signature verification, and so forth. Once the operations are complete, the identity provider issues a single sign-on token (SSO Token) that represents the authentication and authorization decisions to allow or deny the message for further processing at its intended endpoint.

In addition to processing for authentication and authorization decisions, the identity provider agent must be able to incorporate custom mechanisms for verifying selected elements of messages for the purpose of identifying message correlation, timestamps, and element-level data validation. These mechanisms help in detecting message-level attacks that can lead to forged requests, buffer overflow, malicious data injection, infinite parsing loops, and other content-level threats. It is highly recommended to install agents on Web-service infrastructure running on DMZ bastion hosts.

Consequences

Adopting Message Inspector facilitates message-level security processing capabilities and ensures message-level data integrity, confidentiality, non-repudiation, auditability, and traceability. It also safeguards the service endpoint from XML DoS attacks, forged tokens, malicious data injection, identity spoofing, message validation failure attacks, replay of selected parts, schema poisoning, and element/parameter tampering.

In addition, it provides the following benefits to the service endpoint:

• Modularity and maintainability. Separating message-level security mechanisms off-loads resource-intensive security processing tasks from the underlying application endpoint. This enhances the security architecture with a modular subsystem dedicated to processing security headers. It also reduces the complexity of maintaining security-related mechanisms at the service endpoint, which results in better maintainability of the overall Web-services security infrastructure.

• Reusability. Since a Message Inspector pattern encapsulates all the message-level security mechanisms, it facilitates a common reusable solution for protecting multiple service endpoints.

• Extensibility. A Message Inspector pattern offers extensibility by allowing you to incorporate more mechanisms and functionalities and by providing adherence to newer standards for enforcing message-level security. These mechanisms will also remain independent and reduce tight coupling with the underlying service endpoint infrastructure.

Security Factors and Risks

Confidentiality issues. The Message Inspector pattern provides a means to ensure verification and validation of applied message-level security mechanisms and to enforce security policies among communicating partners in Web services. Results returned from the Message Inspector pattern must remain confidential until they are consumed by their immediate or ultimate recipients. These results should not be accessed by, or pass through, intermediary components that are not trusted by the Web-services provider.

Reality Checks

Choosing the right strategy. XML-aware appliance, a message handler chain, or an identity provider agent? Your implementation choice depends on the application service endpoint requirements and the series of operations required for verification and validation of security headers of the message. Using a message handler chain or a vendor's identity provider agent strategy is extensible via programmatic interfaces. Using programmatic interfaces allows adapting to custom element-level data verification and achieving security standards compliance by handling newer content-level threats and vulnerabilities.

Message-level security processing. Tasks such as validating signatures and encrypting and decrypting the data are resource-intensive operations that often impact performance and result in processing overhead (for example, CPU, memory, and network bandwidth utilization). Adopting an XML-aware appliance strategy would help achieve performance and high-availability requirements, particularly while handling a large number of connections, binary security tokens, and larger message payloads by off-loading this processing to specialized hardware design specifically for these operations.

Concurrency implications. Many components associated with the Message Inspector pattern could be competing to update and read session data, which could lead to concurrency issues such as long wait times or deadlocks. A careful analysis of the XML traffic, message payloads, processing requirements, dependencies, and other possible scenarios should bring forth appropriate resolutions and trade-offs.

Related Patterns

Security Logger [Web Tier]. The Secure Logger is used by the Message Inspector to log request messages.

Audit Interceptor [Business Tier]. The Audit Interceptor is used to capture security-related events.

Message Interceptor Gateway [Web Services Tier]. Message Interceptor Gateway provides a single entry point by aggregating access to all service endpoints and centralizes security enforcement.

Secure Message Router

Problem

You want to securely communicate with multiple partner endpoints using message-level security and identity-federation mechanisms.

Using Web services communication in an organizational workflow or across the Internet with multiple partners poses a lot of challenges. If the message sender signs and encrypts the message in its entirety, the message sender restricts the possibility of further message changes by the message recipient in the workflow. This becomes a critical issue when each recipient of the message in a workflow has a responsibility for a selected portion of that message and must modify or add to it.

If the message-level security, such as signature and encryption, were applied to the entire message, any modification made by the initial recipient would invalidate the original message as well as expose the entire message, which was not intended for the initial recipient. In some cases, if a message is intended for multiple recipients and only selected fragments need to be revealed for each recipient, then it becomes more complex to convert each fragment as a message and then compile them together at the end of workflow.

Let's consider an example scenario; a patient visits a hospital that handles all documents and communication electronically using XML Web services. All patient information (for example, contact information, insurance data, health analysis, lab results, doctor observations, prescriptions, visit schedule, credit card information, and so on) is represented in XML. During the visit, the patient's health record is maintained via a workflow involving doctors, pharmacists, insurance providers, and so on. Each individual participating in the workflow does not require complete access to the patient's record. Only selected portions of the message are required and applicable to each workflow participant. For example, the billing department only requires knowing the insurance provider and the co-payment and credit card information; it does not need to know the patient's health history. Although the information workflow happens within an organization, it is a violation of specific legal regulations to unnecessarily disclose information to personnel.

Web services promise easier integration of applications, business partners, and consumers. With multiple parties involved, it often becomes more difficult to communicate with a standardized infrastructure representing a common scheme of authentication and authorization. Sometimes, each service needs a unique representation of credentials and message formats. In a trusted inter-organization or multi-partner communication scenario, eliminating point-to-point security and enabling interoperable mechanisms for single sign-on (SSO), global logout, identity registration, and termination are mandated. This is accomplished by adopting Liberty alliance standards, which define rules and guidelines for defining federated identities, identity registration and revocation, SSO with multiple partner services, global logout, and so forth.

Thus, it becomes very important to provide a security intermediary infrastructure that can handle multiple recipients using a standards-based framework, that can provide message-level configuration security mechanisms, and that can support SSO for accessing disparate security infrastructures.

Forces

• You want to use a security intermediary to support Web servicesbased workflow applications or to send messages to multiple service endpoints.

• You want to configure element-level security and access control that apply message-level security mechanisms, particularly authentication tokens and signatures and encrypted portions using XML digital signature or XML Encryption.

• You want to make sure to reveal only the required portions of a protected message to a target recipient.

• You want to implement SSO by interacting with an identity provider authority to generate SAML assertions and XACML-based access control lists for accessing Web services providers and applications that rely on SAML assertions.

• You want to incorporate a global logout mechanism that sends a logout notification to all participating service endpoints.

• You want to notify participating service providers when an identity is registered, revoked, and terminated.

• You want to dynamically apply security criteria through message transformations and canonicalizations before forwarding them to their intended recipients.

• You want to filter incoming message headers for security requirements and dynamically apply context-specific rules and other required security mechanisms before forwarding the messages to an endpoint.

• You want to support document-based Web services, particularly by checking document-level credentials and attributes.

• You want to enforce centralized logging for incoming messages, faults, messages sent, and intended recipients of the messages.

• You want to configure multiple message formats and support XML schemas that guarantee interoperability with intended service endpoints without compromising message security.

• You want to meet the mandated regulatory requirements defined by Web-services partners.

• You want to use a centralized intermediary that provides mechanisms for configuring message-level security headers supporting XML security specifications such as OASIS WS-Security, XML Signature, XML Encryption, SAML, XACML, and Liberty Alliance.

Solution

The Secure Message Router pattern is used to establish a security intermediary infrastructure that aggregates access to multiple application endpoints in a workflow or among partners participating in a Web-services transaction. It acts on incoming messages and dynamically provides the security logic for routing messages to multiple endpoint destinations without interrupting the flow of messages. It makes use of a security configuration utility to apply endpoint-specific security decisions and mechanisms, particularly configuring message-level security that protects messages in entirety or reveals selected portions to its intended recipients.

During operation, the Secure Message Router pattern works as a security enforcement point for outgoing messages before sending them to their intended recipients by providing endpoint-specific security services, including SSO, access control, and message-level security mechanisms. In addition, it can also provide identity-federation mechanisms that notify service providers and identity providers upon SSO, global logout, identity registration, and termination.

In effect, a Secure Message Router must handle tasks such as:

• Configuring message-level security that allows signing and encrypting an XML message or its selected elements intended for multiple service endpoints.

• Configuring SSO access with multiple Web-services endpoints using SAML tokens and XACML assertions that can act as SSO session tickets.

• Supporting the use of XKMS-based PKI services to retrieve keys for signing and encrypting appropriate message parts specific to a service endpoint or to participate in workflow.

• Notifying all participating service providers and identity providers of SSO and global logouts.

• Notifying all participating service providers and identity providers of identity registration, revocation, and termination.

• Dynamically applying message transformation and canonicalization algorithms to meet recipient endpoint requirements or standards compliance.

• Reconfiguring incoming messages to destination-specific message formats and supporting XML schemas that guarantee interoperability with the target service endpoint.

• Centralizing logging of messages and recording of auditable trails for incoming messages, faults, and their ultimate endpoints.

• Supporting use of a Liberty-compliant identity provider and agents for identity federation and establishing a circle of trust among participating service providers.

Structure

Figure 11-12 shows the class diagram of the Secure Message Router pattern.

Participants and Responsibilities

Figure 11-13 shows the sequence diagram for the Secure Message Router. It illustrates the interactions of the various participants of the Secure Message Router pattern for a basic operation that receives an XML message, interacts with an identity provider, applies message-level security, and sends the message to a workflow or to multiple partner service endpoints over the Internet.

The key participants of the pattern are as follows:

• Client. The client of the Secure Message Router pattern can be any application that initiates a service request to access a single endpoint or multiple service endpoints. Typically, it can be any application component or a Message Interceptor Gateway that sends requests or responds to a Web-services transaction.

• Secure Message Router. The Secure Message Router allows configuring message-level security mechanisms and provides support for Liberty-enabled services such as Federated SSO, global logout, identity registration, and termination services by interacting with a Liberty-enabled identity provider.

• Message Configurator. The Message Configurator plays a secondary role as the Secure Message Router pattern. It implements all the methods intended for configuring message-level security intended for a specified endpoint. It makes use of configuration tables that identify the message, service endpoint and intermediaries, message-level access privileges, validating XML schemas, transformations, and compliance requirements. It signs and encrypts messages in their entirety or selected portions, as specified in the configuration table.

• Identity Provider. The identity provider represents a Liberty-compliant service provider that delivers federated-identity services such as federated single sign-on, global logout, identity registration, termination, authentication, authorization, and auditing.

• Request. The Request message represents an XML document that is verified by all the required security-processing tasks carried out by the Secure Message Router.

• ServiceEndpoint. The ServiceEndpoint represents the target object and the ultimate consumer of the message that the client uses to do message processing. In the case of the Secure Message Router pattern, the ServiceEndpoint can be a single provider or multiple service providers or applications that implement the business logic and processing of the client request.

• WorkflowRecipient. The WorkflowRecipient represents an endpoint that participates in a workflow or in collaboration. It is an intermediary endpoint representing an identity or business logic designated for processing the entire document or selected portions of an incoming message and then forwarding it to the next recipient in the workflow chain.

Strategies

XML Messaging Provider Strategy

In this strategy, the Secure Message Router pattern adopts an XML-based messaging provider or message-broker infrastructure that facilitates sending and receiving of XML messages (such as SOAP or ebXML) using synchronous and asynchronous delivery mechanisms. The XML messaging provider acts as a SOAP intermediary providing message-level security-mechanism support for RPC and document-style Web-services interactions among multiple service endpoints involved in a workflow or collaboration. Figure 11-14 represents the sequence diagram illustrating the Secure Message Router pattern using the XML Messaging Provider Strategy.

The Client initiates XML message requests intended for processing at multiple service endpoints in a Workflow. These messages are forwarded to the messaging provider, which acts as a SOAP security intermediary that allows configuring and applying security-header mechanisms before sending the messages to its workflow participants. Upon receipt of a request message from the client, the messaging provider processes the message and then identifies and determines its intended recipients and their message-level security requirements. It makes use of a Message configurator that provides the required methods and information for applying the required message-level security mechanisms and defining endpoint-specific requirements. The Message configurator follows a security configuration table that specifies the message identifier, endpoints, and message-level security requirements related to representing the identity, signature, encryption, timestamps, correlation ID, and other endpoint-specific attributes. After configuring the message, the messaging provider initiates the workflow by dispatching configured message to its first intended endpoint (that is, a workflow participant). The dispatched message ensures that only the privileged portions of the message are allowed to be viewed or modified by workflow participants, based on their identities and other information; all other portions of the message remain integral and confidential throughout the workflow process.

Liberty SSO Strategy

The Liberty SSO Strategy adopts a federated network identity architecture based on the Liberty Alliance specifications. Using a Liberty-enabled identity provider, this strategy allows establishing circle-of-trust (CoT) relationships via identity federation to enable secure data communication among the service providers over the Internet. The service providers rely on a Liberty-enabled identity provider, which acts as a trust provider that defines and establishes identity federation-based trust relationships and also plays the role of an authority for issuing security assertions that represents authentication, authorization, and other attribute information.

In this strategy, the Secure Message Router pattern makes use of a Liberty-enabled identity provider to link service endpoints, and issue XML-based security assertions. Using the security assertions provided by the service provider, it initiates SSO with partner service endpoints and also uses authorization and other attribute assertions to support message-level security mechanisms for sending XML messages. Figure 11-15 represents the sequence diagram illustrating the Secure Message Router using the Liberty SSO strategy.

During operation, the client will make use of Secure Message Router to process the message, determine its intended endpoint recipients using a message Configurator, and then interact with a Liberty-enabled identity provider to establish SSO with partner endpoints. The Secure Message Router communicates with the Liberty-enabled identity provider using a Liberty-agent via a request and response protocol that works as follows:

1. The Secure Message Router initiates a request to the service provider, which sends a SAML authentication request to an identity provider that instructs the identity provider to provide an authentication assertion.

2. The identity provider responds with a SAML authentication response containing SAML artifacts or an error.

3. The Secure Message Router uses the SAML artifacts as an SSO token to interact with all partner endpoints and to initiate the transaction. The partner endpoints trust the SSO tokens issued by the Liberty-enabled identity provider that established the identity federation.

In addition to the above, the Secure Message Router also facilitates other Liberty-enabled services and tasks, such as notification of identity registration, termination, and global logout to all partner endpoints.

Consequences

Adopting the Secure Message Router pattern facilitates applying SSO mechanisms and trusted communication when the target message is exchanged among multiple recipients or intended to be part of a workflow. It also allows selectively applying XML Encryption and XML Signature at the element level by ensuring that content is not exposed to everyone unless the recipient has privileges to access the selected fragments of the message. This helps in securely sending messages to multiple recipients and ensuring that only selected fragments of the message are revealed or modified by the privileged recipients. With the support for Liberty-enabled identity providers, it establishes a circle of trust among participation endpoints and facilitates SSO by securely sharing identity information among the participating service endpoints. The Secure Message Router also ensures seamless integration and interoperability with all participating endpoints by sending destination-specific messages.

In addition, the Secure Message Router pattern provides the following benefits:

• Centralized routing. The Secure Message Router delivers a centralized message intermediary solution for applying message-level security mechanisms and enabling SSO access to multiple endpoints. This allows configuring a centralized access control and processing subsystem for incorporating all security-related operations for sending messages to multiple service endpoints. It offers centralized management of related services, including authentication, authorization, faults, encryption, audit trails, metering, billing, and so on.

• Modularity and maintainability. Centralizing all security mechanisms and configuring access-control policies using a single intermediary keep the message-sender application interfaces separated from security operations. This enhances a service with a modular subsystem designated for security and reduces complex tasks at the service endpoint of a Web services provider. This also saves significant application processing time and resources at the message-sending application endpoint.

• Reusability and extensibility. The Secure Message Router pattern encapsulates all direct access to participating service endpoints, facilitating a common reusable solution that is necessary for protecting multiple service endpoints. It also offers extensibility by allowing you to incorporate more message-level security mechanisms and functionalities specific to the target endpoints.

• Improved testability. The Secure Message Router infrastructure separates the security architectural model from the underlying message-sender's service endpoint. This improves ease of testability and extensibility of the security architecture.

Security Factors and Risks

• High availability and reliability. The Secure Message Router infrastructure and every component that interacts with it must provide high availability and reliability. It becomes very important to ensure 100 percent availability so that the message router can be better than the weakest link in the Web-services architecture. Failure to provide high availability may result in monetary loss and security vulnerabilities.

• Fault tolerance. The Secure Message Router is also expected to be fault tolerant in order to support security and to enhance reliability and performance of the infrastructure. When a failure is detected, it must be transparently replaced with a redundant infrastructure. The failure should not jeopardize any existing outbound requests or responses or their intermediate processing states. There must be a recovery mechanism that can read all outstanding service requests and paused requests with intermediate states and forward them for further processing with the Secure Message Router without skipping any existing security mechanisms.

• Provider issues. From an implementation standpoint, there are not many messaging providers that facilitate standards-based XML message workflow, multi-hop Web-services communication, and Liberty SSO. Using nonstandard implementations affects the secure message-router-based architecture with noticeable problems related to incompatible messages, routing failures, longer latencies, and lack of guaranteed message delivery. In general, these issues directly affect security and reliability of Web services or workflow communication using multiple Web-services endpoints. The adoption of emerging Web-services standards such as BPEL4WS, WS-Reliability, WS-Reliable Messaging, WS-*, and their compliant products is expected to provide interoperable workflow collaboration, reliability, and guaranteed message delivery protocols.

Reality Checks

Enabling interoperability in a workflow? The Secure Message Router must pre-verify the messages for interoperability before sending them to participants in a workflow or intended recipients. The interoperability requirements of the recipient endpoint with regard to WS-I profiles, XML schemas, transformations, canonicalizations, and other endpoint-specific attributes must be specified using the Message Configurator.

Scalability? It is important to verify the Secure Message Router solution architecture for scalability to eliminate bottlenecks when communicating with multiple endpoints. This is critical to the success of every Message Router to perform resource-intensive tasks such as applying signatures, encryptions, and transformations without the expense of scalability and overall performance.

Related Patterns

Message Inspector [Web services]. The Message Inspector pattern is used to verify and validate the quality of message-level security mechanisms applied to XML Web services.

Message Interceptor Gateway [Web services]. Message Interceptor Gateway provides a single entry point by aggregating access to all service endpoints and centralizes security enforcement.