|
MyProxy
> Docs
> Developer's Guide
> Web Service Delegation Example
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.
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.
- 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.
- The MyProxy server generates a public/private key pair and sends a
certificate signing request (CSR) to the client.
- 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.
- 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.
- 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.
- The web service generates a public/private key pair and sends a CSR
to the MyProxy server.
- 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.
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
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.
Last modified
11/18/09.
©2000-2019 Board of Trustees of the University of Illinois.
|