Writing GSI enabled Web Services

Quick links: Introduction | Download GSI Code | Develop Services | Further Info

1. Introduction

This document is intended as a guide for UK eScience users to develop GSI-enabled web services using code supplied by Argonne National Laboratory. It describes the motivation behind using GSI web services, how to obtain and install the code, and how to write a GSI Web service using the Axis toolkit from Apache.

This document is heavily based on the work of Jarek Gawor and Jason Novotny (credits).

This document will be updated as the web services world changes - please send any additions to N.ChueHong@epcc.ed.ac.uk for inclusion.

Still to be added:

Last update on 17th April 2002.

2. Overview

The Grid is a term commonly used to describe a distributed computing infrastructure which will allow "coordinated resource sharing and problem solving in dynamic, multi-institutional virtual organizations" . The protocols and middleware to enable this Grid infrastructure have been developed by a number of initiatives, most notably the Globus Project .

Web Services are simply applications that interact with each other using Web standards, such as the HTTP transport protocol and the XML family of standards. In particular, Web Services use the SOAP messaging standard for communication between service and requestor. They should be self-describing, self-contained and modular; present a platform and implementation neutral connection layer; and be based on open standards for description, discovery and invocation.

The Grid Security Infrastructure (GSI) is based on the Generic Security Services API (GSS-API) and uses an extension to X509 certificates to provide a mechanism to authenticate subjects and authorise resources. It allows users to benefit from the ease of use of a single sign-on mechanism by using delegated credentials, and time-limited proxy certificates. GSI is used as the security infrastructure for the Globus Toolkit.

Recently, a new proposal for an Open Grid Services Architecture (OGSA) was announced which marries the Grid and Web Services to create a new Grid Services model. One problem, which has not yet been explicitly addressed, is that of security. A possible solution is to use a suitably secure transport binding, e.g. TLS, and extend it to incorporate appropriate support for proxy credentials.

It would be useful to test out some of the principles of Grid Services using the currently available frameworks and tools for developing Web Services. Unfortunately, no standards currently exist for implemented proxy credential support to provide authenticated communication between web services. A number of XML/Web Services security standards are currently in development, e.g. XML Digital Signatures, SAML, XKMS, XACML, but the remainder of this document describes an approach proposed by ANL to use GSI over an SSL link.

It should be noted that the security mechanism currently used will almost certainly change. The extensions to Tomcat and Axis are not supported by ANL and should be considered to be experimental.

3. Obtaining the software

You will require the following software packages to develop GSI-enabled web services:

You will also require Argonne's GSI extensions to Tomcat and Axis (gsicatalina.jar and gsiaxis.jar), as well as the IAIK security libraries (iaik_ssl.jar, iaik_jce_full.jar, iaik_javax_crypto.jar). The IAIK security libraries are free for evaluation and educational use but a license fee is required for commercial use.

The following bundles contain Argonne's GSI extensions, the various Java security and cryptography libraries and the Globus Java CoG kit, so you can simply copy the relevant jars to your Axis/Tomcat installation as described below:

Please do not redistribute these bundles outside of your project group, as this code is still experimental.

Note that due to a change in the Axis APIs, a different version of the GSI extensions is required if you are using Axis Alpha 3 or Axis Beta 1.

The examples in this document used the following versions of the software:

4. Installing the software

4.1. Install Tomcat

4.2. Deploy Axis on Tomcat

Note that a bug in Tomcat means that any jars containing java.* or javax.* classes will not be executed if there are in the webapps/ tree. Instead, copy the jars to Tomcat's common/lib directory. In Axis alpha 3 this applies to axis.jar and wsdl4j.jar; in Axis beta 1 this applies to jaxrpc.jar and wsdl4j.jar.

4.3. Install libraries to provide GSI support for Tomcat

4.4. Deploy GSI support in Tomcat

4.5. Install libraries to provide GSI support for Axis

4.6. Set your CLASSPATH correctly

4.7. Start the GSI enabled Tomcat/Axis server

Check the logs in Tomcat's logs/ directory to ensure the server started correctly. In particular check that:

5. Writing a GSI enabled Web Service

5.1. Implementing the service

The extensions made to Tomcat allow us to receive credentials through a transport-level security mechanism. Tomcat exposes these credentials, and Axis makes them available as part of the MessageContext.

Alpha 3 version

Let's assume we already have a web service called MyService with a single method, myMethod. When a SOAP message request comes in over the GSI httpg transport, the Axis RPC despatcher will look for the same method, but with an additional parameter: the MessageContext. So we can write a new myMethod which takes an additional argument, the MessageContext.

This can be illustrated in the following example:

package org.globus.example;

import org.apache.axis.MessageContext;
import org.globus.axis.util.Util;

public class MyService {

   // The "normal" method
   public String myMethod(String arg) {
      System.out.println("MyService: http request\n");
      System.out.println("MyService: you sent " + arg);
      return "Hello Web Services World!";

   // Add a MessageContext argument to the normal method
   public String myMethod(MessageContext ctx, String arg) {
      System.out.println("MyService: httpg request\n");
      System.out.println("MyService: you sent " + arg);
      System.out.println("GOT PROXY: " + Util.getCredentials(ctx));
      return "Hello Web Services World!";


Beta 1 version

In the Beta 1 version, you don't even need to write a different method. Instead the Message Context is put on thread local store. This can be retrieved by calling MessageCOntext.getCurrentContext():

package org.globus.example;

import org.apache.axis.MessageContext;
import org.globus.axis.util.Util;

public class MyService {

   // Beta 1 version
   public String myMethod(String arg) {
      System.out.println("MyService: httpg request\n");
      System.out.println("MyService: you sent " + arg);

      // Retrieve the context from thread local
      MessageContext ctx = MessageContext.getCurrentContext();
      System.out.println("GOT PROXY: " + Util.getCredentials(ctx));
      return "Hello Web Services World!";


Part of the code provided by ANL in gsiaxis.jar is a utility package which includes the getCredentials() method. This allows the service to extract the proxy credentials from the MessageContext.

5.2. Deploying the service

Before the service can be used it must be made available. This is done by deploying the service. This can be done in a number of ways:

  1. Use the Axis AdminClient to deploy the MyService classes.
  2. Add the following entry to the server-config.wsdd file in WEB-INF directory of axis on Tomcat:
      <service name="MyService" provider="java:RPC">
       <parameter name="methodName" value="*"/>
       <parameter name="className" value="org.globus.example.MyService"/>

6. Writing a GSI enabled Web Service client

As in the previous example, this is very similar to writing a normal web services client. There are some additions required to use the new GSI over SSL transport:

Here's an example which can be used to call the service you wrote in the last section:

package org.globus.example;

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import org.apache.axis.encoding.XMLType;
import org.apache.axis.configuration.SimpleProvider;
import org.apache.axis.utils.Options;
import org.apache.axis.AxisFault;
import org.apache.axis.SimpleTargetedChain;
import org.apache.axis.transport.http.HTTPSender;

import org.globus.axis.transport.GSIHTTPSender;
import org.globus.axis.transport.GSIHTTPTransport;
import org.globus.axis.util.Util;

import org.globus.security.auth.SelfAuthorization;
import org.globus.security.GlobusProxy;

import javax.xml.rpc.namespace.QName;
import javax.xml.rpc.ParameterMode;

public class Client
    public static void main(String [] args)


        try {
            Options options = new Options(args);
            String endpointURL = options.getURL();
            String textToSend;

            // Parse the arguments for text to send
            args = options.getRemainingArgs();
            if ((args == null) || (args.length < 1)) {
                textToSend = "";
            } else {
                textToSend = args[0];

            // Set up transport handler chains and deploy 
	    SimpleProvider provider = new SimpleProvider();
	    SimpleTargetedChain c = null;

	    c = new SimpleTargetedChain(new GSIHTTPSender());
	    provider.deployTransport("httpg", c);

	    c = new SimpleTargetedChain(new HTTPSender());
	    provider.deployTransport("http", c);
	    // Load globus proxy
	    GlobusProxy proxy = GlobusProxy.getDefaultUserProxy();

            // Create a new service call
            Service  service = new Service(provider);
            Call     call    = (Call) service.createCall();

	    // Set globus credentials
	    // Set authorization type
			     new SelfAuthorization(proxy));
	    // Set gsi mode

            // Set the address of the service (from cmd line arguments)
            call.setTargetEndpointAddress( new java.net.URL(endpointURL) );

            // Set the name of the method we're invoking
	    call.setOperationName(new QName("MyService", 

            // Setup a target parameter
            call.addParameter( "arg1", 

            // Set the return type
	    call.setReturnType( XMLType.XSD_STRING );

            // Invoke the method, passing in the value of "arg1"
            String ret = (String) call.invoke( new Object[] { textToSend } );

            // Print out the returned value
            System.out.println("MyService returned: " + ret);

        } catch (Exception e) {
	    if ( e instanceof AxisFault ) {
	    } else

You can invoke this client by running:
java org.globus.example.Client -l httpg:// "Hello!"
assuming that you are running the client on the same machine (localhost) as the Axis/Tomcat server, and that you've installed Axis in the webapps/axis directory of Tomcat.

If you examine logs/catalina.out you should see the messages from the Client received by the service, as well as the proxy credentials.

7. Descriptions of the GSI extensions to Tomcat and Axis

Coming soon...

8. Further reading and References

To be added...

9. Credits

Jason Novotny (LBL, JDNovotny@lbl.gov) implemented GSI extensions to Apache SOAP and Tomcat. Some of this code remains in this distribution.

Jarek Gawor (ANL, gawor@mcs.anl.gov) implemented the GSI extensions to Apache Axis and Tomcat distibuted on this page. Jarek also wrote the original README upon which this document is based.

10. Corrections and Updates

Please send any corrections or updates to this document to N.ChueHong@epcc.ed.ac.uk, as well as any requests for the source code to the GSI extensions to Tomcat and Axis.

It is not yet clear who will support this code in the UK, and to what extent. In the meantime, I will attempt to provide a basic level of support via email. Please bear in mind that I will not always be able to respond immediately, or indeed solve your problem - though I will collate a list of common problems (and any solutions found) on this web page.

Webpage maintained by Neil Chue Hong ( page accesses)