Users guide for WebSSO Acegi Client explains how to deploy a Sample WebSSO Acegi Client application.

Checkout SampleApplications release from SVN

{include:downloads:Subversion Source Code 1.3}

*Repository:* cagrid-1-0/SampleApplications

*cagrid-1-0\SampleApplications* directory is refered as WEBSSO_CLIENT_SAMPLE_APPLICATIONS in this document.

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].

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 Acegi 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 Acegi 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-acegi
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/projects/websso-client-example
%> ant all
{noformat}
h2. Step 6: Configuring Tomcat
----
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\Garmillas\.cagrid\certificates\websso-client-jasig-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 into Tomcat
----
{noformat}%> cd WEBSSO_CLIENT_SAMPLE_APPLICATIONS/projects/websso-client-example
%> ant deployTomcatAcegiClient
{noformat}
h2. Step 8: Verifying the Installation

Verify that the installation was successful by starting the container that WebSSO Acegi 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 Acegi Client installation was successful.From browser type [http://localhost:@PORT_NUMBER@/webssoclientacegiexample-1.3-dev] and make sure you are able to redirect to the WebSSO server.