Arun Manglick - Technical View: 07

Hi,

Here we see the use of SOAP Extension.

Intent –

· SOAP extensions enable you to access and modify SOAP messages that XML Web services send to and receive from clients

Overview of SOAP Extensions

· An XML Web service sends and receives data from clients in the form of SOAP messages.

Cleint à Call on Proxy à Serialize à Soap Message à Encrypt à Sent to Server

Server à Decrypt à Deserialize à Actual WebService Object à Execute the Method

Server à Call on Proxy à Serialize à Soap Message à Encrypt à Sent to Server

Client à Decrypt à Deserialize à Return value to ProxyObject -> ProxyObjec sends value to Client

· SOAP Extensions are components that can Access And Modify the SOAP messages at each stage and manipulate them.

· When the HTTP request comes the aspnet_isapi.dll passes it to appropriate handler for web services and later the web method is invoked. It is during this stage where the SOAP Extension comes into picture.

· The SOAP Extension can access the SOAP message before and after calling the web method. Thus we now know in a vague manner what a SOAP extension is and where it fits in the life cycle of a SOAP message.

· To build a SOAP Extension, we must create a class that inherits from System.Web.Services.Protocols.SaopExtension abstract class.

· SOAP Extensions can be used for a number of purposes. For e.g.

Validation - Use SOAP extensions to validate the SOAP message before it is send so that the XML Web service receives a valid SOAP request.

Encryption - Use SOAP extensions to implement an encryption or compression algorithm that can be executed within an existing XML Web service.

Securing Web Services –

Compressing the Soap Message -

SOAP Extensions Phases:

· Thus the SOAP message goes through a process of serialization and deserialization both at the client and the server side. The various stages of SOAP messages are available in the SOAPMessageStage enumeration. The members of the enumeration includes:

o BeforeDeserialize

o AfterDeserialize

o AfterSerialize

o BeforeSerialize

· We can use the SOAP extension to perform various operations, before and after the serialization and deserialization phases. For e.g -

Encrypting and Decrypting the SOAP messages in these two phases on both the client and server sides.

The encryption takes place only after ASP.NET serializes the SOAP messages. The decryption of these messages occurs before ASP.NET deserializes the messages at the server side.

Building SOAP Extensions - Steps

To build a SOAP extension, you need to perform the following tasks:

· Create a class that inherits from the System.Web.Services.Protocols.SoapExtension class.

· Save a reference to the Stream class that represents future SOAP messages.

· Initialize SOAP extension–specific data.

· Process the SOAP messages during the relevant SoapMessageStage stages.

· Configure the SOAP extension to run with specific XML Web service methods

Creating a Class –

· To let the class provide the functionality of a SOAP extension, it must be derived from the System.Web.Services.Protocols.SoapExtension class.

· This is an abstract class and our derived class should implement the functionalities. The functions include:

Public Overrides Function ChainStream(ByVal stream As Stream) _As Stream

Public Overloads Overrides Function GetInitializer(ByVal methodInfo As LogicalMethodInfo, ByVal attribute As SOAPExtensionAttribute) As Object

Public Overloads Overrides Function GetInitializer(ByVal WebServiceType As Type) As Object

Public Overrides Sub Initialize(ByVal initializer As Object)

Public Overrides Sub ProcessMessage(ByVal message As SOAPMessage)

Save a reference –

· Before you modify a SOAP message, you should obtain a reference to the stream of data that represents the contents of the message.

· Next, you override the ChainStream method to modify the contents of the SOAP message.

· The ChainStream method provides access to the SOAP request or response message contained in a memory buffer. A reference to the stream containing the SOAP request or response is passed to the ChainStream method as a parameter before any SoapMessageStage stage starts.

· This object of the Stream class refers to the XML of the SOAP message after the SOAP extensions execute and modify the message.

· Therefore, a SOAP extension should save this reference in a member variable for access during the SoapMessageStage stage when a SOAP extension inspects or modifies the SOAP message.

· You should not modify the Stream object that is passed into the ChainStream method by using a SOAP extension.

· Instead, you should create an instance of a Stream object, save the instance in a private member variable, copy the contents of the SOAP message to the private Stream object, and return the instance to the calling program from the ChainStream method.

· As the SOAP extension executes during each SoapMessageStage and modifies the SOAP message, a SOAP extension should read from the Stream object passed into ChainStream and write to the Stream object that the ChainStream method returns. Therefore, you must save both the Stream references within the ChainStream method. Figure 8.1 shows the stages of how a SOAP extension modifies a SOAP message

Initializing SOAP Extension–Specific Data

· The SOAP extension class provides two methods to initialize data - GetInitializer and Initialize.

· GetInitializer - called only once.

· Initialize - called whenever a request comes in.

GetInitializer -

· Called only once when you access an XML Web service or Web method.

· Has two overloads. The first overload is called when the extension is configured by Web.Config, the second is called if the extension is configured by a SOAPExtensionAttribute on a specific WebMethod.

· This data in the Getinitializer method will be cached by the ASP.NET infrastructure. This cached data will be passed to a SOAP extension in the Initialize method

Initialize –

· Called every time the SOAP extension runs with the web method. In cases where we do not want any initialization of data, we can return null.

Processing SOAP Messages

· The heart of the SOAP Extension lies in processing the SOAP message. This is handled by the ProcessMessage function.

· This method allows us to manipulate the SOAP message.

Public Overrides Sub ProcessMessage(ByVal message As SoapMessage)

Select Case message.Stage

Case SoapMessageStage.BeforeSerialize

Case SoapMessageStage.AfterSerialize

arr = objEnSoap.EncryptSoap(arr)

WriteOutput(message)

WriteOutput(arr)

Case SoapMessageStage.BeforeDeserialize

arr = objEnSoap.DecryptSoap(arr)

WriteOutput(message)

WriteOutput(arr)

Case SoapMessageStage.AfterDeserialize

Case Else

Throw New Exception("invalid stage")

End Select

End Sub

· The input parameter to this method is the SOAP message. It contains the information about what states the SOAP message belongs to.

If the SOAP extension is executing with an XML Web service, a SoapServerMessage is passed as the parameter.

If the SOAP extension is running with an XML Web service client, a SoapClientMessage is passed as the parameter.

Configuring SOAP Extensions to Execute Using XML Web Service Methods

SOAP extension can be confirgured to run using a Custom Attribute or by modifying a Configuration File.

Custom Attribute –

o To use a custom attribute, apply it to each XML Web service method that you want the SOAP extension to run with.

o To use a custom attribute, derive a class from SoapExtensionAttribute.

o SoapExtensionAttribute has two properties, ExtensionType and Priority.

A SOAP extension should return the type of the extension in the ExtensionType property.

The Priority property represents the relative priority of the SOAP extension.

[AttributeUsage(AttributeTargets.Method)]

public class TraceExtensionAttribute : SoapExtensionAttribute {

public override Type ExtensionType {

get { return typeof(TraceExtension); }

}

Configuration File -

o When you use a configuration file, the SOAP extension runs with all the XML Web services that are within the scope of the configuration file.

o You must add a <soapExtensionTypes> XML element to the webServices section of the configuration file. Within the <soapExtensionTypes> XML element, you add the <add> XML elements for each SOAP extension that you want to run with every XML Web service within the scope of the configuration file

Properties of the <add> XML Element
Property	Description
Type	Indicates the type of the SOAP extension
Priority	Indicates the priority of a SOAP extension within a group
Group	Indicates the group a SOAP extension belongs to

· SOAP extensions have a Priority assigned to them that dictates the relative order of execution when multiple SOAP extensions are configured to run with an XML Web service method.

· The higher the priority of a SOAP extension, the closer it executes to the SOAP message that is being sent or received over the network.

· SOAP extensions belong to one of three Priority Groups. Within each group, the Priority property distinguishes each member. The lower the Priority property, the higher the relative priority, with 0 being the highest.

The three relative Priority Groups for SOAP extensions are

· SOAP extensions configured using a custom attribute - Medium group

· SOAP extensions specified in the configuration file with a Group setting of 0 - Highest Relative Priority

· SOAP extensions specified in the configuration file with a Group setting of 1 - Lowest Relative Priority

Reference:

http://www.codeproject.com/KB/webservices/Securing_web_services.aspx

http://msdn.microsoft.com/en-us/library/ms972353.aspx

Thanks & Regards,

Arun Manglick || Senior Tech Lead