An Approach to Web Services Non-Functional Requirements Using WSDL Annotations

1. Introduction

Web Services play a key role in implementing Service Oriented Architecture (SOA). The notion of describing the service independent of the technology in which it has been implemented has been robustly captured in the Web Services Definition Language (WSDL) Specification. WSDL clearly specifies the service location along with the operations that need to be invoked, the parameters that need to be passed, the data type of each parameter, and the various message formats and types. WSDL describes both Document and RPC Style web services as explicitly as possible.

However, in most of the SOAP engines implemented by various vendors, the WSDL generation for a service is done automatically, when the service is deployed. This gives minimal freedom to the developer to customize the WSDL as per his/her needs during deployment of the service. But in terms of RPC services the amount of information given by WSDL is more than sufficient for the client to consume the service. But Basic Profile published by WS-I recommends the use of document style web service for maximum interoperability between service providers and the service consumers. This resulted in defining robust message exchanges with the help of XML schema. The XML schema that the input and output messages are based on is embedded into the WSDL, so that WSDL contains the complete information to facilitate dynamic discovery and invocation of the service. Hence the WSDL generated by the SOAP engines need to be customized to include the Schema information.

Also in the recent past, web services have been used in the e-commerce world dealing with critical data which need to be secured. Since then the free for all services concept has been dwindling with emphasis on proper access control for the service. The services also do not include the security feature intrinsically, but the feature is provided as a wrapper over the existing services, sometimes completely invisible to the service itself. This helps in re-using the existing services and still be able to make the service robust. In scenarios like these, the WSDL description of the service needs to be modified to include the security mechanism involved in invoking the service so that a client trying to consume the service can pass the necessary security credentials to the service. This raises the issue of customizing the WSDL to carry this information in a standard way to facilitate the dynamic discovery and invocation of the service.

In the coming sections we have addressed these issues and have explained a standards-based manner of customizing WSDL. We have also analyzed various SOAP engines with respect to support rehosting and consumption of customized WSDL for proxy generation. It also describes the interoperability issues and the best practices for customizing WSDL followed by conclusion and scope of future work.

2. Customizing WSDL

Customizing WSDL documents can result in regenerating the Web services binding file and in some cases, writing a wrapper program. One reason to add more custom information to the dynamically generated WSDL is for custom schema requirements as well as non-functional requirements to some extent. In different enterprise applications, it is also important to embed these extra information in the client stubs. In this context, the inclusion of a custom schema and security information in a WSDL file can be taken into consideration for displaying how exactly the WSDL can be used to invoke a service.

2.1. Schema Inclusion

As web services have been widely accepted in the industry from the small scale pilots to big scale enterprise level applications, the way information about the service is provided has become the most important point that developers need to address during the time of service deployment. This will ensure that the service is seamlessly invoked by a client without having much knowledge of the service and the background technology. As all the information about the service is communicated through the WSDL, it has the option of embedding schema in it. Using this embedded schema any SOAP engine tool that uses WSDL as input to generate the proxy classes can create the data holders and create a valid request for the invocation of service. The types element encloses data type definitions that are relevant for the exchanged messages [1]. A typical WSDL with types definitions looks like the one given in Listings-1

 <wsdl:definitions targetNamespace="http:// localhost:.48:8080/axis/services/CreateCustomerService"> <wsdl:types> <xs:schema targetNamespace="http://localhost:8080/axis/services/CreateCustomerService" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="createCustomer" type="createCustomerType"/> <xs:complexType name="createCustomerType"> <xs:sequence><xs:element name="NewCustomer" type="NewCustomerType"/></xs:sequence> </xs:complexType> [...........................] </xs:sequence></xs:complexType> </xs:schema> </wsdl:types> [.............] </wsdl:definitions>

Listing 1: WSDL containing the Schema inside the types element

In the above Listing-1 the entire schema is embedded in between the tag types. The information between the types tag is the detail of the data that is exchanged with the service. The important point to notice here is that unlike the RPC based services where the input and output data is simple, document style web service can have a complex structure of input and output data. All the soap engines, for example Apache axis, do not create a types definition for document style web service. In such cases a static wsdl has to be deployed with schema embedded in it. This will allow a user to generate the proxy classes and value objects for the web service allowing dynamic invocation.

2.2. Security Information Inclusion

In the last few years, Web services have gone from being an overly-hyped technology to one that many organizations are using productively. In these situations, even though service providers were using industry standards like SOAP, WSDL, etc. additional information concerning the security process was needed in order to allow the service providers to secure the service and provide a standard way to service requestors to send the security related data . So in April 2002, the WS-Security became an industry wide standard for exchanging security credentials between service provider and the consumer.

WS-Security Specification states "WS-Security describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms can be used to accommodate a wide variety of security models and encryption technologies." (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf )

2.2.1. Issue of exposing security related information to the consumers

While WS-Security concentrates on the standards required for the security credentials exchanged as part of the SOAP message, there are no standard mechanisms by which Security related information of the service can be communicated to the consumers. WSDL is the standard for communicating any information about a service to the consumers; hence the WSDL of a service needs to be customized to capture the security details adhering to the WSDL specifications.

A proper standard mechanism for communicating security related information to all the service consumers. for any web service is not present, so the question of how to inform a consumer about the security credentials that one needs to invoke the service.

Assuming the fact the WSDL is having security related information, the next information that needs to be answered is generation of client side proxies to access the service.

Normally for consuming a web service, consumers prefer to use the proxy generation tool of various SOAP engines to generate the proxies from WSDL. However, these tools provided by various vendors do not provide any mechanism to embed security related information in the proxy classes even from the custom WSDL.

2.2.2. Using SOAP Headers in WSDL 1.1

The issue of communicating security related information to various clients can be solved to some extent by exposing the required security credentials in the WSDL in a standard way.

According to the WS-Security Standard, security related information is embedded inside the SOAP Header (optional element in the SOAP Message). The WSDL 1.1 specification (https://www.w3.org/TR/wsdl#_soap:header ) also provides a mechanism of to embed SOAP Header related information in Web Services Security (wsse). Figure 1 gives the snap shot of the same. So if the WSDL 1.1 specification provide a way of inserting the SOAP Header information, then there should be a standard way of adding the Security related information too.

 <definitions .... > <binding .... > <operation .... > <input> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </input><output> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </output></operation></binding> </definitions>

Listing 2: WSDL Specification Snippet containing SOAP Headers

The "Customizing WSDL" tool mentioned in this paper is primarily with the objective of inserting security related information in the WSDL (w.r.t. WSDL specifications 1.1).

In the next section the above mentioned tool as well as the WSDL customization process is being discussed in details.

2.2.3. Customizing WSDL with security related information

The WSDL file for a particular web service can have multiple bindings and every binding can have multiple operations and each operation can have different security mechanisms.

In order to run the complete customization process, the tool takes the following inputs:

• WSDL File which needs to be customized
• The binding for which the security provided
• Operation for which the security information has to be provided
• Type of Security Tokens - (User Name Password or Binary Tokens)

Depending on these parameters, the tool is able to modify the existing WSDL, add the security related information appropriately and create a new WSDL out of it. The tool uses the open source implementation WSDL4J for parsing the existing WSDL file. It checks for the corresponding bindings and operations in the WSDL file as mentioned in the inputs and make the required changes.

Figure 1 is a shows a WSDL file containing two operations for a particular binding, where the CalculateAddition operation is secured by a Username Password, and this information is missing in the given WSDL.

Figure 1: WSDL of the service

Figure 2 shows the WSDL modified by our tool after adding the security details.

Figure 2: CalculateAddition Operation expects a WS-Security Username Token in the header of the incoming SOAP request

2.2.4. Tool Functionality

The GUI of the tool which allows the user to do WSDL customization is shown in Figure 4. Presently, the tool is packed with Axis 1.2.1. The steps involved in using it are very simple. Firstly, the tool uploads the WSDL File. WSDL specific vendor information is also required. Although WSDL is an open standard, still the vendor specific information is required due to some interoperability issues (in Section 3.2.2).

On uploading the WSDL, all the information related to binding, operations are displayed. Depending on the requirement, the schema or the security related information is provided.

Figure 3: User Interface of the TOOL which allows the user to upload and customize the dynamic generated WSDL

3. SOAP Engines support for Custom WSDL

3.1. Re-hosting the WSDL

After the existing WSDL file has been customized, there is a proper way of re-hosting the new modified WSDL.

Generally, any SOAP engine dynamically generates the WSDL of a Web Service, based on the contents of its deployment descriptor file. Most SOAP engines provide a way to publish a static and customized WSDL. If the Web Service Implementation is changed, one should also manually change the static WSDL file to reflect the changes one has made to the Web Service. Different SOAP Engines have different implementations of re-hosting the WSDL file. The following section talks about in detail.

3.1.1. Re-hosting Implementation in AXIS 1.2.1

In order to publish a new static wsdl file in Axis on Tomcat 5.0.28, the deployment descriptor of the Web Service needs to be modified. An element wsdlFile needs to be inserted, for a particular Web Service, containing the location of the static wsdl file as shown in Listing 3. The WSDL file can be any where in the disk but it is recommended that it must be inside the respective directory or sub-directories inside classes folder. Then the server needs to be restarted. The change in the deployment descriptor file (server-config.wsdd) is shown in Listing 3.

 <service name="RPCService" provider="java:RPC"> <wsdlFile> CHANGEDWSDL.wsdl</wsdlFile> <parameter name="allowedMethods" value="*"/> <parameter name="className" value="RPCServices.Service"/> </service>

Listing 3: CHANGEDAXISWSDL is the custom WSDL of the Service

Similarly, the "Customizing Tool" mentioned in Section 2 also allows the user to re host the WSDL in axis. In fact, the tool makes required change in the deployment descriptor file and advises the user to restart the server in order to make the changes effective.

Figure 5 shows the User Interface where one is asked to re host the WSDL on axis 1.2.1.

Till date, the tool can only re host the WSDL File on Axis. In its future versions, it is going to re host the customized WSDL in other different vendor specific soap engines.

Figure 4: User Interface of the TOOL which allows the user to re host the customized static WSDL on Axis

3.1.2. Re-hosting Implementation in Websphere Application Server 5.1.2

In order to publish the new WSDL file on Websphere Application Server 5.1.2, the deployment descriptor file webservices.xml needs to be updated. The value of the wsdl-file element needs to be modified. Generally,, it refers to the WSDL file WEB-INFwsdl (default), which can be replaced with the new WSDL file. The purpose of re-publishing the WSDL file is to provide consumers with a description of the Web service, including the URL identifying the location of the service.

The WSDL files for each Web services-enabled module are published to the file system location one has specified. One can provide these WSDL files to consumers that want to invoke the Web services.

The WSDL file can be re-published in three different ways in Websphere:

• Using the Administrative Console
• Using the wsadmin command tool
• Publish it through a URI

Listing 4 depicts the changed deployment descriptor in Websphere Application Server using the URI Publish way.

 <webservices id="WebServices_1132306198577"> <webservice-description id="WebServiceDescription_1134098346888"> <webservice-description-name>WEBSERVICEService</webservice-description-name> <wsdl-file>WEB-INF/wsdl/ CHANGEDWSDL.wsdl </wsdl-file> <jaxrpc-mapping-file>WEB-INF/WEBSERVICE_mapping.xml</jaxrpc-mapping-file> [.........] </webservices>

Listing 4: Inclusion of Custom WSDL in Websphere Application Server

3.1.3. Re-hosting Implementation in Weblogic Application Server 8.1.2 SP4

In order to publish the new WSDL file on Weblogic Application Server 8.1.2 SP4, updating of the web.xml inside the WEB-INF is necessary. The WEB-INF also contains their proprietary deployment descriptor file web-services.xml. The <mime-mapping> element needs to be added in the web.xml file. The new wsdl can be placed inside the top most directory of the Web Application, just above the WEB-INF directory. If the new wsdl is CHANGEDWEBLOGICEWEBSERVICEUSERNAMETOKEN.wsdl, then the entry in the web.xml would be as shown in Listing 5.

 <mime-mapping> <extension>wsdl</extension> <mime-type>text/xml</mime-type> </mime-mapping>

Listing 5: Inclusion of Custom WSDL in Weblogic Application Server

3.2. Proxy Generation from custom WSDL

The earlier section explained customizing WSDL files and publishing them on their respective application servers and their soap engines.

Apart from this, different proxy generation tools by various vendors was also examined to check what kind of interfaces or client stubs were generated from the customized WSDL. The objective was to check whether the generated client stubs contains any information about the security information embedded inside the WSDL. Were the tools agile enough to include the soap header information in the stubs? The following section talks about that.

3.2.1. Proxy Generations

An existing web service has been secured provided with the security feature. The web service requires a username token from the consumers to function properly. The security feature has been implemented using Web Service Security for Java (wss4j) - An Open source implementation of WS-Security. The security features of the web service were implemented using vendor specific Handlers in all the following cases.

The tool used in Axis to generate the client stubs is called WSDL2Java. It is a command line tool utility. It generates the necessary classes and interfaces with WSDL as the input. Strikingly, the client stubs generated does not contain any information about the SOAPHeader and its message content and the element required to embed. But the client stubs has one extra class SecurityFault which was mentioned in the WSDL inside the header of the output element of the operation element.

But that does not say anything about what tokens or security credentials needs to be passed by the client to access the service.

In Websphere Application Server a similar kind of tool called WSDL2Java does the client proxy generation. It is also a command line tool utility. It also generated two interfaces about the definition of the different methods. Apart from that, the interfaces did not give any information about the tokens/security credentials. In Weblogic, the tool that is used to generate the client stubs in Weblogic 8.1 is called wsdl2service. It is an ant task, as shown in Listing 6.

 <project name="buildWebservice" default="generate-from-WSDL"> <target name="generate-from-WSDL"> <wsdl2service wsdl=" CHANGEDWSDL.wsdl " destDir="wsdl/security" packageName="caseStudy.security"/> </target> </project>

Listing 6: Ant Script to generate the proxies from the WSDL

The ant task wsdl2service creates the necessary client stubs. In this particular case, it creates only a single interface which contains information about the security tokens as well as shown in Listing 7.

 public java.lang.String calculateAddition(int intiOne, int iTwo,weblogic.xml.schema.binding.util.runtime. SOAPElementHolder UserNameToken) throws java.rmi.RemoteException ;

Listing 7: Client Stubs Generated by Ant Script

Apart from the stubs being generated, the wsdl2service also generated the deployment descriptor file web-services.xml which also contains information about the security tokens or rather the soap header information as shown in Listing 8.

 <param xmlns:param prefix="http://schemas.xmlsoap.org/wsdl/" type="param-prefix:UserNameToken" location="header" class-name="javax.xml.soap.SOAPElement" name="UserNameToken" style="inout"> </param>

Listing 8: Deployment Descriptor containing information about the SOAP headers

3.2.2. Interoperability Issue

In all these proxy generation tools, there is an interoperability issue that needs to be addressed. In cases of Axis and Websphere SOAP Engines, the proxy generation tool checks the WSDL and checks the wsse: SecurityHeader (taking the namespace URI xmlns: wsse) and generates the wsdl. Listing 9 depicts the Binding Input of the WSDL which mentions about the Security Header.

 <wsdl:input name="calculateAdditionRequest"> <wsdlsoap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="http://RPCServices"/> <wsdlsoap:header message="wsse:SecurityHeader" part="UsernameToken" use="literal" namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> </wsdlsoap:header> </wsdl:input>

Listing 9: WSDL Binding Input exposing the Security Header Information

Likewise, if the same wsdl has given as input to generate the client stubs using Weblogic Tool "wsdl2service," it will throw an error saying the SecurityHeader message is not declared. This, according to the WSDL Specification 1.1 should not be the case, because the same WSDL which is valid in generating the client stubs for one SOAP Engine should also work fine for others too.

So in this context, in Weblogic specifically, we have to generate the Security Header Message in the WSDL too.

That answers the questions why one needed to mention the WSDL Vendor type while uploading the WSDL.. Thus, the conclusion that can be drawn is, an interoperability issue exists, which needs to be sorted out. On the other hand, the proxy generation tool provided by Weblogic is more robust as well as agile enough to understand the customized WSDL. It helps the end-user to know that one must pass security token inside the client as a proper parameter to access the web service.

4. Best Practices to Customize the WSDL

It can be clearly seen out that there is an interoperability issue the way wsdl is being customized. The same customized wsdl is not generating the client stubs properly when used with all the respective proprietary proxy generation tools. The best way to deal with this issue is to create a generic customized wsdl such that the client stubs are generated irrespective of any proprietary proxy generation tool.

The number of issues that has to be kept in mind while creating the custom wsdl such that the interoperability issued does not arise are as follows:

• Create the SecurityHeader message
• Create the part with name and element equal to the Security Token that needs to be embedded in the WSDL
• The prefix of all the relevant Security related namespaces should be properly declared. In this scenario, the prefix "wsse" is mainly required.
• The SecurityFault Message needs to be declared such that it can be used in the SOAP Header Fault

The above declared points are the basic issues, which sorted out; the customized tool can be easily generated irrespective of the SOAP Engine and the proxy generation Tool.

5. Conclusions

So, presently, the tool that we have mentioned is customizing the existing WSDL File and embedding various custom information in a proper standard way. The tool can be used as a plug-in in different enterprise web applications. The tool can be utilized in a much more efficient way as it is being mentioned in the Future Works Section

6. Future Works

There are a number of improvements planned in the future. There are a number of important issues on which the tool can be improved and a better version can be implemented.

• The tool can be used at the client side to generate the client stubs which would contain the soap header related information (just as "wsdl2service" of Weblogic does)

• In the above sections, we have discussed in detail how the Non-Functional Requirements (NFRs) (mainly "security") can be embedded in the WSDL which is adhering to WSDL Specification 1.1.

  At the same time, WSDL 2.0 specification allows the Feature Component to carry NFR information like reliability, security, correlation, routing, etc.

  The tool can be utilized in a more robust way by adding the mechanism such that it can migrate or customize the WSDL (presently adhering to WSDL 1.1 Standard) to WSDL 2.0 specification. So for any enterprise application, which wants to migrate their WSDL 1.1 to WSDL 2.0 can use the tool as a plug-in and achieve it very easily.

7. References

[1] Web Services Definition Language (WSDL) 1.1, https://www.w3.org/TR/wsdl_November_20005

[2] Web Services Definition Language (WSDL) 2.0, https://www.w3.org/TR/wsdl20/#Feature

[3] What's New in WSDL 2.0, http://webservices.xml.com/pub/a/ws/2004/05/19/wsdl2.html

[4] Implementing WS-Security, http://www-128.ibm.com/developerworks/webservices/library/ws-security.html

[5] Web services programming tips and tricks: Using SOAP headers with JAX-RPC, http://www-128.ibm.com/developerworks/webservices/library/ws-tipjax1.html

[6] WS-Security Spec Nearing Completion, http://www.securitypipeline.com/specwatch/ws-security.jhtml

About the Authors

Senthil Kumar K M works as a Technical Specialist with Web Services Centre of Excellence in SETLabs, Bangalore. His current focus is on Syndeo - Web services Management Framework. He has published papers in international conferences like IEEE International Conference of Web services and spoken at various industry forums exclusively on Web services. His current research interests are Web services security, Web services interoperability and Web services Transaction Models. Senthil holds a B.E. (Hons) degree in Computer Science and M.Sc (Hons) degree in Mathematics from the Birla Institute of Technology and Science, Pilani, India. He can be reached at [email protected].

Anshuk Pal Chaudhuri is working as part of the Web Services COE (Center of Excellence) for Infosys Technologies, a global IT consulting firm, and have substantial experience in publishing papers, presenting papers at conferences, and defining standards for SOA and Web services. The Web Services COE specializes in SOA, Web services, and other related technologies. He has done his B.Tech from Kolkata. He has developed and deployed Web services in various J2EE Compliant Servers. His current focus is on Syndeo - Web services Management Framework. His current research interests WS-Security and different open source products. He is also working in different binding frameworks for XML. He can be reached at [email protected].

Vineet Singh is a Software Engineer with Web Services Center of Excellence in SETLabs, Bangalore. His current focus is on Service Oriented Architecture, Web services over CRM. He has also implemented Web services on different application servers and worked on Syndeo - Web services bootstrap framework. He has been working on prevention and detection of XML based denial of service attack on Web services. He can be reached at [email protected].