Below you will find a list of technologies used by the CVRG to create the CVRG WebSSO system. The CVRG WebSSO project is an extension of the caGrid WebSSO 1.2 project. Enhancements include: configuration enhancements for the creation of delegated credentials, classloader fixes for deployment to Tomcat 5.5/6.0, CSS and style updates for CVRG, and updates to the cas-servlet.xml file to set service redirect/cookie age. Until the next release of the project from caGrid that incorporate these enhancements, please use only this version for CVRG. Some of the data below has been directly copied from the caGrid 1.2 WebSSO wiki (WebSSO:1.2:Administrators Guide) For more information on how caGrid Single sign-on works please see here (caGrid WebSSO)

CVRG Developer Workstation Hardware Requirements
We recommend the following minimum hardware configuration if you are a developer looking to extend the portal's functionality or to create portlets.

CVRG WebSSO Server Hardware Requirements
We recommend the following minimum hardware configuration if you deploying the CVRG portal at your institution.

The following software must be installed on deployment server in order for WebSSO to run

Step 1: Install Prerequisite Software

1. J2SE 5.0
2. Tomcat 5.5
3. Media:Ws-core-4.0.3.zip
4. Ant 1.7.0

Step 2: Setup environment variables

1. Create a GLOBUS_LOCATION environment variable and point it at the directory in which you installed Globus (ws-enum-4.0.3).
2. Create a CATALINA_HOME environment variable and point it at the directory in which you installed Tomcat.
3. Create a JAVA_HOME environment variable and point it at the directory in which you installed Java.
4. Create a ANT_HOME environment variable and point it at the directory in which you installed Ant.
5. Add the following values to your PATH variable
   1. $CATALINA_HOME/bin
   2. $ANT_HOME/bin
   3. $JAVA_HOME/bin

Step 3: Obtain a Host Credential

The WebSSO 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 provides the ability to issue and manage host credentials. There are many methods of retrieving host credentials, including:

1. Requesting a credential from a known/trusted certificate authority (CVRG Certificate Authority). (RECOMMENDED APROACH)
2. Standing up a Dorian service.
3. Standing up a simple certificate authority.

Step 4: Create Host Credential Keystore

1. Download and unzip gridca (located in the projects folder for caGrid; automatically built by the createTomcatPortalKeystore in cvrgPortal-1.1).
2. Bring up a command prompt and change to the gridca directory which you recently unzipped.
3. At the command line type ant createTomcatKeystore, this will execute a command line program which will guide you through creating the keystore.
4. In the Enter a location and name for your keystore: prompt enter a file name and location to create your keystore.
5. In the Enter a password for your keystore: prompt enter a password for your keystore.
6. In the Enter the location of the certificate (PEM format): prompt enter the location of the host certificate you just created.
7. In the Enter the location of the private key (PEM format): prompt enter the location of the private key you just created.
8. In the Enter the current password of the private key: prompt enter the password for your private key, if you private key does not have a password (most cases) just hit enter.
9. At this point the program will create your keystore at the location you specified. Below is a sample output of the program just described:

  Enter a location and name for your keystore:/home/userDir/webssoKeystore/webssokeystore
  Enter a password for your keystore:webssopasswd
  Enter the location of the certificate (PEM format):/home/userDir/.globus/certificates/dwight.bmi.ohio-state.edu-cert.pem
  Enter the location of the private key (PEM format):/home/userDir/.globus/certificates/dwight.bmi.ohio-state.edu-key.pem
  Enter the current password of the private key:

Step 5: Configure Globus To Trust the CA

NOTE: This step is not necessary if you opt to start syncGTS programatically. For detailed steps refer Step 9 and Step 10.

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

Step 6: Configure Tomcat

Since the WebSSO Server would be running using SSL we need to configure Tomcat to enable SSL. To do so complete the following:

1. Edit the file $CATALINA_HOME/conf/server.xml (example shown below).
2. Uncomment connector element for port 8443 (SSL)
3. Add a keystoreFile parameter containing the location of the keystore you just created.
4. Add a keystorePass parameter containing the the password of the keystore you just created.
5. Restart Tomcat.

   <Connector port="8443" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" disableUploadTimeout="true"
   acceptCount="100" scheme="https" secure="true"
   clientAuth="false" sslProtocol="TLS"
   keystoreFile="/home/userDir/webssoKeystore/webssokeystore"
   keystorePass="webssopasswd" />

Step 7: Edit Tomcat to Work with Java 5.0 Generics

1. Edit the file $CATALINA_HOME/conf/web.xml (example shown below) - This is necessary for Tomcat to compile JSPs that are referencing Java 5.0 generic beans.
2. Move jasper-compiler-jdt.jar from CATALINA_HOME/common/lib to CATALINA_HOME
3. Copy Media:Ant.jar found here into CATALINA_HOME/common/lib
4. Restart tomcat if running

web.xml

    <servlet>
         <servlet-name>jsp</servlet-name>
         <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
         <init-param>
              <param-name>fork</param-name>
              <param-value>false</param-value>
         </init-param>
         <init-param>
              <param-name>xpoweredBy</param-name>
              <param-value>false</param-value>
         </init-param>
         <init-param>
              <param-name>compilerSourceVM</param-name>
              <param-value>1.5</param-value>
         </init-param>
         <init-param>
              <param-name>compilerTargetVM</param-name>
              <param-value>1.5</param-value>
         </init-param>
         <load-on-startup>3</load-on-startup>
    </servlet>

Step 8: Configure Tomcat Endorsed Jars

1. Delete jars from $CATALINA_HOME/common/endorsed.
2. Download the Media:xercesImpl.jar and place it in CATALINA_HOME/common/endorsed.

Step 9: Configuring the WebSSO Server

CVRG WebSSO is configured through an file, WEBSSO_LOCATION/src/resources/websso-properties.xml. Below is an example of the websso property file, followed by a description of each of the properties. WEBSSO_LOCATION refers to the directory location where you have checked out the project from source such as:

svn checkout https://project.bmi.ohio-state.edu/svn/cvrg/trunk/dev/websso/CVRG_WebSSO-1.2-CredFix 

websso-properties.xml

<?xml version="1.0" encoding="UTF-8"?>
<websso-properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="websso-properties.xsd">
     <websso-server-information>
          <start-auto-syncgts>yes</start-auto-syncgts>
          <trust-store-path>trust-store-path</trust-store-path>
          <host-credential-certificate-file-path>/root/.globus/certificates/webSSOServer.domain.com-cert.pem</host-credential-certificate-file-path>
          <host-credential-key-file-path>/root/.globus/certificates/webSSOServer.domain.com-key.pem</host-credential-key-file-path>
     </websso-server-information>
     <credential-delegation-service-information>
          <service-url>https://cvrg02-dev.bmi.ohio-state.edu:9442/wsrf/services/cagrid/CredentialDelegationService</service-url>
          <delegation-lifetime-hours>12</delegation-lifetime-hours>
          <delegation-lifetime-minutes>0</delegation-lifetime-minutes>
          <delegation-lifetime-seconds>0</delegation-lifetime-seconds>
          <delegation-path-length>2</delegation-path-length>
          <issued-credential-path-length>1</issued-credential-path-length>
    </credential-delegation-service-information>
    <authentication-service-list>
         <authentication-service-information>
              <service-name>CardioVascular Research Grid</service-name>
              <service-url>https://dorian.bmi.ohio-state.edu:9443/wsrf/services/cagrid/Dorian</service-url>
              <dorian-information>
                   <service-url>https://dorian.bmi.ohio-state.edu:9443/wsrf/services/cagrid/Dorian</service-url>
                   <proxy-lifetime-hours>12</proxy-lifetime-hours>
                   <proxy-lifetime-minutes>0</proxy-lifetime-minutes>
                   <proxy-lifetime-seconds>0</proxy-lifetime-seconds>
                   <proxy-delegation-path-length>3</proxy-delegation-path-length>
              </dorian-information>
         </authentication-service-information>
    </authentication-service-list>
    <delegated-applications-group>
         <group-name>CVRG</group-name>
              <delegated-application-list>
                   <delegated-application>
                        <application-name>CVRG Web Portal</application-name>
                        <host-identity>/O=CVRG/OU=LOA1/OU=Services/CN=host/cvrg-portal.icm.jhu.edu</host-identity>
                   </delegated-application>
              <delegated-application-list>
                   <delegated-application>
                        <application-name>Another Web Portal</application-name>
                        <host-identity>/O=CVRG/OU=LOA1/OU=Services/CN=host/another-web-portal.icm.jhu.edu</host-identity>
                   </delegated-application>
              </delegated-application-list>
         </delegated-applications-group>
</websso-properties>

WebSSO Properties

1. websso-server-information - This section contains information about the WebSSO Server.
   1. start-auto-syncgts - This is a configuration parameter indicating whether the WebSSO Server should start SyncGTS automatically or not. "yes" indicates WebSSO Server to start the SyncGTS daemon
   2. trust-store-path - This is the path to the trust store. This attribute is kept for future use.
   3. host-credential-certificate-file-path - This is the path to the WebSSO Server's Host Certificate File obtained in Step 3 above
   4. host-credential-key-file-path - This is the path to the WebSSO Server's Host Key File obtained in Step 3 above
2. credential-delegation-service-information - This section is used to configure the Central Delegation Service which will be used to publish the delegation policy for User's Grid Credentials
   1. service-url - This is the URL to the Central Delegation Service (CDS).
   2. delegation-lifetime-hours - This is the hours for which the delegation policy remains alive.
   3. delegation-lifetime-minutes - This is the minutes for which the delegation policy remains alive.
   4. delegation-lifetime-seconds - This is the seconds for which the delegation policy remains alive.
   5. delegation-path-length - The delegation path length of the credential being delegated to the Credential Delegation Service (CDS).
   6. issued-credential-path-length - The path length of the credentials delegated to entities by the CDS on your behalf. A path length of 0 means that entities that can you obtain a delegated credential cannot further delegate it.
3. authentication-service-list - This is the list of all the Authentication Services which can be used to authenticate user's credentials. For CCTS Release there would be only one entry.
   1. authentication-service-information - This is the entry for a single Authentication Service which consists of its name and URL.
      1. service-name - This is the name of the Authentication Service.
      2. service-url - This is the url where the Authentication Service is located.
      3. dorian-information - This section is used to configure the Dorian Server which will be used to retrieve User's Grid Credentials
         1. service-url - This is the URL to the Dorian Service.
         2. proxy-lifetime-hours - This is the hours for which the proxy remains alive.
         3. proxy-lifetime-minutes - This is the minutes for which the proxy remains alive.
         4. proxy-lifetime-seconds - This is the seconds for which the proxy remains alive.
         5. proxy-delegation-path-length - This is the delegation path length which should be set for proxy when created. It should be set to '0' thus avoiding any further delegation of proxy by the client.
4. delegated-applications-group - These are the group of applications to which user's credentials are to be delegated. In future these will be provided as a choice to the user. As of now they are just static list.
   1. group-name - This is the name given to the group of the applications to which a user's credentials is delegated.
   2. delegated-application-list - These are the list of the applications to which user's credentials are to be delegated.
      1. delegated-application - This is the entry for an application to which the user's credentials are delegated..
         1. application-name - This is the name of the application to which the user's credentials are delegated.
         2. host-identity - This is the host identity (obtained from the Host Credentials that are obtained from the Dorian) of the application to which the user's credentials are delegated.

NOTE: For each application (i.e. host server) using CVRG WebSSO it will be necessary to add the delegated-application and host-identity to the websso-properties.xml file. You will also have to rebuild the project and redeploy it in order to give the new application rights to access the WebSSO server. Since the configuration files are found within a jar (cas.war/WEB-INF/lib/caGrid-websso-conf-1.2.jar) upon deployment it will be necessary to do this build-redeploy (See steps 11 and 12 for more information) action each time a new application comes on line.

Step 10: Sync Description File

In order to sync with the Grid Trust Fabric, the WebSSO Server needs a sync-description.xml file in its classpath to start SyncGTS programatically if the start-auto-syncgts entry in WebSSO Configuration file is set to 'yes'. Depending upon the grid you are trying to connect to, you need to obtain the sync-description.xml file from the corresponding Grid Administrator (In this case one has been provided with in the project). NOTE: if you have turned start-auto-syncgts to 'no', then the onus of syncing with the trust fabric relies on the administrator. This can be done manually by starting the syncGTS Daemon. For detailed steps refer to GTS.

Step 11: Building the CVRG WebSSO Server

If you have obtained a source release of the WebSSO, you will need to build it. Type the following from a command prompt:

%> cd WEBSSO_LOCATION
%> ant clean all

Step 12: Deploying CVRG WebSSO

Once you have configured a secure (Tomcat) container and built the WebSSO Application, you need to deploy the WebSSO to that container. To deploy the WebSSO to a secure Tomcat container, copy cas.war file from the WEBSSO_LOCATION/build folder into Tomcat's webapps folder. If the Tomcat container is running ($CATALINA_HOME/bin/startup.sh), the CVRG WebSSO application should automatically deploy. To see the main CVRG Websso Server see here: CVRG WebSSO

TroubleShooting

If the following error shows up after trying to log into the WebSSO server, you need to check to see if the system time is accurate:

Run the following command to update the time:  sudo /usr/sbin/ntpdate navobs1.gatech.edu