Installing GridShib on UNIX
April 30, 2008

This GridShib Installation Guide shows how to install Globus Java WS Core 4.0, GridShib for GT v0.6, and GridShib SAML Tools v0.3 on UNIX. We use the GridShib CA v0.5 to bootstrap your X.509 environment, which is required to run a Globus container or issue an X.509-bound SAML token.

Software requirements include JDK 1.4.2 (or higher) and Ant 1.6 (or higher), which we assume are already installed. In addition to these general software requirements, we assume that you have Java Web Start installed so that we can leverage the GridShib CA to obtain credentials via the browser. Please check for a proper installation of Java Web Start before continuing.

A lightweight alternative to installing the full Globus Toolkit (GT) is to install Java WS Core 4.0 and then install GridShib for GT on top of that. This document shows how to layer GridShib for GT on top of Java WS Core on a UNIX system.

Contents

Getting Started
Installing JWS Core on UNIX
Installing GridShib for GT on UNIX
Installing GridShib SAML Tools on UNIX

Getting Started

We will install each of the software components (JWS Core, GridShib for GT, GridShib SAML Tools) as the globus user:

$ su - globus
$ echo $HOME
/home/globus

You may install the software as any user you want as long as that same user starts and stops the container.

Installing JWS Core on UNIX

This section shows how to install a JWS Core 4.0 container on a UNIX system.

We extract the JWS Core archive into $HOME/globus. If this directory does not exist on your system, create it now.

Install the binary version of Java WS Core 4.0.7 on Unix.

The binary version is simplest, but of course the source version works just as well.

Download and unpack the JWS Core archive:

$ cd $HOME/globus
$ wget http://www-unix.globus.org/ftppub/gt4/4.0/4.0.7/ws-core/bin/ws-core-4.0.7-bin.tar.gz
$ gunzip ws-core-4.0.7-bin.tar.gz
$ tar xvf ws-core-4.0.7-bin.tar

Change directory to the installation directory and set the GLOBUS_LOCATION environment variable:

$ cd ./ws-core-4.0.7
$ export GLOBUS_LOCATION=`pwd`
$ echo $GLOBUS_LOCATION
/home/globus/globus/ws-core-4.0.7

For debugging purposes, add the following line to $GLOBUS_LOCATION/container-log4j.properties:
```
log4j.category.org.globus.gridshib=DEBUG
```

As an initial but crude test, start the container (with transport-level security disabled):

$ bin/globus-start-container -nosec
Starting SOAP server at: http://141.142.234.19:8080/wsrf/services/
With the following services:

[1]: http://141.142.234.19:8080/wsrf/services/AdminService
[2]: http://141.142.234.19:8080/wsrf/services/AuthzCalloutTestService
[3]: http://141.142.234.19:8080/wsrf/services/ContainerRegistryEntryService
[4]: http://141.142.234.19:8080/wsrf/services/ContainerRegistryService
[5]: http://141.142.234.19:8080/wsrf/services/CounterService
[6]: http://141.142.234.19:8080/wsrf/services/JWSCoreVersion
[7]: http://141.142.234.19:8080/wsrf/services/ManagementService
[8]: http://141.142.234.19:8080/wsrf/services/NotificationConsumerFactoryService
[9]: http://141.142.234.19:8080/wsrf/services/NotificationConsumerService
[10]: http://141.142.234.19:8080/wsrf/services/NotificationTestService
[11]: http://141.142.234.19:8080/wsrf/services/PersistenceTestSubscriptionManager
[12]: http://141.142.234.19:8080/wsrf/services/SampleAuthzService
[13]: http://141.142.234.19:8080/wsrf/services/SecureCounterService
[14]: http://141.142.234.19:8080/wsrf/services/SecurityTestService
[15]: http://141.142.234.19:8080/wsrf/services/ShutdownService
[16]: http://141.142.234.19:8080/wsrf/services/SubscriptionManagerService
[17]: http://141.142.234.19:8080/wsrf/services/TestAuthzService
[18]: http://141.142.234.19:8080/wsrf/services/TestRPCService
[19]: http://141.142.234.19:8080/wsrf/services/TestService
[20]: http://141.142.234.19:8080/wsrf/services/TestServiceRequest
[21]: http://141.142.234.19:8080/wsrf/services/TestServiceWrongWSDL
[22]: http://141.142.234.19:8080/wsrf/services/Version
[23]: http://141.142.234.19:8080/wsrf/services/WidgetNotificationService
[24]: http://141.142.234.19:8080/wsrf/services/WidgetService
[25]: http://141.142.234.19:8080/wsrf/services/gsi/AuthenticationService

Press Ctrl-C to abort the container.

[Optional] Complete the test sequence in section 5 of the Globus Java WS Core Admin Guide.

Install a trusted CA certificate.
In what follows, we will use a GridShib CA-issued end-entity credential (EEC) to authenticate to GT services. We will also issue proxy certificates signed by a GridShib CA-issued EEC. Thus the container needs to be configured to trust certificates issued by the GridShib CA.
1. Download and install the public certificate of the GridShib CA in directory $HOME/.globus/certificates (if this directory does not exist, create it now):
```
$ cd $HOME/globus
$ wget http://gridshib.globus.org/downloads/gridshib-ca-cert.tar
$ cd $HOME/.globus/certificates
$ tar xvf $HOME/globus/gridshib-ca-cert.tar
```
  If the server system already has a directory /etc/grid-security/certificates, install the trusted CA certificate in that directory instead.
2. Verify the trusted certificate was extracted to the trusted certificate directory:
```
$ ls $HOME/.globus/certificates/bfcd1f28.*
/home/globus/.globus/certificates/bfcd1f28.0
/home/globus/.globus/certificates/bfcd1f28.signing_policy
```

Obtain a user certificate and stop the container normally.

Ironically, it is more difficult to stop a container with transport security disabled (-nosec) than to stop a secure container.

In the previous shell window, start an insecure container again:

$ echo $GLOBUS_LOCATION
$ bin/globus-start-container -nosec
Starting SOAP server at: http://141.142.234.19:8080/wsrf/services/
With the following services...

Open another shell window and try to stop the container:

$ su - globus
$ cd $HOME/globus/ws-core-4.0.7
$ export GLOBUS_LOCATION=`pwd`
$ echo $GLOBUS_LOCATION
$ bin/globus-stop-container -m msg \
    -s http://localhost:8080/wsrf/services/ShutdownService
2008-04-25 15:23:31,817 ERROR securemsg.X509SignHandler
[main,handleMessage:109] Failed to sign message
org.globus.gsi.GlobusCredentialException: Proxy file
(/tmp/x509up_u504) not found.

Obtain a short-term X.509 end-entity credential (EEC) from the online GridShib CA. This EEC will be written (by the GridShib CA) to the exact path noted in the error message above.
```
$ echo /tmp/x509up_u$UID
/tmp/x509up_u504
$ ls -l /tmp/x509up_u$UID
-rw------- 1 globus globus 8047 Apr 24 08:22 /tmp/x509up_u504
```
If the previous command fails, set the UID environment variable to the appropriate value:
```
$ export UID=`grep -i $USER /etc/passwd | cut -f 3 -d ":"`
```
Finally, stop the container normally, authenticating with your GridShib CA-issued credential via Secure Message:
```
$ bin/globus-stop-container -m msg \
    -s http://localhost:8080/wsrf/services/ShutdownService
```

Start and stop a secure container.
For the rest of this Quick Start, we require a secure container and a valid GridShib CA-issued end-entity credential. If the credential expires, simply obtain another one from the online GridShib CA.
1. In the first shell window, start a secure container:
```
$ echo $GLOBUS_LOCATION
$ bin/globus-start-container
Starting SOAP server at: https://141.142.234.19:8443/wsrf/services/
With the following services...
```
2. In the second shell window, stop the container:
```
$ echo $GLOBUS_LOCATION
$ bin/globus-stop-container
```

Request the SecureCounterService, authenticating with your EEC via Secure Conversation.

In the first shell window, start a secure container:

$ echo $GLOBUS_LOCATION
$ bin/globus-start-container
Starting SOAP server at: https://141.142.234.19:8443/wsrf/services/
With the following services...

In the second shell window, request a service:

$ echo $GLOBUS_LOCATION
$ bin/counter-client -m conv -z none \
    -s https://localhost:8443/wsrf/services/SecureCounterService
Got notification with value: 3
Counter has value: 3
Got notification with value: 13

In the second Command Prompt window, stop the container:
```
$ bin/globus-stop-container
```

Installing GridShib for GT on UNIX

This section shows how to deploy GridShib for GT v0.6 into a JWS Core 4.0 container on a UNIX system. Follow these steps regardless of the underlying Globus Java WS Core version. The GridShib for GT installer will auto-detect the JWS Core version and install the appropriate files in the correct locations.

We extract the GridShib for GT archive into $HOME/gridshib. If this directory does not exist on your system, create it now.

Important! Before installing GridShib for GT, check to make sure the GLOBUS_LOCATION environment variable is set correctly:

$ echo $GLOBUS_LOCATION

We begin by uninstalling any versions of GridShib for GT that may have been previously installed into $GLOBUS_LOCATION. Then, after installing GridShib for GT, we run a simple test to make sure the plugin is running properly.

Uninstall all old versions of GridShib for GT (< 0.6).

$ cd $HOME/gridshib/gridshib-gt-X_X_X
$ ant undeploy
$ ant undeploy-echoservice
$ ant undeploy-tests

Download the latest GS4GT v0.6 source distribution (GZIP archive) from the GridShib Downloads page. (A ZIP archive is also available.)
```
$ cd $HOME/gridshib
$ wget http://gridshib.globus.org/downloads/gridshib-gt-0_6_0-src.tar.gz
```

Unpack the GZIP archive and extract the source files.

$ gunzip gridshib-gt-0_6_0-src.tar.gz
$ tar xvf gridshib-gt-0_6_0-src.tar

Deploy GridShib for GT v0.6:

$ cd gridshib-gt-0_6_0
$ ant deploy
$ ant deploy-echoservice

Obtain a short-term X.509 end-entity credential (EEC) from the online GridShib CA. The EEC will end up in the following file:
```
$ ls /tmp/x509up_u$UID
/tmp/x509up_u504
```

Start a secure container (restart it if it's already running).

$ $GLOBUS_LOCATION/bin/globus-start-container
Starting SOAP server at: https://141.142.234.19:8443/wsrf/services/
With the following services:

[1]: https://141.142.234.19:8443/wsrf/services/AdminService
[2]: https://141.142.234.19:8443/wsrf/services/AuthzCalloutTestService
[3]: https://141.142.234.19:8443/wsrf/services/ContainerRegistryEntryService
[4]: https://141.142.234.19:8443/wsrf/services/ContainerRegistryService
[5]: https://141.142.234.19:8443/wsrf/services/CounterService
[6]: https://141.142.234.19:8443/wsrf/services/JWSCoreVersion
[7]: https://141.142.234.19:8443/wsrf/services/ManagementService
[8]: https://141.142.234.19:8443/wsrf/services/NotificationConsumerFactoryService
[9]: https://141.142.234.19:8443/wsrf/services/NotificationConsumerService
[10]: https://141.142.234.19:8443/wsrf/services/NotificationTestService
[11]: https://141.142.234.19:8443/wsrf/services/PersistenceTestSubscriptionManager
[12]: https://141.142.234.19:8443/wsrf/services/SampleAuthzService
[13]: https://141.142.234.19:8443/wsrf/services/SecureCounterService
[14]: https://141.142.234.19:8443/wsrf/services/SecurityContextEchoService
[15]: https://141.142.234.19:8443/wsrf/services/SecurityTestService
[16]: https://141.142.234.19:8443/wsrf/services/ShutdownService
[17]: https://141.142.234.19:8443/wsrf/services/SubscriptionManagerService
[18]: https://141.142.234.19:8443/wsrf/services/TestAuthzService
[19]: https://141.142.234.19:8443/wsrf/services/TestRPCService
[20]: https://141.142.234.19:8443/wsrf/services/TestService
[21]: https://141.142.234.19:8443/wsrf/services/TestServiceRequest
[22]: https://141.142.234.19:8443/wsrf/services/TestServiceWrongWSDL
[23]: https://141.142.234.19:8443/wsrf/services/Version
[24]: https://141.142.234.19:8443/wsrf/services/WidgetNotificationService
[25]: https://141.142.234.19:8443/wsrf/services/WidgetService
[26]: https://141.142.234.19:8443/wsrf/services/gsi/AuthenticationService

Note that the SecurityContextEchoService is now running in the container.

In the second shell window, copy your EEC to a preconfigured location (say, /tmp/testcredential.pem), set your environment, and request the service:

$ cp /tmp/x509up_u$UID /tmp/testcredential.pem
$ set X509_USER_PROXY=/tmp/testcredential.pem
$ $GLOBUS_LOCATION/bin/gridshibecho -d -z none \
    -s https://localhost:8443/wsrf/services/SecurityContextEchoService

---------
Response:
---------

Principal {
  name='/DC=edu/DC=uiuc/DC=ncsa/DC=computer/O=Shibboleth User
        /OU=https://idp.protectnetwork.org/protectnetwork-idp
        /CN=trscavo@idp.protectnetwork.org'
  type='Globus'
}
(untrusted) SAMLIdentity {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  nameID='<NameIdentifier
            xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
            Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">
            CN=trscavo@idp.protectnetwork.org,
            OU=https://idp.protectnetwork.org/protectnetwork-idp,
            O=Shibboleth User,DC=computer,DC=ncsa,DC=uiuc,DC=edu
          </NameIdentifier>'
}
(untrusted) BasicAttribute {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  name='http://gridshib.globus.org/testAttribute'
  nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
  value #1='testValueTwo'
  value #2='testValue'
}
(untrusted) BasicAttribute {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  name='http://gridshib.globus.org/testAttributeTwo'
  nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
  value #1='testValue'
}

There are a total of four (4) items in the above response:

One (1) Principal item, the Subject DN of your GridShib CA-issued EEC
One (1) SAMLIdentity item, corresponding to the <NameIdentifier> element in the bound SAML assertion
Two (2) BasicAttribute items, corresponding to the SAML <Attribute> elements in the bound SAML assertion

Note that all the items except the Principal item are labeled (untrusted). This is because these items have not yet been subjected to policy and are therefore only provisionally accepted by GridShib for GT.

In a shell window, stop the container.

The principal name in the above response is the Subject DN of the authenticated user.

Installing GridShib SAML Tools on UNIX

This section shows how to deploy GridShib SAML Tools v0.3 on UNIX.

We extract the GridShib SAML Tools archive into $HOME/gridshib. If this directory does not exist on your system, create it now.

Install GridShib SAML Tools v0.3.x on UNIX.
To install the GridShib SAML Tools, we invoke an ant script that creates a JAR file and runs some tests. The tests use a default issuing credential bundled with the SAML Tools.
1. Download the GridShib SAML Tools v0.3.x GZIP archive from the GridShib Downloads page. Unpack the GZIP archive into directory $HOME/gridshib:
```
$ cd $HOME/gridshib
$ wget http://gridshib.globus.org/downloads/gridshib-saml-tools-0_3_2-src.tar.gz
$ gunzip gridshib-saml-tools-0_3_2-src.tar.gz
$ tar xvf gridshib-saml-tools-0_3_2-src.tar
```
2. In a shell window, type the following commands:
```
$ cd ./gridshib-saml-tools-0_3_x
$ export GRIDSHIB_HOME=`pwd`
$ ant install
```
  See the GridShib SAML Tools Installation Notes for more detailed instructions.

Configure GridShib SAML Tools v0.3.0 on UNIX.

Obtain a short-term X.509 end-entity credential (EEC) from the online GridShib CA. The EEC will be end up in the following file:
```
$ ls /tmp/x509up_u$UID
/tmp/x509up_u504
```

Using the output of the above command, create a configuration properties file ($GRIDSHIB_HOME/etc/test-saml-issuer.properties) with the following lines:

# BEGIN test-saml-issuer.properties

# SAML NameIdentifier
NameID.Format=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
NameID.Format.template=%PRINCIPAL%

# FriendlyName="mail"
Attribute.mail.Namespace=urn:mace:shibboleth:1.0:attributeNamespace:uri
Attribute.mail.Name=urn:oid:0.9.2342.19200300.100.1.3
Attribute.mail.Value=trscavo@gmail.com

# X.509 Issuing Credential
certLocation=file:///tmp/x509up_u504
keyLocation=file:///tmp/x509up_u504

# END test-saml-issuer.properties

Request the SecurityContextEchoService, authenticating with a proxy credential.

In a shell window, issue a proxy:
```
$ $GRIDSHIB_HOME/bin/gridshib-saml-issuer \
    --user trscavo --holder-of-key \
    --config $GRIDSHIB_HOME/etc/test-saml-issuer.properties \
    --x509 --outfile /tmp/testcredential.pem
```
As indicated by the --holder-of-key option, an implicit holder-of-key SAML assertion will be bound to the proxy certificate. Since the SAML issuer is the X.509 subject, the security information in the proxy is said to be self-asserted.
In a shell window, start a secure container.

In a shell window, set the proxy path and request the service:

$ export X509_USER_PROXY=/tmp/testcredential.pem
$ $GLOBUS_LOCATION/bin/gridshibecho -d -z none \
    -s https://localhost:8443/wsrf/services/SecurityContextEchoService

---------
Response:
---------

Principal {
  name='/DC=edu/DC=uiuc/DC=ncsa/DC=computer/O=Shibboleth User
        /OU=https://idp.protectnetwork.org/protectnetwork-idp
        /CN=trscavo@idp.protectnetwork.org'
  type='Globus'
}
(untrusted) SAMLIdentity {
  issuer='CN=trscavo@idp.protectnetwork.org,
          OU=https://idp.protectnetwork.org/protectnetwork-idp,
          O=Shibboleth User,DC=computer,DC=ncsa,DC=uiuc,DC=edu'
  nameID='<NameIdentifier
            xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
            Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
            trscavo
          </NameIdentifier>'
}
(untrusted) SAMLIdentity {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  nameID='<NameIdentifier
            xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
            Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">
            CN=trscavo@idp.protectnetwork.org,
            OU=https://idp.protectnetwork.org/protectnetwork-idp,
            O=Shibboleth User,DC=computer,DC=ncsa,DC=uiuc,DC=edu
          </NameIdentifier>'
}
(untrusted) BasicAttribute {
  issuer='CN=trscavo@idp.protectnetwork.org,
  OU=https://idp.protectnetwork.org/protectnetwork-idp,
  O=Shibboleth User,DC=computer,DC=ncsa,DC=uiuc,DC=edu'
  name='urn:oid:0.9.2342.19200300.100.1.3'
  nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
  value #1='trscavo@gmail.com'
}
(untrusted) BasicAttribute {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  name='http://gridshib.globus.org/testAttribute'
  nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
  value #1='testValueTwo'
  value #2='testValue'
}
(untrusted) BasicAttribute {
  issuer='https://test-sp.ncsa.uiuc.edu/shibboleth'
  name='http://gridshib.globus.org/testAttributeTwo'
  nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
  value #1='testValue'
}

There are a total of six (6) items in the above response:

One (1) Principal item, the Subject DN of your GridShib CA-issued EEC
Two (2) SAMLIdentity items, corresponding to the <NameIdentifier> elements in the bound SAML assertions
Three (3) BasicAttribute items, corresponding to the SAML <Attribute> elements in the bound SAML assertions

You will recognize the two items contributed by the proxy certificate by their issuer, which is the Subject DN of your GridShib CA-issued EEC. Note that all the items except the Principal item are labeled (untrusted). This is because these items have not yet been subjected to policy and are therefore only provisionally accepted by GridShib for GT.

In a shell window, stop the container.

The GridShib Project
http://gridshib.globus.org/

Installing GridShib on UNIX April 30, 2008

Getting Started

Installing JWS Core on UNIX

Installing GridShib for GT on UNIX

Installing GridShib SAML Tools on UNIX

Installing GridShib on UNIX
April 30, 2008