h1. WebSSO 1.3 Users Guide

{include:Documentation Navigation}
{cagridroundpanel}
{pre:class=cagridheaderfont}Table of Contents{pre}

This is the users guide for WebSSO Jasig Client that explains how to deploy a Sample WebSSO Jasig Client application. This application communicates with the WebSSO client (deployed in the same application server) to use the session attributes added by the WebSSO client. These session attributes are added during authentication and can be used by any web application that is deployed to a WebSSO-enabled app server.

Checkout SampleApplications release from SVN.

h2. Step 1: Install Prerequisite Software

In order to install and run the WebSSO, the following pre-requisite software must be installed:
* [Java 1.5 JDK|http://java.sun.com/j2se/1.5.0/system-configurations.html]
* [Ant 1.6.5|http://archive.apache.org/dist/ant/binaries/apache-ant-1.6.5-bin.zip]
* [Globus WS-Core with WS-Enum Support|http://gforge.nci.nih.gov/frs/download.php/1334/ws-core-enum-4.0.3.zip]
* [Tomcat 5.0.28|http://tomcat.apache.org/download-55.cgi#5.0.28]

The WebSSO Server has been configured and installed. The URL to this server would be used for configuring the WebSSO Client. Make sure *host-identity{*}of WebSSO Client was added as delegated application in websso-properties.xml for WEBSSO-Server. Details on how to install and configure a WebSSO Server can be found at following location [WebSSO Administrators Guide|websso13:Administrators Guide|http://wiki.cagrid.org/display/websso13/Administrators+Guide].

h2. Step 2: Setup Environment Variables

# Create a GLOBUS_LOCATION environment variable and point it at the directory in which you installed Globus.
# Create a CATALINA_HOME environment variable and point it at the directory in which you installed Tomcat.

h2. Step 3: Obtain a Host Credential

The WebSSO Client must run as a secure service, so the hosting container must run with a host credential. A host credential consist of an X.509 certificate and private key. [Dorian|dorian:home] provides the ability to issue and manage host credentials. There are many methods of retrieving host credentials, including:
# Requesting a credential from a known/trusted certificate authority ([caGrid Certificate Authority|websso13:Request a Host Certificate]). (*RECOMMENDED APROACH*)
# Standing up a [Dorian|dorian13:Administrators Guide] service.
# Standing up a simple certificate authority.

h2. Step 4: Configure Globus To Trust the CA

We MUST configure Globus to trust the CA that issued the host credentials obtained in the previous step. To do this, place a copy of the certificate for the CA that issued the host credentials in the Globus trusted certificates directory. Unless otherwise specified during installation, this is usually ''USER_HOME/.globus/certificates''. Globus requires all CA certificates in its trusted certificates directory to be in PEM format and to have a digit extension (0-9). For example, if a CA certificate is stored in the file ''cacert.pem'', it should be copied to the directory ''USER_HOME/.globus/certificates'' (create directory if needed) with the file name ''cacert.0''

h2. Step 5: Configuring and Building Sample WebSSO Jasig Client Application

Modify *application.properties* in WEBSSO_CLIENT_SAMPLE_APPLICATIONS directory to specify location of *cagrid.dir.*
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS
%> ant allwithcagridprojects
{noformat}
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS/projects/websso-client-example
%> ant configure-websso-client-jasig
Buildfile: build.xml

-template-input-configuration:
[input] Enter the location of the websso client host certificate (PEM format):
C:/Documents and Settings/user_account/host-cert.pem
[input] Enter the location of the websso client host key (PEM format):
C:/Documents and Settings/user_account/host-key.pem
[input] Enter websso client host name:
localhost
[input] Enter websso client http port:
8080
[input] Enter websso client https port:
8443
[input] Enter websso server host name:
NCI-GARMILLAS-1
[input] Enter websso server https port:
18443

importWebSSOTrustStore:
[echo] Importing WebSSO server trust store into WebSSO-Client cacerts file
[copy] Copying 1 file to C:\jakarta-tomcat-5.0.28-client1\conf
[java] Opening connection to NCI-GARMILLAS-1:18443...
[java] Starting SSL handshake...
[java] Certificate is not present in the trust store.Writing to the trust store
[java] Server sent 1 certificate(s):
[java] 1 Subject CN=webssoserver, OU=Services, OU=caGrid, OU=xyz, O=abc, C=US
[java] Issuer CN=caGrid Dorian CA, OU=caGrid, OU=xyz, O=abc, C=US
[java] sha1 9d 7d 68 0b 30 3b f8 8f 3b 76 7e f6 56 63 59 20 d9 2b dc d2
[java] md5 6d 5a 3b 57 df ff b0 5b d9 34 c4 9a a1 6e 07 e4
[java] Enter certificate to add to trusted keystore or 'q' to quit: [1]
1

BUILD SUCCESSFUL
{noformat}
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS

Since the WebSSO Client would be running using SSL we need to configure Tomcat to enable SSL. To do so complete the following:
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS/projects/websso-client-example
%> ant create-tomcat-keystore
Buildfile: build.xml

create-tomcat-keystore:

[java] Enter a location and name for your keystore:
C:\Documents and Settings\Garmillas\.cagrid\certificates\websso-client-jasig-keystore
[java] Enter a password for your keystore:
webssoclient
[java] Enter the location of the certificate (PEM format):
C:/Documents and Settings/user_account/host-cert.pem
[java] Enter the location of the private key (PEM format):
C:/Documents and Settings/user_account/host-key.pem
[java] Enter the current password of the private key:
webssoclient

{noformat}
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS/projects/websso-client-example
%> ant insert-tomcat-secure-connector
Buildfile: build.xml

defineAntTask:

insert-tomcat-secure-connector:
[input] Enter the location of the keystore:
C:/Documents and Settings/user_account/my_keystore
[input] Enter store password:
webssoclient
[input] Enter tomcat https port number:
8443
[echo] modifying server.xml in tomcat home dir C:\jakarta-tomcat-5.0.28-client1
{noformat}
h2. Step 7: Deploying WebSSO Client App into Tomcat

{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS/projects/websso-client-example
%> ant deployTomcatJasigClient
{noformat}
h2. Step 8: Verifying the Installation

Verify that the installation was successful by starting the container that WebSSO Jasig Client was deployed to. To start a secure Tomcat container run the startup script (startup.sh or startup.bat) located in TOMCAT_INSTALLATION_DIRECTORY/bin. If the container starts up,we are ready to verify that the WebSSO Jasig Client installation was successful.
From browser type [http://localhost:@PORT_NUMBER@/webssoclientjasigexample-1.3-dev] and make sure you are able to redirect to the WebSSO server.