Web Service Delegation via MyProxy

National Center for Supercomputing Applications

University of Illinois at Urbana-Champaign

MyProxy > Docs > Developer's Guide > Web Service Delegation Example

Motivation

Sometimes it is desirable to have an entity perform some action on your behalf. For example, there might exist a web service front end to a GridFTP client. You might want the web service to use GridFTP to transfer data on your behalf, in essence performing the action as you. In order to do this, you need to delegate a credential to the web service front end. This delegated proxy credential contains your user certificate, not your user private key, but still allows the web service to act as you.

Currently, there are a few solutions out there to this problem.

Globus Toolkit 4.0 - If you are willing to use the GT4 web service environment, you can use its built-in delegation service. Its advantage is that other GT4 web services are built using this delegation service, so you get a lot of tools with delegation support "for free". Its disadvantage is that you need to retrofit any existing web services to use the GT4 environment, which can be difficult.
EGEE's gLite - The EGEE effort has created gLite, Lightweight Middleware for Grid Computing. It, too, provides a delegation service implemented as a web services portType. Its advantange is that minimal changes to existing web services need to be made to utilize this delegation service. Its disadvantage is that the delegation service is bundled as an integral component of the gLite toolkit, which can be difficult to deploy and use as a stand alone component.
CoG Kit - The Commodity Grid (CoG) Kit has a Java toolkit for rapid grid application development that is used by the Globus Toolkit. There is an extension for Tomcat which allows for a GSI-enabled secure connection between client and web service. This extension also allows for a form of credential delegation, sometimes referred to as pre-WS (Web Services) in the Globus Toolkit. It uses a non-standard protocol "httpg://" which is a GSI-extended https connection. After the SSL handshake portion of the https connection, the credential is delegated "over the wire". Its advantage is that no extra delegation service provider is necessary as delegation occurs as part of the SSL handshake. Its disadvantage is that the httpg protocol is being dropped from future versions of the toolkit, and it currently works only with the Tomcat web application server. See this page for more details.

MyProxy provides yet another solution to the problem of delegating credentials. The built-in functions put() and get() provide for transparent delegation of credentials to/from a MyProxy server.

High-level Explanation

Reminder: A credential consists of both a certificate and a private key.

In the image above, a Java Client needs to delegate a credential to a Web Service so that the web service can act on the client's behalf. Using a MyProxy server, we can delegate the credential using the following procedure.

PUT - The Java client generates a random username and passphrase for the credential to be delegated. It then does a MyProxy put(credential,username,passphrase,lifetime) to the MyProxy server. Behind the scenes, the following occurs between the Java client and the MyProxy server.
1. The put() request is authenticated via TLS (Transport Layer Security). The passphrase is not used for put() authentication, but will be used later to authenticate get() requests.
2. The MyProxy server generates a public/private key pair and sends a certificate signing request (CSR) to the client.
3. The client signs the CSR with its private key and returns a proxy certificate, which contains the public key from the CSR and the corresponding certificate chain.
4. The MyProxy server stores the credential and returns a standard "response" message indicating the success/failure of storing the credential.
NOTIFY - Upon successful storage of the credential, the Java client notifies the web service. Typically, this involves a single method call to a user-defined portType. The method call would need to send the hostname and port number of the MyProxy server holding the credential, the username and passphrase used to store the credential, and perhaps the lifetime of the credential (which should be a short value).
GET - Using the information passed to it from the Java client, the web service retrieves the credential from the MyProxy server with a MyProxy get(username,passphrase,lifetime) call. This is an "anonymous" MyProxy function because no local credential is used for the call. Behind the scenes, the following occurs between the web service and the MyProxy server.
1. Using the given username, the MyProxy server locates the credential and verifies it with the given passphrase. If the username/passphrase validates, then the server indicates success to the client.
2. The web service generates a public/private key pair and sends a CSR to the MyProxy server.
3. The MyProxy server signs the CSR with the private key of the stored credential and returns a proxy certificate, which contains the public key of the CSR and the corresponding certificate chain.

Once the web service has a delegated proxy credential, it can perform other services on the behalf of the Java client.

Installing The Example Web Service

Quick Link: MyProxyDelegatee.jws (web service)

For your web service application server, you are going to use Tomcat and Axis. If you already have Tomcat 5.x or higher and Axis 1.2 or higher, you probably only need the CoG Kit libraries. Here are some detailed instructions to get you up and running.

Install Java
Tomcat requires Java to run. You can use either Java 1.4.2 or Java 1.5.0 (a.k.a. J2SE 5.0). These instructions assume you are using a Sun JVM. If you don't have Sun's verison of Java, you can download Sun's Java 2 Platform Standard Edition 5.0. Make sure you get the JDK (J2SE Development Kit) 5.0 Update 6. You can install Java just about anywhere you like. Just make sure to set the JAVA_HOME environment variable to point to the installation location. You may also want to add the "bin" directory to your PATH. For example, in the "bash" shell under *nix, you would type the following commands:
```
  export JAVA_HOME=/opt/jdk1.5.0_06
  export PATH=$PATH:$JAVA_HOME/bin 
```
Install Tomcat
For the web application server, you will be using Tomcat. You should be able to use Tomcat 5.0.X or 5.5.X. For the purposes of these instructions, let's assume Tomcat 5.5.17. You will need to get at least the "Core" package. Other packages of interest which are available include "Deployer", "Administration Web Application", and "JDK 1.4 Compatibility". You can install Tomcat just about anywhere you like. Just make sure to set the CATALINA_HOME environment variable to point to the installation location. You may also want to add the "bin" directory to your PATH. For example, in the "bash" shell under *nix, you would type the following commands:
```
  export CATALINA_HOME=/opt/apache-tomcat-5.5.17
  export PATH=$PATH:$CATALINA_HOME/bin 
```
Download Axis
For the SOAP implementation, you will be using Axis. You should be able to use any version of Axis above 1.2. For the purposes of these instructions, let's assume Axis 1.4. You will be copying some files from the Axis distribution into your Tomcat installation, so it is not critical to make the Axis files widely available on your system. For the purposes of these instructions, let's keep the convention established in the previous two steps and install it in /opt/axis-1_4. You then need to copy Axis' webapps directory to Tomcat's webapps directory. For example, in the "bash" shell under *nix, you would type the following commands:
```
  export AXIS_HOME=/opt/axis-1_4
  cp -R $AXIS_HOME/webapps/* $CATALINA_HOME/webapps/ 
```
Download Globus Toolkit
In order to communicate with a MyProxy server, you need a few libraries from the CoG (Commodity Grid) Kit. The easiest way to get these libraries is to download the GT4 Java WS Core binary distribution. You will be copying a few files from the GT4 Java WS Core into your Tomcat/Axis installation, so it is not critical to make these files widely available on your system. For the sake of continuity, let's extract the tarball to "/opt" and set an environment variable for WSCORE_HOME. Then copy a few files to $CATALINA_HOME/webapps/axis/WEB-INF/lib. The commands for "bash" in *nix are as follows:
```
  export WSCORE_HOME=/opt/ws-core-4.0.2
  cp $WSCORE_HOME/lib/cog-jglobus.jar \
     $WSCORE_HOME/lib/cryptix32.jar \
     $WSCORE_HOME/lib/cryptix-asn1.jar \
     $WSCORE_HOME/lib/jce-jdk13-125.jar \
     $WSCORE_HOME/lib/puretls.jar \
     $CATALINA_HOME/webapps/axis/WEB-INF/lib/ 
```
Configure Tomcat With SSL
Tomcat comes with a built-in SSL implementation to allow you to connect securely via "https://". However, it is disabled by default. You need to edit the server.xml configuration file to enable SSL. So go to the $CATALINA_HOME/conf directory and edit the server.xml file. Look for an XML block that starts with:
```
  <-- Define a SSL HTTP/1.1 Connector on port 8443 -->
  <--
  <Connector port="8443" ...
      ... />
  -->
  
```
Remove the comments (<-- -->) from around this <Connector.../> XML block to enable the SSL Connector. Also, somewhere in that block (before the closing "/>"), insert the following line:
```
  keystoreFile="conf/keystore" 
```
Create A Java keystore
In the previous step, you added an option for the keystoreFile. This is a file which can contain certificates and keys and is created using the Java keytool command. While it is possible to convert existing certificates into a format suitable for Tomcat's SSL Connector, let's just create an easy "self-signed" certificate for testing purposes. In the $CATALINA_HOME/conf directory, issue the following command:
```
  keytool -genkey -alias tomcat -keyalg RSA -keypass changeit \
          -storepass changeit -keystore keystore 
```
You will be prompted for various entries such as your name, your location, etc. The only important one is "your first and last name" (the first prompt). Here, enter the machine name you will use to access the web application server. For example, if you plan on running Tomcat only as a local installation, you would probably have URLs which look like https://localhost:8443/axis. In this case, "your first and last name" is localhost. However, if you plan on allowing outside access to your web application server, you should use the FQDN (Fully Qualified Domain Name). For example, if users would enter URLs of the form https://www.sillynilly.org:8443/axis, then you would enter www.sillynilly.org for "your first and last name". All other fields are unimportant for the purposes of the example web service.
Download The Example Web Service
Right-click on the MyProxyDelegatee.jws web service and select "Save As...". Save the file to $CATALINA_HOME/webapps/axis/. Since this is an 'instant' JWS (Java Web Service) file within Axis, you don't need a WSDL for it, nor do you need to compile it. Axis will compile it the first time it is accessed. (If you are interested, you can see the WSDL for this web service by pointing your browser to https://hostname:8443/axis/MyProxyDelegatee.jws?wsdl, replacing "hostname" with the name of your host machine).
(Re)Start Tomcat
Finally, everything should be in place and correctly configured. If Tomcat is currently running, you should stop it with the "shutdown.sh" command. You can then (re)start Tomcat and monitor its progress with the following commands:
```
  startup.sh ; \
  tail -f $CATALINA_HOME/logs/catalina.out 
```

Installing The Example Java Client

Quick Link: MyProxyDelegator.java (Java client)

For the client side, you will need Java, Axis, and GT4 Java WS Core (but not Tomcat). If you are running the example client on the same machine as the server, then you already have everything you need. However, if you are running the example client on another machine, you will need to download and install these three packages. Let's assume that you have used the instructions for the web service side above on your client machine, so that all of the paths are the same.

Download The Example Java Client
Right-click on the MyProxyDelegator.java client and select "Save As...". Save the file anywhere you like. Let's save it to the "/tmp" directory.
Compile the Example Java Client
In order to compile the example client code, you need the following jars in your CLASSPATH:
- axis.jar (from Axis)
- cog-jglobus.jar (from GT4 Java WS Core)
- jaxrpc.jar (from Axis)
- log4j.jar (from Axis or GT4 Java WS Core)
In order to execute the compiled client code, you need the following additional jars in your CLASSPATH:
- commons-discovery.jar (from Axis)
- commons-logging.jar (from Axis)
- cryptix32.jar (from GT4 Java WS Core)
- cryptix-asn1.jar (from GT4 Java WS Core)
- puretls.jar (from GT4 Java WS Core)
- saaj.jar (from Axis)
It's easiest to simply put all of these jars in your CLASSPATH and then compile/run the program. Here are some "bash" shell commands to do this:
```
export AXIS_LIB=$AXIS_HOME/lib
export WSCORE_LIB=$WSCORE_HOME/lib
export CLASSPATH=.:\
$AXIS_LIB/axis.jar:\
$WSCORE_LIB/cog-jglobus.jar:\
$AXIS_LIB/jaxrpc.jar:\
$AXIS_LIB/log4j-1.2.8.jar:\
$AXIS_LIB/commons-discovery-0.2.jar:\
$AXIS_LIB/commons-logging-1.0.4.jar:\
$WSCORE_LIB/cryptix32.jar:\
$WSCORE_LIB/cryptix-asn1.jar:\
$WSCORE_LIB/puretls.jar:\
$AXIS_LIB/saaj.jar:\
$CLASSPATH
```
Now you can actually compile the source code with this command:
```
  javac MyProxyDelegator.java
```
Get A Java TrustStore
In order to authenticate the connection from the Java client to the Tomcat web service, you need to have a Java TrustStore which contains the certificate (chain) of the Tomcat server. The easiest way to do this is to copy the server file $CATALINA_HOME/conf/keystore to the client machine and put it in the same location as the MyProxyDelegator.java program, in this case "/tmp". Then when you run the example client, you can reference this file as a TrustStore using the command line option -Djavax.net.ssl.trustStore=keystore.

Execute the Example Java Client
The example program demonstrates delegating a credential to a web service via a MyProxy server. It is assumed that if you are trying to run this example program, then you have a credential to delegate. If not, you should consult the rest of the MyProxy Documentation.

To see the command line parameters for the sample program, execute:

  java MyProxyDelegator -?

Basically, there are two ways to read in the credential you wish to delegate: from a local file or from a MyProxy server. If you have a credential on your local hard drive, then you would use the "-n filename" command line option. If you have a credential stored in a MyProxy server, then you would use the "-h host", "-p port", "-u username", and "-w password" command line options. Here's an example that reads a credential from a local file in /tmp/x509up_u_501, delegates that credential to the MyProxy server at NCSA, and then notifies the web service running on www.willynilly.org:

  java -Djavax.net.ssl.trustStore=keystore MyProxyDelegator \
       -n /tmp/x509up_u_501 -h myproxy.ncsa.uiuc.edu -p 7512 \
       https://www.willynilly.org:8443/axis/MyProxyDelegatee.jws

This would result in output similar to the following. (Note that carriage returns and spaces have been inserted to improve readability.)

  [main] INFO  MyProxyDelegator  - Getting credential from Local File.
  [main] INFO  MyProxyDelegator  - Local credential file name = /tmp/x509up_u_501
  [main] INFO  MyProxyDelegator  - Web service URL = 
                                   https://www.willynilly.org:8443/axis/MyProxyDelegatee.jws
  [main] INFO  MyProxyDelegator  - Got Credential with DN = /C=US/O=NCSA/CN=John Doe
  [main] INFO  MyProxyDelegator  - Trying to put credential
                                   'org.globus.gsi.gssapi.GlobusGSSCredentialImpl@c2a132' 
                                   to myproxy.ncsa.uiuc.edu:7512 
                                   with username = '/C=US/O=NCSA/CN=John Doe->tgz]2tc', 
                                   passphrase = 'LxfAgOSMSStMdX4Q', and lifetime = '300' ...
  [main] INFO  MyProxyDelegator  - Succeeded!
  [main] INFO  MyProxyDelegator  - Notifying web service about delegated short lived GSSCredential
  [main] INFO  MyProxyDelegator  - Web Service Responded : Using the MyProxy server at 
                                   myproxy.ncsa.uiuc.edu:7512 with
                                   username = '/C=US/O=NCSA/CN=John Doe->tgz]2tc' and 
                                   passphrase = 'LxfAgOSMSStMdX4Q',
                                   successfully fetched the credential 
                                   org.globus.gsi.gssapi.GlobusGSSCredentialImpl@12dd76 
                                   with remaining lifetime = 297 seconds

You will notice that the original credential (identified with the trailing @c2a132) differs from the credential that the web service got (identified with the trailing @12dd76). This is good! It means that the MyProxy server did its job and created new proxy credentials on-the-fly.