The Web Single Sign-On/Sign-Out Client (WebSSO Client) is distributed both as a standalone project and a component other projects (such as caGrid). The Developers Guide covers the necessary steps to integrate a WebSSO client (Jasig Client, Acegi Client, Liferay Portal Client) into an existing web application. This guide provides guidance to integrate a WebSSO client into a web application server to make it WebSSO enabled. (e.g., integrate WebSSO client into the popular Liferay application server to WebSSO-enable the server).
Each distribution contains websso-client directory, herein referred to as WEBSSO_CLIENT_LOCATION. To install and configure the WebSSO Client, please follow the steps below.
In order to install and run the WebSSO, the following pre-requisite software must be installed:
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|websso14:Administrators Guide
Also, the target web application is a standard Java Web Application packaged in a war file. Details about a creating and packing a J2EE Web Application can be found on Sun's site at Packaging Web Components
If you have obtained a source release of the WebSSO Client, you will need to build it. Type the following from a command prompt:
|Depending on the the WebSSO Client distribution, it may be required to build the entire project that the WebSSO Client is distributed with prior to building the WebSSO Client. For example, if you have obtained a caGrid source distribution, this is required. If you received a WebSSO Client standalone distribution, this is not required.|
The WebSSO Client provides capability to retrieve user's delegated credentials by connecting to the Credentials Delegation Service (CDS). To use this feature, a host credential needs to be obtained for the container/server hosting the web application which will integrate with WebSSO Client. 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:
- Requesting a credential from a known/trusted certificate authority (caGrid Certificate Authority).
- Standing up a Dorian service.
- Standing up a simple certificate authority.
Once a host credentials are obtained and stored on the server, the path to the certificate file and the key file should be noted. This will be used to configure the Delegation Lookup filter.
To connect to the Credential Delegation Service (CDS), one must configure the server hosting the Web Application to trust the CA that issued the host credentials obtained in the previous step.
|NOTE: if you opt to start syncGTS programmatically execute the following. For detailed steps refer Step 7 and Step 8.|
In order for SyncGTS to 'sync' up the CA certificates on the server hosting the web application, the master GTS Certificate Authority .0 file must be copied from GTS to the server.
Copy the MASTER GTS CA.0 file from the GTS server that is at the $HOME/.globus/certificates to the $HOME/.globus/certificates folder on the server hosting the Web Application.
|Note: if you don't opt to start syncGTS programatically execute the following. For detailed steps refer Step 7 and Step 8.|
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"
- Download and unzip gridca.
- Bring up a command prompt and change to the gridca directory which you recently unzipped.
- At the command line type ant createTomcatKeystore, this will execute a command line program which will guide you through creating the keystore.
- In the Enter a location and name for your keystore: prompt enter a file name and location to create your keystore.
- In the Enter a password for your keystore: prompt enter a password for your keystore.
- In the Enter the location of the certificate (PEM format): prompt enter the location of the host certificate you just created.
- In the Enter the location of the private key (PEM format) : prompt enter the location of the private key you just created.
- 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.
- At this point the program will create your keystore at the location you specified. Below is a sample output of the program just described:
Since the WebSSO Client would be running using SSL we need to configure Tomcat to enable SSL. To do so complete the following:
- Edit the file CATALINA_HOME/conf/server.xml (example shown below).
- Uncomment connector element for port 8443 (SSL)
- Add a keystoreFile parameter containing the location of the keystore you just created.
- Add keystorePass parameter containing the the password of the keystore you just created.
- Restart tomcat
Once host credentials have been obtained, you can integrate the WebSSO Client into your Web Application. The WebSSO Client is released as a set of jar and configuration files found in WEBSSO_CLIENT_LOCATION/build folder.
The WEBSSO_CLIENT_LOCATION/build contains the following three configuration files:
- The applicationContext-jasig-1.4-dev.xml file is a spring configuration files which contains the configuration setting for CAS Filters which are packaged as part of WebSSO Client. Rename this file to applicationContext.xml and copy to WEBAPP_LOCATION/WEB-INF folder.
- Then cas-client-template-jasig-1.4-dev.properties is the file which contains configuration for connecting to the Central CAS Single Sign On Server. Rename this file to cas-client.properties, resolve the tokens @WEBSSO.SERVER@, @WEBSSO.SERVER.HTTPS.PORT@, @WEBSSO.CLIENT.SERVER@ and @WEBSSO.CLIENT.HTTP.PORT@ with respective values and copy to WEBAPP_LOCATION/WEB-INF/classes folder
- The web-template-jasig-1.4-dev.xml is a sample file provided to show entries which needs to be made to your web.xml file to enable the WebSSO Client capabilities in your application. Rename the file to web.xml and resolve the tokens @WEBSSO.CLIENT.HOST.CERTIFICATE@ and *@WEBSSO.CLIENT.HOST.KEY@.
The cas client is configured through a properties file: WEBSSO_CLIENT_LOCATION/build/cas-client-template-jasig-1.4-dev.properties. Below is an template of the cas-client-template-jasig-1.4-dev.properties file, followed by a description of each of the properties:
- cas.server.gateway - This is a property indicating whether the login screen should be displayed to the user or not. This option should be always set to 'false'.
- cas.server.renew - This is a property if set to true would require the user to login again irrespective of whether the Single Sign On session has been established or not. For general use, this should be set to 'false'. Note If you want to log into another application within the SSO realm without providing your credentials again, this property should be set to 'true'
- cas.server.url - This is the URL to the WebSSO's CAS Server. Note The CAS Server is generally installed in a secured container as a result of which the URL should have 'https'.
- cas.client.service - This is the URL to the WebSSO client server.
An example file is show below
Here localhosta is hosting the CAS Central Single Sign On Server and localhostb is hosting client application.
|Note - Also since both the applications are assumed to be running securely hence the default SSL ports for tomcats are shown.|
This file should be placed in the WEB_LOCATION/WEB-INF/ folder of the client web application.
Once the cas-client.properties file is configured, you need to enable the WebSSO Client filters. To do this, make an entry into the web.xml. A sample web.xml is show below. This file can be found in the WEBSSO_CLIENT_LOCATION/build/ location of the WebSSO Client Release:
Following are the entries in the web.xml file which should be added to the Client Web Application's web.xml file:
- Start Auto Sync GTS - This entry is to load the "org.cagrid.gaards.websso.client.utils.StartSyncGTSServlet" Servlet on start up. This Servlet uses the sync-description.xml file from the classpath and starts the SyncGTS Daemon. If the target application doesnt want to automatically start the SyncGTS Daemon then they should remove this entry from the web.xml or edit the param value to no eg: <param-value>no</param-value>.
|NOTE: Depending on how many start up servlets are configured for your application you would need to give appropriate number (based on start up order) to the load-on-startup entry|
- contextConfigLocation - This entry is to define the spring based applicationContext.xml file entry which is needed by the CAS Client. This entry should be copied as it is in the client web application's web.xml file
- listener-class - This entry points to the listener class which should be used. org.jasig.cas.client.session.SingleSignOutHttpSessionListener listener enables the CAS Single Sign out feature.
- CAS Authentication Filter - This is the entry for the CAS Authentication Filter. This filter checks if the User's Single Sign On Session has been established or not. This entry should be copied as it is in the client web application's web.xml file
- CAS Validation Filter - This is the entry for the CAS Validation Filter. This filter validates the User's Authentication Session and then retrieve User's Attributes from the Central CAS Single Sign On Server. This entry should be copied as it is in the client web application's web.xml file
- caGRID WebSSO Attribute Loader Filter - This is the entry for the caGRID WebSSO Attribute Loader Filter. This filter reads the attributes which are retrieved from the Central CAS Single Sign On Server and loads each of them into the HTTP Session. This entry should be copied as it is in the client web application's web.xml file
- caGRID WebSSO Delegation Lookup Filter - This is the entry for the caGRID WebSSO Delegation Lookup Filter. This filter connects to the Credential Delegation Service (CDS) using the Client Application's Host Credentials and retrieves the User's Grid Credentials. It then stores the retrieved User's Grid Credentials into the session as a session attribute. This filter need two parameter pointing to the certificate and the key file for the Client Application's Host Credential.
- certificate-file-path - points to the certificate file for the Client Application's Host Credentials.
- key-file-path - points to the key file for the Client Application's Host Credentials.
- caGRID WebSSO Logout Filter - This is the entry for the caGRID WebSSO Logout Filter. This filter connects to the WebSSO Server and issues a logout call. On receiving this logout the CAS Server terminates the SSO Session and issues a call to the Credential Delegation Service (CDS) to destroy user's delegation policy.
|Note These filters have to be defined in the above mentioned order as each is dependent on previous filter.|
Once these filters are defined, a mapping must be provided for them. In the sample shown, it is mapped to protect everything within the web context root of the application. If you want to protect anything within a specific context URL, you need to provide that entry.
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 Sync GTS Servlet is configured in the web.xml file above. Depending upon the grid you are trying to connect to, you need to obtain the sync-description.xml file from the corresponding Grid Administrator. This file needs to be placed in the classpath within the target application. This can be done by placing the file in the classes folder of the target application web archive (war file).
|NOTE: if you haven't configure the Start Auto Sync GTS start up servlet, then the onus of syncing with the trust fabric relies on the administrator. This can be done manually by starting the syncGTS Daemon on the target web application. For detailed steps refer to GTS|
In order for the client to trust the WebSSO Server you need to install the WebSSO Server's Public CA Cert into its truststore. This can be done by the following steps
- On the target application server, simply copy the cacerts to cacerts.old (to save it just in case)
- Run the java program given below by giving the following command - run java InstallCert <<CAS_SERVER_ADDRESS>>:<<CAS_SERVER_PORT>> (i.e. provide the argument "<<CAS_SERVER_ADDRESS>>:<<CAS_SERVER_PORT>>" to the executable "InstallCert"). (adapted source code for InstallCert.java from Sun blog by Andreas Sterbenz is shown below)
- Answer 1 to the prompt
Once the WebSSO Client has been configured, you need to program your application to retrieve the session attributes which are injected by the WebSSO Client. Following is the list of session attributes which hold values of the corresponding User Attributes: