JAX-WS and Secure Java Web Services using UsernameToken: WS-Security with Metro and WSIT Example

This tutorial focuses on creating secure JAX-WS web service with UsernameToken WS-Security profile by using Metro and WSIT. You will learn how to create , deploy and run JAX-WS UsernameToken web service security example and UsernameToken jax-ws client. We will also create the service-side username and password validation handlers, Configure the client by providing a callback handler for the username and for the password to send the UsernameToken authentication data.

Metro web service stack

As we discussed earlier, Metro is the reference implementation of JAXB 2.x and JAX-WS 2.x Java™ standards. Metro also has extensive support WS-* SOAP security extensions. The WS-* technologies are related to Web Service Security,Reliability, and Transactions.
WSIT or the Web Service Interoperability Technologies (Also known as Project Tango) provides interoperability between Java Web Services and Microsoft’s WCF( Windows Communication Foundation

Metro is bundled with Java SE 6 and above (but requires the newer 2.2.x version of JAX-WS, this is not provided by default in Java 6 and you’ll need to place the newer jaxws-api.jar in your JDK’s endorsed folder) as well as with application servers such as GlassFish, Oracle Weblogic, JBoss 5.x and above Sun Java App server etc.

Metro implements OASIS WS-Security specifications and W3C Policy Standards. Read Metro specifications implementation details to know more about the different specification versions implementation.
The bootstrapping and configuration specifications deals with accessing web service URLs , WSDLs and provides information that are required to build web service clients. Message Optimization Specifications deals with optimized communication between two web service endpoints.

WS-ReliableMessaging specifications deal with system’s ability to deliver messages from point A to point B regardless of network errors and WS-Security specifications targets to secure communication between two web service endpoints.

Related Articles:

• JAX-WS with Attachment – MTOM , XOP and Java Web Service Example using JAX-WS
• SOAP Binding: Difference between Document and RPC Style Web Services
• Java JAX-WS Tutorial: Develop Web Services and Clients (Consumers) Using JAX-WS

In this tutorial, we develop a sample JAX-WS service and client application which include WS-Security with the UsernameToken profile.

Usernametoken ws-security using Metro and WSIT : JAX-WS UsernameToken web service and client examples.

Here we focus on a simple plain-text UsernameToken example using Metro. We will see more secure encrypted versions in the next tutorials.
UsernameToken provides a standard way of representing a username and password pair with WS-Security. Please note that, the plain text username and password is used in production only when it is combined with SSL or WS-Security encryption. That means metro requires either transport-level encryption ( SSL) or other message-level encryption to be in use while using this UsernameToken profile. User Name token will be part of SOAP Header rather than HTTP header

Points to remember when using WS-Security with the UsernameToken profile.

• The custom extensions used to configure WSIT user information differ in the XML namespace on the client and server sides. For client the namespace is “ http://schemas.sun.com/2006/03/wss/client” and for server the XML namespace is “http://schemas.sun.com/2006/03/wss/server”.

• The policy namespace refers http://java.sun.com/xml/ns/wsit/policy

• The WS-Security/UsernameTokens can be configured either directly as part of WSDL document using WS-SecurityPolicy assertions or using separate configuration files. The service side configuration file is named as “wsit-*.xml” and client side configuration file follows the “wsit-client.xml” naming conventions.

• Metro provides two options for server side authentication when UserNameToken profile is used. It can be either container based or via a validation handler class.
  • If it is container based you need to configure the realm, for example if you are using Tomcat container you can configure tomcat-users.xml file to include user credentials to validate the tokens.
  • You can also use validation handler classes as part of the application instead of relying on container realm based default validations.

To try the example below, you need to have IDE such as Eclipse, JDK version 7 (Metro requires the newer 2.2.x version of JAX-WS (jaxws-api.jar) available in Java 7. This is not provided by default in Java 6 and you’ll need to place the newer jaxws-api.jar in your JDK’s endorsed folder) , Metro distribution and Tomcat server 6 or above.

The WS-SecurityPolicy configuration is not very easy and it is recommended to use some IDE such as NetBeans to create them. If you have Netbeans and Glassfish installed, the JAX-WS web service development is pretty easy. You can read the WSIT Netbeans tutorial to learn more.
In this tutorial, I used eclipse and Tomcat so that we can create web service, client and configuration files manually without generating them and deploy and test them on Tomcat.

Create the SEI and the JAX-WS Web Service Implementation class.

The SEI is created and annotated as a web service. It defines three methods. These methods allow the clients to upload images, download images and a simple greetCustomer method.

/*
 * @(#)MyWebServiceIntf.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.service;

import java.awt.Image;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
/**
 * The SEI
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
@WebService(name="MyWebService")
public interface MyWebServiceIntf {

	/**
	 * Web service operation
	 */
	@WebMethod(operationName = "greetCustomer")
	public String greetCustomer(@WebParam(name = "parameter") String parameter);

	@WebMethod(operationName = "retrieveImage")
	public Image retrieveImage(@WebParam(name = "name") String name);

	@WebMethod(operationName = "uploadImage")
	public String uploadImage(@WebParam(name = "file") Image file,
			@WebParam(name = "name") String name);

}

The implementation class is below.

 /*
 * @(#)MyWebService.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.service;

import java.awt.Image;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;

import javax.imageio.ImageIO;
import javax.jws.WebService;
import javax.xml.ws.WebServiceException;

/**
 * The web service implementation class.
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
@WebService()
public class MyWebService implements MyWebServiceIntf {
	 final static String PATH = "D:\\mtomtest\\upload\\";

    /* (non-Javadoc)
	 * @see com.globinch.service.MyWebServiceIntf#greetCustomer(java.lang.String)
	 */
    @Override
    public String greetCustomer(String parameter) {
    	
        return "Hello..." + parameter;
    }
 	/* (non-Javadoc)
	 * @see com.globinch.service.MyWebServiceIntf#retrieveImage(java.lang.String)
	 */
 	@Override
	public Image retrieveImage(String name) {
 		
		try {
			// Create a file object with file name and read the image
			File image = new File(PATH + name);
			return ImageIO.read(image);
		} catch (IOException e) {
			throw new WebServiceException("Download Failed");
		}
	}
	/* (non-Javadoc)
	 * @see com.globinch.service.MyWebServiceIntf#uploadImage(java.awt.Image, java.lang.String)
	 */
	@Override
	public String uploadImage(Image file, String name) {
		
		if (file != null) {
			try {
				File image = new File(PATH + name);
				ImageIO.write((BufferedImage) file, "jpg", image);
			} catch (IOException e) {
				throw new WebServiceException("Upload Failed");
			}
			return "Upload Successful";
		}
		throw new WebServiceException("No data to upload.");
	}
  }

Create the service-side username and password validation handler.

In this article we are using plane text username and passwords. They are not encrypted. The PlainTextPasswordRequest represents the validation request when the password in the username token is in plain text.
PasswordValidationCallback is a callback for Password validation. This callback may be used by an authentication module to employ the password validation facilities of its containing runtime. This Callback would typically be called by a ServerAuthModule during validateRequest processing. In our case, in WSIT configuration file we add the ValidatorConfiguration and indicate our custom validator class name which implements PasswordValidationCallback.PasswordValidator. You can use this validator class to authenticate customers against your own services such as database or external services.

/*
 * @(#) MyServicePasswordValidator.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.service;

import com.sun.xml.wss.impl.callback.PasswordValidationCallback;
/**
 * The plain text password validation class.
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
public class MyServicePasswordValidator implements
        PasswordValidationCallback.PasswordValidator {
	
    public boolean validate(PasswordValidationCallback.Request request)
            throws PasswordValidationCallback.PasswordValidationException {

        PasswordValidationCallback.PlainTextPasswordRequest plainTextRequest 
            = (PasswordValidationCallback.PlainTextPasswordRequest) request;
          if ("myuserid".equals(plainTextRequest.getUsername())
                && "mypassword".equals(plainTextRequest.getPassword())) {
            return true;
        
        }else{
        	throw new PasswordValidationCallback.PasswordValidationException("Invalid credentials provided. Authentication failed");
        }
        
        //return false;
    }
}

sun-jaxws.xml server side configuration file

Now we need a sun-jaxws.xml configuration file. As we already discussed in other articles, sun-jaxws.xml is a proprietary deployment descriptor needed when web services are deployed as a standard WAR archive on a non-Java EE5 servlet container using the SUN’s reference implementation.

If wsdl-location isn’t specified, JAX-WS will create and publish a new WSDL. When the service is developed from Java, it is recommended to omit this attribute.

The web.xml

	MyWebService
	my Web Service
	
		com.sun.xml.ws.transport.http.servlet.WSServletContextListener
	
	
		MyWebServicePort
		com.sun.xml.ws.transport.http.servlet.WSServlet
		1
	
	
		MyWebServicePort
		/
	
	
		60
	
	
		index.html
		index.htm
		index.jsp
		default.html
		default.htm
		default.jsp
	

Configuring usernameToken Security Policy in wsit-service.xml/WSDL file

It is important to note that to implement simple plain-text UsernameToken example on Metro, you need to include appropriate WS-Policy/WS-SecurityPolicy configuration in the WSDL service definition file.
You can either generate the wsdl file using the wsgen tool which is available as part of JDK distribution or you can use the WDL generated by the JAXWS runtime when you deploy your service.
The wsgen tool reads a web service endpoint implementation class (SEI annotated with @WebService annotation) and generates JAX-WS portable artifacts used in JAX-WS web services.
The following command will generate a SOAP 1.2 WSDL

wsgen -wsdl:Xsoap1.2 -d directory -cp myclasspath yourclassfile 

Once you have the WSDL file you can create the server side WSIT configuration file. As we mentioned earlier the server side WSIt configuration file is usually named as “wsit-package.service.xml“, where “package” is the service package and “service” is the service name. This file defines which WSIT technologies are enabled in the web service. Usually you can include these policy information as part of WSDL itself. You can include the policy refrence in <wsdl:binding> section as below.

	
…..

And the policy elements are added as below.

You can both include this as part of wsdl and provide the wsdl-location element in sun-jaxws.xml or you can include the above configurations in wsit-package.service.xml.
In our example we have created wsit-com.globinch.service.MyWebService.xml and the content is as follows.

The location of the WSIT configuration file should be either inside META-INF or under WEB-INF/Classes folder. The JAX-WS runtime will load the site files during deployment. You will see messages similar to the below in the server log files.

INFO: WSSERVLET12: JAX-WS context listener initializing
May 14, 2013 3:32:18 PM [com.sun.xml.ws.policy.parser.PolicyConfigParser]  parse
INFO: WSP5018: Loaded WSIT configuration from file: jndi:/localhost/MyService/WEB-INF/wsit-com.globinch.service.MyWebService.xml.

Now our service is ready for deployment. Once you deploy the service you can access the WSDL file from the URL similar to the below.
http://{host}:{port}/MyService/?wsdl
You will see the WSDL as follows

Now the JAX-WS UsernameToken security web service is deployed and ready to test.

Create JAX-WS UsernameToken client

When you create JAX-WS client application using metro you need to have the following files.

• The service proxy classes
• {wsdl file name}.xml
• wsit-client.xml
• Service client classes.
• CallbackHandler class.

The first step in creating the web service client is to generate the proxy artifacts using wsimport utility. Ofcourse you can always use the IDE tools for generating these client side files.
A sample command is given below

wsimport -keep -XadditionalHeaders http://localhost:8080/MyService/?wsdl

We will create the client classes using the above generated classes. In this application I have created a ServiceInvoker class which invokes the services such as upload image, retrieve image and greet customer. Please note that the client service invoker just picks the image from a physical location and send it to the “uploadImage” service of MyWebService”. Similar way the client also requests an image from server and the server sends back the image to the client. The client saves the image in a physical location.

UsernameToken jax-ws client Example

/*
 * @(#)Client.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.client;

import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Map;

import javax.imageio.ImageIO;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.Service;

import com.globinch.service.MyWebService;
/**
 * The web service client service invoker class.
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
public class Client {
	private static URL url = null;
	private static Service service = null;
	private static final String PATH = "D:\\mtomtest\\download\\";
	
	public Client() {
		try {
			url = new URL("https://localhost:8443/MyService/?wsdl");
			QName qname = new QName("http://service.globinch.com/",
					"MyWebServiceService");
			service = Service.create(url, qname);
		} catch (Exception e) {
			e.printStackTrace();
		}

	}
       /**
	 * Upload image
	 * @return String
	 */
	public String uploadImage() {
		try {
			MyWebService myService = service.getPort(MyWebService.class);
			File file = new File(PATH + "11841.jpg");
			BufferedImage imageToUpload = null;
			try {
				imageToUpload = ImageIO.read(file);
			} catch (IOException e) {
				e.printStackTrace();
			}
			double d = Math.random();
			byte[] imageInByte = null;
			try {
				ByteArrayOutputStream baos = new ByteArrayOutputStream();
				ImageIO.write(imageToUpload, "jpg", baos);
				baos.flush();
				imageInByte = baos.toByteArray();
				baos.close();
			} catch (IOException e) {
				System.out.println(e.getMessage());
			}
			// now upload the image
			myService.uploadImage(imageInByte, "ImageFromClient" + d + ".jpg");
			String imageToDownload = d+"";
						
			return imageToDownload;
		} catch (Exception e) {

			e.printStackTrace();
		}
		return null;
	}
	/**
	 * Download the uploaded image
	 * @param imageName
	 * @return String
	 */
	public String downloadImage(String imageName) {
		try {
			MyWebService myService = service.getPort(MyWebService.class);
			// lets now download the uploaded image
			byte[] downloadedImage = myService
					.retrieveImage("ImageFromClient" + imageName + ".jpg");
			File imageFromServer = new File(PATH + "ImageFromServer" + imageName
					+ ".jpg");
			try {
				FileOutputStream fileOuputStream = new FileOutputStream(
						imageFromServer);
				fileOuputStream.write(downloadedImage);
				fileOuputStream.close();
				
			} catch (IOException e) {
				e.printStackTrace();
			}
			return "success";
		} catch (Exception e) {

			e.printStackTrace();
		}
		return null;

	}
	/**
	 * Greet the customer
	 * @param name
	 * @return String
	 */
	public String greet(String name) {
		try {
			MyWebService myService = service.getPort(MyWebService.class);
			String message = myService.greetCustomer(name);
			System.out.println(message);
			return message;

		} catch (Exception exception) {
			exception.printStackTrace();
		}
		return "empty string";
	}

	public static void main(String[] args) {

		try {
			new Client().greet("Some user");
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
}

Client side WSIT configuration file

The WSIT policy configuration needs to be applied using the wsit configuration file. On the client side, a file with the name of wsit-client.xml is used for the WSIT configuration. You also need to create a service xml file. The name for the service xml file is usually will be {wsdl file name}.xml.
The wsit-client.xml imports the service xml file. In effect these two files are simply a copy of the service WSDL with its wsp:Policy element modified to provide client-side configuration information such as callback handler etc.

MyWebServiceService.xml

wsit-client.xml

CallbackHandler to manage username and password at client side

An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords. For example in this particular case the underlying service needs a username and password to authenticate a user, it uses a NameCallback and PasswordCallback.
In MyWebServiceService.xml the callback handler is configured in the <sc:CallbackHandlerConfiguration> section. The callback handler must implement javax.security.auth.callback.CallbackHandler interface.

* @(#)MyWebServiceCallbackHandler.java
 * @author Binu George
 * Globinch.com
 * copyright http://www.globinch.com. All rights reserved.
 */
package com.globinch.client;

import java.io.IOException;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.callback.UnsupportedCallbackException;
/**
 * The callback handler class to manage username and password.
 * @author Binu George
 * @since 2013
 * @version 1.0
 */
public class MyWebServiceCallbackHandler implements CallbackHandler {
   
	   public void handle(Callback[] callbacks) throws IOException,
	      UnsupportedCallbackException {
	         for (int i = 0; i < callbacks.length; i++) {
	            if (callbacks[i] instanceof NameCallback) {
	               NameCallback nc = (NameCallback) callbacks[i];
	               nc.setName("myuserid");
	            } else if (callbacks[i] instanceof PasswordCallback) {
	               PasswordCallback pc = (PasswordCallback) callbacks[i];
	               pc.setPassword("mypassword".toCharArray());
	            } else {
	               throw new UnsupportedCallbackException(callbacks[i],
	                  "Unrecognized Callback");
	            }
	         }
	   }
	}

You can create a web project to test the above example. You can add a servlet component to invoke the Client.java methods along with a JSP page to upload and download images.

As we mentioned in the beginning of the article, since the username and password is being sent as plain text ensure that the endpoint URL is using HTTPS/SSL to encrypt the messages if deployed in production.

References:

• Introduction to Metro
• OASIS WS-SecurityPolicy Examples
• OASIS Web Services Security (WSS) TC
• SOAP stack space comparison
• GlassFish Tools Bundle For Eclipse
• WSIT Example applications
• wsgen
• interface CallbackHandler

Incoming search terms:

• JAX-WSandSecureJavaWebServicesusingUsernameToken:WS-SecuritywithMetroandWSIT
• jax ws security