Webservices WS security WSS

WS-Security (Web Services Security, short WSS) is a flexible and feature-rich extension to SOAP to apply security to web services. It is a member of the WS-* family of web service specifications and was published by OASIS.

The protocol specifies how integrity and confidentiality can be enforced on messages and allows the communication of various security token formats.  Its main focus is the use of XML Signature and XML Encryption to provide end-to-end security.
The specification allows a variety of signature formats, encryption algorithms and multiple trust domains, and is open to various security token models, such as:

• X.509 certificates,
• Kerberos tickets,
• UserID/Password credentials,
• SAML Assertions, and
• custom-defined tokens.

WS-Security incorporates security features in the header of a SOAP message. Below is a sample program on how to incorporate ws-security in SOAP message header. I am using the UserID/Password credentials.

import java.io.IOException;

import java.net.URL;

import java.util.Date;

import javax.xml.soap.MessageFactory;

import javax.xml.soap.Name;

import javax.xml.soap.SOAPBody;

import javax.xml.soap.SOAPConnection;

import javax.xml.soap.SOAPConnectionFactory;

import javax.xml.soap.SOAPElement;

import javax.xml.soap.SOAPEnvelope;

import javax.xml.soap.SOAPException;

import javax.xml.soap.SOAPFactory;

import javax.xml.soap.SOAPHeader;

import javax.xml.soap.SOAPHeaderElement;

import javax.xml.soap.SOAPMessage;

import javax.xml.soap.SOAPPart;

public class WebservicesSecurityService {

    public static final String SECURITY = "Security";

    public static final String WSSE_NS = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";

    public static final String WSSE_PREFIX = "wsse";

    public static final String WSU_NS = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";

    public static final String WSU_PREFIX = "wsu";

    public static final String PAL_NS = "http://palin.com";

    public static final String PAL_PREFIX = "pal";

    public static final String PASSWORD_TEXT_TYPE = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText";

    public static final String ENCODING_TYPE = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary";

    public static final String USERNAME = "UserName";

    public static final String PASSWORD = "Password";

    public static final String WEBSERVICE_URL = "http://localhost:8080/axis2/services/PalinServ?wsdl";

    public static Object makeRequest(int xml) throws IOException, SOAPException, Exception{

    SOAPMessage soapMessage = MessageFactory.newInstance().createMessage();

        SOAPPart soapPart = soapMessage.getSOAPPart();

        SOAPEnvelope soapEnvelope = soapPart.getEnvelope();

        SOAPFactory soapFactory = SOAPFactory.newInstance();

       

        SOAPBody soapBody = soapEnvelope.getBody();

        soapEnvelope.addNamespaceDeclaration("xsi", "http://www.w3.org/2001/XMLSchema-instance");

        soapEnvelope.addNamespaceDeclaration("xsd", "http://www.w3.org/2001/XMLSchema");

        soapEnvelope.addNamespaceDeclaration("soap", "http://www.w3.org/2003/05/soap-envelope");

        soapEnvelope.addNamespaceDeclaration(PAL_PREFIX, PAL_NS);

        

        SOAPHeader soapHeader = soapMessage.getSOAPHeader();

        

        if (soapHeader == null)

        soapHeader = soapEnvelope.addHeader();

           

        SOAPHeaderElement elHeader = soapHeader.addHeaderElement(

        soapEnvelope.createName("Security", WSSE_PREFIX, WSSE_NS));

        elHeader.setMustUnderstand(false);

        Name usernameNameToken = soapEnvelope.createName("UsernameToken", WSSE_PREFIX, WSSE_NS);

        SOAPElement elUnToken = elHeader.addChildElement(usernameNameToken);        

        elUnToken.setAttribute("wsu:Id","UsernameToken-2");   

        elUnToken.setAttribute("xmlns:wsu", WSU_NS); 

        

        Name usernameName = soapEnvelope.createName("Username", WSSE_PREFIX, WSSE_NS);

SOAPElement usernameMsgElem = soapFactory.createElement(usernameName);

usernameMsgElem.addTextNode(USERNAME);

elUnToken.addChildElement(usernameMsgElem);

   

Name passwordName = soapEnvelope.createName("Type", WSSE_PREFIX, WSSE_NS);

SOAPElement passwordMsgElem = soapFactory.createElement("Password", WSSE_PREFIX, WSSE_NS);

passwordMsgElem.addAttribute(passwordName, PASSWORD_TEXT_TYPE);

  passwordMsgElem.addTextNode(PASSWORD);

  elUnToken.addChildElement(passwordMsgElem);

   

  Name nonceName = soapEnvelope.createName("EncodingType", WSSE_PREFIX, WSSE_NS);

  SOAPElement nonceMsgElem = soapFactory.createElement("Nonce", WSSE_PREFIX, WSSE_NS);

  nonceMsgElem.addAttribute(nonceName, ENCODING_TYPE);

  nonceMsgElem.addTextNode("u6r/JZ+Y73epyvmENjBeZQ==");

  elUnToken.addChildElement(nonceMsgElem);

   

  SOAPElement createdElem = elUnToken.addChildElement("Created", WSU_PREFIX , WSU_NS);

  createdElem.addTextNode(String.valueOf(new Date()));
  soapBody.addChildElement(WebservicesSecurityService.makeOperation(xml));

        soapMessage.writeTo(System.out);

    return soapMessage;    

    }

    public static void callService() throws IOException, Exception {

SOAPMessage soapMessageRequest = (SOAPMessage) WebservicesSecurityService.makeRequest(12321);

  SOAPConnectionFactory sfc = SOAPConnectionFactory.newInstance();

  SOAPConnection connection = sfc.createConnection();

  URL endpoint = new URL(WEBSERVICE_URL);

  SOAPMessage soapMessageResponse = connection.call(soapMessageRequest, endpoint);

  soapMessageResponse.writeTo(System.out);

  connection.close();

    }

    public static SOAPElement makeOperation(int number) throws SOAPException{

        SOAPFactory soapFactory = SOAPFactory.newInstance();

        SOAPElement isPalin = soapFactory.createElement("isPalindrome", PAL_PREFIX, PAL_NS);

        SOAPElement args = isPalin.addChildElement("args0", PAL_PREFIX, PAL_NS);

        args.addTextNode(String.valueOf(number));

return isPalin;

    }

    public static void main(String[] args) {

  try {

  WebservicesSecurityService.callService();

  } catch (Exception e) {

  e.printStackTrace();

  }

    }

}

This is how the generated security request looks:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pal="http://palin.com" xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header>
<wsse:Security
 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
 SOAP-ENV:mustUnderstand="0">
 <wsse:UsernameToken
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="UsernameToken-2">
<wsse:Username>UserName</wsse:Username>
<wsse:Password
wsse:Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
<wsse:Nonce
wsse:EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">u6r/JZ+Y73epyvmENjBeZQ==</wsse:Nonce>
<wsu:Created>Fri Sep 28 17:45:38 CDT 2012</wsu:Created>
 </wsse:UsernameToken>
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<pal:isPalindrome>
<pal:args0>12321</pal:args0>
</pal:isPalindrome>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Testing webservices manually with raw soap request

This method is useful when you are required to generate a SOAP request manually without using any tools like axis2, jaxrpc etc. Here we manually create the request using java, no other jar files are required.

Pre-requisite: 

• Jdk 1.6.0_31 installed
• Up and running webservice (see my post http://helptodeveloper.blogspot.com/2012/09/creating-basic-webservice-example.html on how to create your own webservice up and running within minutes). I am going to use my Palindrome webservice, the link is given above.

First we have to identify the request which we are going to create (you can identify your request using SOAP-UI here http://helptodeveloper.blogspot.com/2012/09/testing-webservice-or-wsdl-with-soap-ui.html). I am using the PalinServ webservice, so below is the request.

Request:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:pal="http://palin.com">
   <soap:Header/>
   <soap:Body>
      <pal:isPalindrome>
         <pal:args0>123454321</pal:args0>
      </pal:isPalindrome>
   </soap:Body>
</soap:Envelope>


Java code for request creation:

package com.service.palinImpl;


import java.io.IOException;
import java.net.URL;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPConnection;
import javax.xml.soap.SOAPConnectionFactory;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPHeader;
import javax.xml.soap.SOAPMessage;
import javax.xml.soap.SOAPPart;



public class PalindromeServiceImpl {
public static final String PAL_NS = "http://palin.com";
public static final String PAL_PREFIX = "pal";
public static final String WEBSERVICE_URL = "http://localhost:8080/axis2/services/PalinServ?wsdl";

public static Object makeRequest(SOAPElement request) throws IOException, SOAPException, Exception{
    SOAPMessage soapMessage = MessageFactory.newInstance().createMessage();
     SOAPPart soapPart = soapMessage.getSOAPPart();
     SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
     SOAPBody soapBody = soapEnvelope.getBody();
     soapEnvelope.addNamespaceDeclaration(PAL_PREFIX, PAL_NS);
     SOAPHeader soapHeader = soapMessage.getSOAPHeader();
     if (soapHeader == null){
      soapHeader = soapEnvelope.addHeader();
     }
     soapBody.addChildElement(request);
     soapMessage.writeTo(System.out);
    return soapMessage;    
    }

public static void callService() throws IOException, Exception {
SOAPElement bodyElem = PalindromeServiceImpl.makePalindromeOperation(123454321);
SOAPMessage soapMessageRequest = (SOAPMessage) PalindromeServiceImpl.makeRequest(bodyElem);
SOAPConnectionFactory sfc = SOAPConnectionFactory.newInstance();
SOAPConnection connection = sfc.createConnection();
URL endpoint = new URL(WEBSERVICE_URL);
   SOAPMessage soapMessageResponse = connection.call(soapMessageRequest, endpoint);
   soapMessageResponse.writeTo(System.out);
   connection.close();
}

/*<pal:isPalindrome>
         <pal:args0>123454321</pal:args0>
      </pal:isPalindrome> */
public static SOAPElement makePalindromeOperation(int number) throws SOAPException{
        SOAPFactory soapFactory = SOAPFactory.newInstance();
        SOAPElement isPalin = soapFactory.createElement("isPalindrome", PAL_PREFIX, PAL_NS);
        SOAPElement args = isPalin.addChildElement("args0", PAL_PREFIX, PAL_NS);
        args.addTextNode(String.valueOf(number));
return isPalin;
}

public static void main(String[] args) {
try {
PalindromeServiceImpl.callService();
} catch (Exception e) {
e.printStackTrace();
}
}
}

Below are the Request and Response after running the above program:

Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pal="http://palin.com">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<pal:isPalindrome>
<pal:args0>123454321</pal:args0>
</pal:isPalindrome>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Response
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:isPalindromeResponse xmlns:ns="http://palin.com">
<ns:return>Palindrome</ns:return>
</ns:isPalindromeResponse>
</soapenv:Body>
</soapenv:Envelope>

Hope this helped :)

Testing Webservice or wsdl with SOAP UI

Testing a webservice is very easy and it can be done within minutes using SOAP UI.

The best thing about SOAP UI is that it’s a free and open source application, meaning anyone can have free access to the full source code. Because soapUI is Java-based, it works on most operating systems, including Windows, Linux and Mac. It also means you can modify or customize it any way you like. And you can find everything you need to know about soapUI at its official site soapUI.org.

Pre-requisite: We need a wsdl and that too up and running on a server. You can create your own wsdl file from my previous post below. 

http://helptodeveloper.blogspot.com/2012/09/creating-basic-webservice-example.html


 To check whether the service is up or not, you can just type the wsdl url in you web browser (there should be ?wsdl at the end of your url), you should see an xml file in your browser.

example of wsdl url: http://<host > : < port>/axis2/services/PalinServ?wsdl

Download SOAP-UI (I used the 4.5.1 version for this example). Once you have installed and run it, create a new project as below.

I am using a wsdl from my previous post http://helptodeveloper.blogspot.com/2012/09/creating-basic-webservice-example.html which returns whether the given number is Palindrome or not..

Give a name to the project and give our wsdl url in the section provided, and check the 'Create Requests' and 'Create TestSuite' (most often used by testers) and click OK button.

NOTE: Make sure our service is up and RUNNING.

We can see our operations in the next window, make selections as shown below and click on OK button.

Provide a name for TestSuite.

 

It will ask for both SOAP 1.1 and SOAP 1.2, repeat the same steps for SOAP 1.2 also.

Now click on any request from either SOAP 1.1 or SOAP 1.2, you can see the request how exactly it is going to send to our service using SOAP. Shown below is the request from the SOAP 1.2 request.

Give parameters in the args0 tag in place of the "?" and click on the green play/run button in the left top corner of window Request 1. Then you can see the webservice response in the right most window of the Request 1.

Here is the output for a non-palindrome number.

Below is the output for an invalid input, you might be wondering how the SOAP UI has identified it as an "Invalid value"!

We can find the reason for the above fault code in the wsdl file where the data type is defined as int, see below the snippet from wsdl file

<xs:element minOccurs="0" name="args0" type="xs:int"/> 

Creating basic webservice example

Basic webservice example the manual way using axis2 and testing using SOAP UI

Apache Axis2 is a Web Service engine for deploying the web services, you can find more information about it at its official http://axis.apache.org/axis2/java/core/.

Pre-requisites:

• Java 1.5 or greater installed (I am using 1.6 here)
• Apache Tomcat 6 or above installed
• Apache Axis2 web archive (.war.zip file) from the official site download page http://axis.apache.org/axis2/java/core/download.cgi (I am using 1.6.2 here)

Now unzip and copy axis2.war into Tomcat's webapps directory, start the Tomcat server and navigate to http://localhost:8080/axis2, you should see the below welcome page

For accessing the Administration page you need the credentials admin/axis2 for doing all the necessary administrative activities.

When we click on services link you can see one Version service which dislpays the version which comes by default in the axis2 war bundle.

There are two types of approaches while developing web services, they are:

a) Code first (also called as bottom-up approach): In this approach we will start programming the classes and business logic as java code and then generate the web service contract(wsdl)

b) Contract first (also called as top-bottom approach): In this approach we will start generating class stubs from the WSDL.

We will go with the code first approach which is the most preferred way so let us quickly get into the example

1) Create a project with package and META-INF folders within it as shown below

2) Write the service class first through which we are going to service, let us write a program which validates whether the given number is a palindrome or not PalindromeService.java.

package com.palin;

public class PalindromeService {

  public String isPalindrome(int number) {

    String palin=null;

    try {

      int tempNumber = number;

      int reverse = 0;

      for (int i = 0; i <= number; i++) {

        int temp = number % 10;

        number = number / 10;

        reverse = reverse * 10 + temp;

        i = 0;

      }

      if (tempNumber == reverse) {

        palin="Palindrome";

      } else {

        palin="Not Palindrome!";

      }

    } catch (Exception e) {

      palin="Invalid number!";

    }

    return palin;

  }

}

Create the service descriptor i.e, services.xml (and place in location:WEB-INF)

<service name="PalinServ">

<transports>

    <transport>http</transport>

</transports>

<parameter name="ServiceClass" locked="xsd:false">com.palin.PalindromeService</parameter>

<operation name="isPalindrome">

    <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"

class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>

</operation>

</service>

The <service> tag is used to define the services, we can even declare the scope for it. We can have multiple services in single services.xml file.

The <transport> tag is used to declare which senders/listeners for SOAP over different protocols like FTP, SMTP, HTTPS, HTTP etc. Here I have used just http. If we are not going to declare any transport, then all the transports that are available in the default axis2.xml file are accepted by default. These can be found in the %TOMCAT_HOME%\webapps\axis2\WEB-INF\conf\axis2.xml with <transportSender> tag.

The <parameter> tag is used to define our service class along with the package name.

The <operation> tag is used to define our method which we are going to expose. All the methods which we wish to publish or do the service are treated as operations in the service descriptor, here isPalindrome is our operation.

RPCMessageReceiver is the messageReceiver which is the most commonly used one for receiving messages.

3) Now we are going to compile the class, create an axis archive file (.aar) as shown below

4) Now copy the PalinServ.aar into webapps/axis2/WEB-INF/services directory and restart your Tomcat and check this url http://localhost:8080/axis2/services/listServices we should be able to see our service along with the default Version service as shown below.

We can see our service name under Service Description section and our method under Available Operations section as shown above.

We can see the .wsdl file url under the Service EPR (endpoint) section but we need to append ?wsdl to its end like http://localhost:8080/axis2/services/PalinServ?wsdl

As the previous version should not get effected, it supports all its previous ones SOAP 1.1, SOAP 1.2 that is the reason why you will be seeing more than one endpoints.

Now, for testing whether you webservice is working or not, see this post http://helptodeveloper.blogspot.com/2012/09/testing-webservice-or-wsdl-with-soap-ui.html.

If you don't have any tools for testing your webservice; you can do manually, look in this post http://helptodeveloper.blogspot.com/2012/09/testing-webservices-manually-with-raw.html on how to test.