Legacy uPortal client

CASifying uPortal 2.3.2

(May work on other versions of uPortal).
Andrew Petro
July 16, 2004

Abstract:

An explanation of how to go from a fresh download of uPortal 2.3.2 to a CASified uPortal instance.

Discussion:

CASifying a deployment of uPortal requires, of course, an available CAS server. The CAS server must be able to receive https: requests, as the connection for ticket validation between a CAS client (in this case, uPortal) and the CAS server must be secure.

In addition, in order to be able to use Proxy CAS tickets for authenticating Portal channels to the services from which they obtain their data, the uPortal instance must be able to receive https: requests to its proxy ticket receptor servlet.

This is simplified in the case where the uPortal and CAS applications are both being hosted on the same machine, since a self-signed localhost certificate will be sufficient. In the more general case where uPortal and CAS are hosted on separate machines, each machine will need a server certificate that the other machine trusts. All clients of the CAS server will need to trust the CAS server certificate – for this reason CAS servers often use commercial certificates purchased from Verisign, Thawte, etc.

uPortal can be configured to use any of several security contexts. To use CAS for uPortal authentication, the YaleCasContext security context must be the selected context. uPortal security contexts are configured to receive one or more "principals" and "credentials" read from the Login servlet request. In particular, CAS receives the request parameter "ticket" as its credential. It validates this ticket against the CAS server configured in the portal.properties file.

Services validating CAS server tickets must already know, and provide to CAS on the validation request, the URL
of the service to which the ticket is intended to authenticate the user. This reduces the chance for misunderstanding between the CAS server and the client application as to exactly to what service the user has been authenticated. This also reduces the ability of an adversary to obtain identity information from an intercepted, not-yet-validated, ticket, though this is unlikely to be a real issue in practice.

In the uPortal, the service to which the user is authenticating is statically configured in the portal.properties file and must be identical to the URL of the uPortal login servlet.

Steps

These steps provide details about exactly how one configures CAS to provide and uPortal to receive authentication on a single host.

Establishing a self-signed certificate

First you need to establish a self-signed certificate using the keytool.

To do so, you should follow the instructions in the file readme_tomcat_ssl.txt, available from Chris Dunne's Developer Tutorials article. The article itself is available here.

Some particulars: Don't bother with the line "Uncomment the SSL configuration in the %catalina_home%\conf\server.xml." in the readme_tomcat_ssl.txt instructions referenced above, since we will cover this point explicitly below.

The "alias" of the certificate must be "tomcat". The referenced instructions set this alias correctly. The JRE instance into which you install the certificate must of course be the one used to run the Tomcat instance in which you intend to run the CAS and uPortal applications – that is, if you have multiple Java Runtime Environments installed, be sure to use the correct environment, that referenced by your Tomcat server's startup and shutdown scripts, if you are starting and stopping via script (the "bin" directory of your Tomcat installation).

If you have not otherwise set the password for your keystore, it is "changeit".

Configuring Tomcat 5 to listen for https: requests

If your Tomcat instance is running, stop it using the stop script in the "bin" directory of your Tomcat installation.

Edit the file "conf\server.xml" in your Tomcat installation. Find the commented-out entry

<Connector port="8443" 
   maxThreads="150" 
   minSpareThreads="25" 
   maxSpareThreads="75" 
   enableLookups="false" 
   disableUploadTimeout="true" 
   acceptCount="100" 
   debug="0" 
   scheme="https" 
   secure="true" 
   clientAuth="false" 
   sslProtocol="TLS" 
   keystoreFile="C:\j2sdk1.4.2_04\jre\lib\security\cacerts" 
   keystorePass="changeit" />

Edit the keystorePass attribute to have the value of your keystore password, if any. Edit the keystoreFile attribute to reference the cacerts file for your Java Runtime Environment. Uncomment this "Connector" element.

With this connector declaration uncommented, your Tomcat instance will now listen for secure requests on port 8443.

Configuring uPortal to use CAS for authentication

First, you'll need to install the uPortal CAS security provider, a CAS client library for uPortal. This file is attached to this page. The uPortal login servlet is called LoginServlet in uPortal 2.3.2 and is mapped as /Login, rather than /Authenticate, so references in the documentation to /Authenticate should be replaced with /Login. This provider includes two important classes for the org.jasig.portal.security.provider package: a YaleCasContext and associated YaleCasContextFactory. Add these into the uPortal source tree in the provider package and run Ant to rebuild the portal.jar file.

You'll need to place the casclient.jar file in the uPortal lib directory.

In the security.properties file in the uPortal properties directory, set the property "root" = "org.jasig.portal.security.provider.YaleCasContextFactory". This specifies that you want to use the YaleCasContext (which will be produced by this factory) as your root security context. A more complex configuration would be to allow the union of CAS authentication and other (say, simple) authentication, but let's start simple:

# Comment out the existing value for "root":
#root=org.jasig.portal.security.provider.SimpleSecurityContextFactory

# and instead use this value:
root=org.jasig.portal.security.provider.YaleCasContextFactory

In the same security.properties file, set the property "credentialToken.root" = "ticket". Comment out all other principalToken and credentialToken entries. This specifies that you want uPortal to remember the request parameter "ticket" on the Login request – which CAS will send along – and make it available to YaleCasContext, which will validate it.

# Answers what tokens are examined in the request for each context during authentication.


# A subcontext only needs to set it's tokens if it differs from those of the root context.


#principalToken.root=userName


#credentialToken.root=password


#credentialToken.root.cas=ticketid


credentialToken.root=ticket

At the end of portal.properties, add the following properties, which specify parameters that YaleCasContext requires:

org.jasig.portal.security.provider.YaleCasContext.CasValidateUrl=https://localhost:8443/cas/proxyValidate


org.jasig.portal.security.provider.YaleCasContext.CasProxyCallbackUrl=https://localhost:8443/uPortal/CasProxyServlet


org.jasig.portal.security.provider.YaleCasContext.PortalServiceUrl=http://localhost:8080/uPortal/Login

Declaring the uPortal ProxyTicketReceptor servlet

If you intend your uPortal to use proxy tickets, you'll need to set the context parameter "edu.yale.its.tp.cas.proxyUrl" to "https://localhost:8443/cas/proxy" in your uPortal web.xml. The CAS client ProxyTicketReceptor servlet reads this parameter to determine where it should send Proxy Granting Tickets to receive proxy tickets for specific services.

  <web-app>
	<context-param>
		<param-name>edu.yale.its.tp.cas.proxyUrl</param-name>
		<param-value>https://secure.its.yale.edu/cas/proxy</param-value>
	</context-param>
	...

You will also need to declare the servlet itself:

  <servlet>
	<servlet-name>CasProxyServlet</servlet-name>
	<servlet-class>edu.yale.its.tp.cas.proxy.ProxyTicketReceptor</servlet-class>
  </servlet>

And you will need to map this servlet:

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

Exercising your CAS and uPortal deployments

Start your Tomcat server (e.g., using the start script in the "bin" directory of your Tomcat instance. Open a web browser. Visit
https://localhost:8443/cas/login. If your CAS login page loads, this demonstrates that you have installed your SSL certificate correctly and that Tomcat is successfully listening on port 8443 for https: requests. Next, visit the url
https://localhost:8443/cas/login?service=http%3A%2F%2Flocalhost%3A8080%2FuPortal%2FLogin

Enter the username "demo" and the password "demo" (the default CAS authentication handler in the CAS server authenticates usernames with passwords identical to the username). CAS should redirect you to your uPortal instance, logging you in as "demo".

Where to go from here

From here, you will need to replace the default authentication handler declared in the CAS application web.xml with a handler that authenticates your population. You may wish to visit ESUP-Portail's CAuthGenericHandler project for several handler options.