Access Keys:
Skip to content (Access Key - 0)

WebSSO

WebSSO 1.2 Developers Guide

[  caGrid 1.3 Documentation    |  WebSSO 1.2 Documentation |  WebSSO 1.2 Developers Guide ]

Table of Contents


Web Single Sign On Client (WebSSO Client) Installation and Configuration

The Web Single Sign Out Client (WebSSO Client) is distributed both as a standalone project and a component other projects (such as caGrid). Each distribution contains a websso-client directory, herein referred to as WEBSSO_CLIENT_LOCATION. To install and configure the WebSSO Client, please follow the steps below.

Step 1: Install Prerequisite Software

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. Details on how to install and configure a WebSSO Server can be found at following location WebSSO 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

Step 2: Building WebSSO Client

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

%> cd WEBSSO_CLIENT_LOCATION
%> ant clean all

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

Step 3: Obtain a Host Credential

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:

  1. Requesting a credential from a known/trusted certificate authority (caGrid Certificate Authority).
  2. Standing up a Dorian service.
  3. 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.

Step 4: Configure Server to Trust the Certificate Authority

NOTE: This step is not necessary if you opt to start syncGTS programmatically. For detailed steps refer Step 5 and Step 6.

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. 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 5: Integrating the WebSSO Client

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. The jar files are found in the WEBSSO_CLIENT_LOCATION/build/lib folder and configuration files are in the WEBSSO_CLIENT_LOCATION/build/conf folder. All the jar files for the WebSSO Client should be added to the Web Application's library. This can be done by copying all the files from the WEBSSO_CLIENT_LOCATION/build/lib into your WEBAPP_LOCATION/WEB-INF/lib.

The WEBSSO_CLIENT_LOCATION/build/conf contains the following three configuration files:

web.xml
cas-client.properties
securityConfiguration.xml

The securityConfiguration.xml file is a spring configuration files which contains the configuration setting for CAS Filters which are packaged as part of WebSSO Client. This file should be copied as it is in the WEBAPP_LOCATION/WEB-INF/ folder.

The cas-client.properties is the file which contains configuration for connecting to the Central CAS Single Sign On Server. This file should be copied after modifications in the WEBAPP_LOCATION/WEB-INF/ folder.

The web.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.

Step 5.1: Configuring the cas-client.properties File

The cas client is configured through a properties file: WEBSSO_CLIENT_LOCATION/build/conf/cas-client.properties. Below is an template of the cas-client.properties file, followed by a description of each of the properties:

cas.server.gateway=false
cas.server.renew=false
cas.server.url=https://<<CAS_SERVER_ADDRESS>>:<<CAS_SERVER_PORT>>/cas/
cas.server.proxyCallbackUrl=https://<<CAS_SERVER_ADDRESS>>:<<CAS_SERVER_PORT>>/manager/proxy/Receptor
cas.client.serverName=<<WEBAPP_ADDRESS>>:<<WEBAPP_PORT>>
cas.client.proxyCallbackUrl=https://<<WEBAPP_ADDRESS>>::<<WEBAPP_PORT>>/myClientApp/casProxyReceptor

cas-client.properties

  1. 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'.
  2. 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'
  3. 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'.
  4. cas.server.proxyCallbackUrl - This is the server proxy callback URL. This URL should point to the CAS Server/Port. Note The feature that uses this URL is not used in WebSSO's implementation of CAS.
  5. cas.client.serverName - This is the client server address. It consist of the fully qualified server name and the port at which the application is running. Note This port should be the SSL port if you are running secured application.
  6. cas.client.proxyCallbackUrl - This is the client proxy callback URL. This URL should point to the server and the port where the client application is running. Note This port should be the SSL port if you are running secured application.

An example file is show below:

cas.server.gateway=false
cas.server.renew=false
cas.server.url=[https://localhosta:8443/cas/]
cas.server.proxyCallbackUrl=[https://localhosta:8443/manager/proxy/Receptor]
cas.client.serverName=localhostb:8443
cas.client.proxyCallbackUrl=[https://localhostb:8443/myClientApp/casProxyReceptor]

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.

Step 5.2: Modifying the web.xml File

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/conf/ location of the WebSSO Client Release:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
[http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd]">

<servlet>
<servlet-name>Start Auto Sync GTS</servlet-name>
<servlet-class>
org.cagrid.gaards.websso.client.utils.StartSyncGTSServlet
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet>
<servlet-name>hello</servlet-name>
<servlet-class>test.HelloServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>hello</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>

<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>
/WEB-INF/securityConfiguration.xml
</param-value>
</context-param>

<filter>
<filter-name>CAS Authentication Filter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
<init-param>
<param-name>targetBeanName</param-name>
<param-value>casAuthenticationFilter</param-value>
</init-param>
</filter>

<filter>
<filter-name>CAS Validation Filter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
<init-param>
<param-name>targetBeanName</param-name>
<param-value>casValidationFilter</param-value>
</init-param>
</filter>

<filter>
<filter-name>caGRID WebSSO Attribute Loader Filter</filter-name>
<filter-class>org.cagrid.gaards.websso.client.filter.CaGridWebSSOAttributeLoaderFilter</filter-class>
</filter>

<filter>
<filter-name>caGRID WebSSO Delegation Lookup Filter</filter-name>
<filter-class>org.cagrid.gaards.websso.client.filter.CaGridWebSSODelegationLookupFilter</filter-class>
<init-param>
<param-name>certificate-file-path</param-name>
<param-value>C:/Documents and Settings/MODI/.cagrid/certificates/MODIK_LAP-cert.pem</param-value>
</init-param>
<init-param>
<param-name>key-file-path</param-name>
<param-value>C:/Documents and Settings/MODI/.cagrid/certificates/MODIK_LAP-key.pem</param-value>
</init-param>
</filter>


<filter>
<filter-name>caGRID WebSSO Logout Filter</filter-name>
<filter-class>org.cagrid.gaards.websso.client.filter.CaGridWebSSOLogoutFilter</filter-class>
<init-param>
<param-name>logout-landing-url</param-name>
<param-value>[https://localhost:58443/sample/hello]</param-value>
</init-param>
</filter>


<filter-mapping>
<filter-name>CAS Authentication Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>CAS Validation Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>caGRID WebSSO Attribute Loader Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>caGRID WebSSO Delegation Lookup Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
<filter-name>caGRID WebSSO Logout Filter</filter-name>
<url-pattern>/logout/*</url-pattern>
</filter-mapping>

<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
</web-app>

Following are the entries in the web.xml file which should be added to the Client Web Application's web.xml file:

Start-up Entries

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

Other Entries

  1. contextConfigLocation - This entry is to define the spring based securityConfiguration.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
  2. listener-class - This entry points to the listner class which should be used.

Filter Entries

  1. 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
  2. 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
  3. 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
  4. 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.
    1. certificate-file-path - points to the certificate file for the Client Application's Host Credentials.
    2. key-file-path - points to the key file for the Client Application's Host Credentials.
  5. 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|CDS:Home) to destroy user's delegation policy.
    1. logout-landing-url - points to the location of the target webapplication where the user should be rerouted by the WebSSO Server upon successful logout.

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.

Step 6: Copying 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 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 GTSstart 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

Step 7: Establish Trust with WebSSO CAS Server

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

  1. On the target application server, simply copy the cacerts to cacerts.old (to save it just in case)
  2. 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)
  3. Answer 1 to the prompt/*
* @(#)InstallCert.java 1.1 06/10/09
\*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
\*/


import java.io.*;
import java.net.URL;

import java.security.*;
import java.security.cert.*;

import javax.net.ssl.*;

public class InstallCert {

public static void main(String\[\] args) throws Exception {
String host;
int port;
char\[\] passphrase;
if ((args.length == 1) \|\| (args.length == 2)) {         String[] c = args[0].split(":");         host = c[0];         port = (c.length == 1) ? 443 : Integer.parseInt(c[1]);         String p = (args.length == 1) ? "changeit" : args[1];         passphrase = p.toCharArray();     } else {         System.out.println("Usage: java InstallCert[:port] [passphrase]");         return;     }

File file = new File("jssecacerts");
if (file.isFile() == false) {
char SEP = File.separatorChar;
File dir = new File(System.getProperty("java.home") + SEP
+ "lib" + SEP + "security");
file = new File(dir, "jssecacerts");
if (file.isFile() == false) {         file = new File(dir, "cacerts");         }
}
System.out.println("Loading KeyStore " + file + "...");
InputStream in = new FileInputStream(file);
KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
ks.load(in, passphrase);
in.close();

SSLContext context = SSLContext.getInstance("TLS");
TrustManagerFactory tmf =
TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(ks);
X509TrustManager defaultTrustManager = (X509TrustManager)tmf.getTrustManagers()[0];
SavingTrustManager tm = new SavingTrustManager(defaultTrustManager);
context.init(null, new TrustManager\[\] {tm}{tm}, null);
SSLSocketFactory factory = context.getSocketFactory();

System.out.println("Opening connection to " + host + ":" + port + "...");
SSLSocket socket = (SSLSocket)factory.createSocket(host, port);
socket.setSoTimeout(10000);
try {         System.out.println("Starting SSL handshake...");         socket.startHandshake();         socket.close();         System.out.println();         System.out.println("No errors, certificate is already trusted");     } catch (SSLException e) {         System.out.println();         e.printStackTrace(System.out);     }

X509Certificate\[\] chain = tm.chain;
if (chain == null) {         System.out.println("Could not obtain server certificate chain");         return;     }

BufferedReader reader =
new BufferedReader(new InputStreamReader(System.in));

System.out.println();
System.out.println("Server sent " + chain.length + " certificate(s):");
System.out.println();
MessageDigest sha1 = MessageDigest.getInstance("SHA1");
MessageDigest md5 = MessageDigest.getInstance("MD5");
for (int i = 0; i < chain.length; i++) {         X509Certificate cert = chain[i];         System.out.println             (" " + (i + 1) + " Subject " + cert.getSubjectDN());         System.out.println("   Issuer  " + cert.getIssuerDN());         sha1.update(cert.getEncoded());         System.out.println("   sha1    " + toHexString(sha1.digest()));         md5.update(cert.getEncoded());         System.out.println("   md5     " + toHexString(md5.digest()));         System.out.println();     }

System.out.println("Enter certificate to add to trusted keystore or 'q' to quit: [1]");
String line = reader.readLine().trim();
int k;
try {         k = (line.length() == 0) ? 0 : Integer.parseInt(line) - 1;     } catch (NumberFormatException e) {         System.out.println("KeyStore not changed");         return;     }

X509Certificate cert = chain[k];
String alias = host + "-" + (k + 1);
ks.setCertificateEntry(alias, cert);

OutputStream out = new FileOutputStream(file);
ks.store(out, passphrase);
out.close();

System.out.println();
System.out.println(cert);
System.out.println();
System.out.println
("Added certificate to keystore 'cacerts' using alias '"
+ alias + "'");
}

private static final char\[\] HEXDIGITS = "0123456789abcdef".toCharArray();

private static String toHexString(byte\[\] bytes) {
StringBuilder sb = new StringBuilder(bytes.length * 3);
for (int b&nbsp;: bytes) {         b &= 0xff;         sb.append(HEXDIGITS[b >> 4]);         sb.append(HEXDIGITS[b & 15]);         sb.append(' ');     }
return sb.toString();
}

private static class SavingTrustManager implements X509TrustManager {

private final X509TrustManager tm;
private X509Certificate\[\] chain;

SavingTrustManager(X509TrustManager tm) {           this.tm = tm;       }

public X509Certificate\[\] getAcceptedIssuers() {           throw new UnsupportedOperationException();       }

public void checkClientTrusted(X509Certificate[] chain, String authType)
throws CertificateException {          throw new UnsupportedOperationException();      }
}

public void checkServerTrusted(X509Certificate\[\] chain, String authType)
throws CertificateException {           this.chain = chain;           tm.checkServerTrusted(chain, authType);       }
}

}

Retrieving User Attributes Inside Client Application

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:

Session Attribute Name Information
CAGRID_SSO_GRID_IDENTITY User's Grid Identity
CAGRID_SSO_FIRST_NAME User's First Name
CAGRID_SSO_LAST_NAME User's Last Name
CAGRID_SSO_EMAIL_ID User's Email Id
CAGRID_SSO_DELEGATION_SERVICE_EPR Delegation Service's End Point Reference
CAGRID_SSO_GRID_CREDENTIAL User's Grid Credential

These attributes can be retrieved from the HTTP Session programmatically by specifying the individual session attribute name. Below is anexample servlet which retrieves all the attribute and prints them on the screen.

package test;

import java.io.*;
import java.util.Enumeration;

import javax.servlet.http.*;
import javax.servlet.*;


public class HelloServlet extends HttpServlet {
public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
{
// Returns a writer to write to the browser
PrintWriter out = response.getWriter();

// Writes the string to the browser.
out.println("Begin Printing User Attributes");
Enumeration attributeNames = request.getSession().getAttributeNames();
for (; attributeNames.hasMoreElements(); ) {
// Get the name of the attribute
String name = (String)attributeNames.nextElement();
if (name.contains("CAGRID"))<<<<< ATTRIBUTE NAME >>>>>" + name + "<<<<< ATTRIBUTE VALUE >>>>>" + value);        " >{         	Object value = (Object)request.getSession().getAttribute(name);         	out.println("<<<<< ATTRIBUTE NAME >>>>>" + name + "<<<<< ATTRIBUTE VALUE >>>>>" + value);         }
}
out.println("Done Printing User Attributes");
out.close();
}
}
Last edited by
Knowledge Center (1519 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence