Introduction

This document is a guide for deploying and configuring the PURSe portlets. Please see the PURSe Admin Guide for instructions on installing PURSe and its requirements. This guide assumes that you already have an installation of Tomcat and a portal server deployed to Tomcat.

Deploying the PURSe Portlets

Note: when you first deploy these war files, the PURSe portlet webapp will certainly complain that it was not able to initialize properly. See the section below on "Configuring the PURSe Portlet" after you deploy the portlet war for instructions on how to properly configure the PURSe portlets.

Deploying to a GridSphere portal

Download the GridSphere PURSe portlet war file from the main page. This war file has been tested with GridSphere. Deploy it to GridSphere using whatever method you use for deploying portlets to GridSphere. This war file contains a web.xml appropriate to GridSphere as well as the gridsphere-ui-tags.jar required for GridSphere portlets.

Deploying to a non-GridSphere portal

(Note that these portlets have only been tested in GridSphere.) Download the generic PURSe portlet war file from the main page. You can then deploy this war to your portal framework using whatever means necessary to deploy war's to your portal.

Copying necessary jars to Tomcat's shared/lib

Download the shared-lib-jars.tgz tarball from the main page, and untar it. Copy the jars in this tarball to the shared/lib directory of your Tomcat installation, making sure to remove any duplicate jars (e.g., if you copy cog-jglobus.jar into shared/lib and cog-jglobus-1.2.jar is already in shared/lib, then make sure to delete the cog-jglobus-1.2.jar jar).

Configuring the PURSe Portlets

Now that you have the PURSe portlets and their dependencies deployed to your portal server, you'll need to configure these portlets.

Configuring Registration Modules

The web.xml ($TOMCAT_HOME/webapps/purse-portlets/WEB-INF/web.xml ) file is where to remove and add Registration Modules. Currently, only GridSphereRegistrationModule is included, and it is enabled by default in the GridSphere war, but not in the generic war. Add Registration Modules by creating a new context parameter in the web.xml file. For example, if I've created a Registration Module called "org.ogce.purse.SampleRegistrationModule", I would add the following entry to the web.xml file:

<context-param>
    <param-name>PurseRegistrationModule_1</param-name>
    <param-value>org.ogce.purse.SampleRegistrationModule</param-value>
</context-param>
        

It's important that the param_name begins with PurseRegistrationModule and that it ends with an unique identifier. The convention is to increment an integer so that if there are three Registration Modules, you would have _0, _1, and _2 as suffices.

An additional note about the GridSphere registration module. If you use this module, note that it will take care of creating a GridSphere account and doing a password update for your users, so you'll probably also want to configure GridSphere to not allow account creation or allow users to reset their password in the Administrative "Configure Login" panel in GridSphere.

Configuring PURSe

Begin by copying the template PURSe properties file, $TOMCAT_HOME/webapps/purse-portlets/WEB-INF/purse.properties.template, to $TOMCAT_HOME/webapps/purse-portlets/WEB-INF/purse.properties. Then open this file up in an editor, and configure the properties in the table below. Properties listed in bold are ones that you must change. Other properties are safe to leave with their default values.

PropertyDescription
purse.dir The PURSE installation directory containing messages etc. This is the directory on the portal server where we deployed the PURSe tarball in the PURSe Admin Guide.
dbDriverJDBC driver to use when connecting to PURSe database. Default value is com.mysql.jdbc.Driver.
dbConnectionURLJDBC connection URL.
dbUsernameUsername to use when connection to PURSe database.
dbPasswordPassword to use when connection to PURSe database.
dbPropFile Filename that contains data about table and column names used in the backend database. Default value is ${purse.dir}/etc/databaseFilename.
statusFilename File with human-readable status indicators in the registration system. Default value is ${purse.dir}/etc/purse_status.
passPhrase Passphrase used to encrypt passwords stored in the PURSe database.
caAddress Email address of Certificate Authority.
purseAdminAddr Email address of PURSe Administrator.
portalVerifiesEmail Set the following to "true" to delegate validation of email address to the portal (that is, if your portal already checks or "knows" that the user's email address is valid). Default value is false. Note: this is an extension to PURSe.
outgoingProtocolEmail protocol for sending email. Default value is smtp.
outgoingHostOutgoing mail server.
outgoingPortOutgoing mail port. Default value is 25.
userAccountThis property and following mail properties are useful only for the mail retrieval and processing functionality of PURSe, which is not supported by the PURSe portlets. Although unused, these properties do need to be specified in order for PURSe to properly initialize.
passwordUnsupported.
incomingProtocolUnsupported.
incomingHostUnsupported.
incomingPortUnsupported.
signerCertUnsupported.
signerKeyUnsupported.
signerPassUnsupported.
proxyUploadTemplateUnsupported.
sendTokenTemplateTemplate used to send mail with the initial token generated when a user starts the registration process. Default value is ${purse.dir}/etc/tokenMailTemplate.
caAcceptTemplateTemplate used to send mail when CA accepts the user's request. Default value is ${purse.dir}/etc/caAcceptTemplate.
caRejectTemplateTemplate used to send mail when CA rejects the user's request. Default value is ${purse.dir}/etc/caRejectTemplate.
expireWarnTemplateTemplate used to send mail to users to warn about impending credential expiration. Default value is ${purse.dir}/etc/expireWarnTemplate.
renewTemplateTemplate used to send mail to users when renewal is successful. Default value is ${purse.dir}/etc/renewTemplate.
caTemplateTemplate to send mail to CA with details about user request. Default value is ${purse.dir}/etc/caMailTemplate.
caAdmtemplateTemplate used to send email to administrator who approves the account creation. Default value is ${purse.dir}/etc/caAdminTemplate.
subjectLineSubject line for user emails. Default value is PURSE Registration.
adminSubjectLineSubject line for CA email. Default value is Admin Subject line.
portalBaseUrlBase URL of the portal. For example, http://mygridsphere.mydomain.com:8080/gridsphere/gridsphere.
caBaseUrl URL to administrative action page, which will be emailed to the CA when a user's PURSe request is pending. For example, for GridSphere this would be something like https://myportal.gridproject.org/gridsphere/gridsphere?cid=purse-admin
userBaseUrl URL to email confirmation page, which will be emailed to the user for verification of email address. For example, for GridSphere this would be something like https://myportal.gridproject.org/gridsphere/gridsphere?cid=purse-confirm
renewBaseUrlBase URL of the PURSe certificate renewal page. Note that certificate renewal is currently not supported in PURSe portlets.
binLocationLocation of bin directory in GLOBUS_LOCATION install.
tmpLocationLocation of tmp directory in GLOBUS_LOCATION install. Note that it is important that the user under which the portal process executes has read/write access to this directory (one possibility here is to run chmod 1777 $GLOBUS_LOCATION/tmp).
myProxyHostMyProxy hostname.
myProxyPortMyProxy port number. Default is 7512.
myProxyBinLocation of directory holding the MyProxy administrative commands. For a GT4 install this should be $GLOBUS_LOCATION/sbin.
myProxyDnDistinguished Name (DN) of the MyProxy server. In a typical setup, this will be the DN of the host certificate of the server on which the MyProxy server runs.
myProxyDirDirectory where MyProxy stores its certificates, assuming a local installation. Because of the modifications to PURSe provided with these portlets, this setting is no longer necessary. Default value is /var/myproxy.
caDirDirectory of the simpleCA installation to be used with PURSe. This is the directory specified when running the setup-simple-ca script. See the PURSe Admin Guide for further details.
caHashThe hash of the CA bundle created by simpleCA. The hash is an 8 hexadecimal digit string.
caPasswordSet this property if you want certificate requests to automatically be accepted and signed. This property takes as its value the CA password supplied when generating the simple CA bundle. Note: this is an extension to PURSe.

After configuring the purse.properties file, you may need to restart Tomcat to have the changes take effect.

Configuring the Resource Bundles

All of the strings used in the PURSe Portlets are configured using resource bundles. There are five resource bundle files:

  • PursePortletResources.properties - this is the main resource bundle which covers all strings in the various PURSe Portlet web forms, etc.
  • PurseRegistrationPortlet.properties - provides the title of the PURSe Registration Portlet.
  • PursePasswordReminderPortlet.properties - provides the title of the PURSe Password Reminder Portlet.
  • PurseUserPortlet.properties - provides the title of the PURSe User Portlet
  • PurseAdminPortlet.properties - provides the title of the PURSe Admin Portlet
These files are in the TOMCAT_HOME/webapps/purse-portlets/WEB-INF/classes directory in the deployed webapp, or in src/conf if you are using the PURSe Portlets source.

Modifying the last 4 of the 5 files listed above is simple. These each just contain one resource string, the title, so it's easy to change, for example, the "PURSe Registration Portlet" to "MyGridPortal Account Sign-up". The first resource bundle file has several entries. The naming convention for these entries is a little inconsistent, i.e., some of them begin with "purseportlet." but that was dropped halfway through. Other than that, hopefully finding resource strings that you wish to modify should be fairly straightforward. There are two things that come to mind that you may want to do. The first is that you probably want to "re-brand" the PURSe Portlets with your own portal's name, and so an easy way to do this is just to search through the resource bundle files for the word "purse" and change accordingly. Another idea, if you are trying to figure out where a resource string is used in the PURSe portlets you can remove the file PursePortletResources.properties from the web application and restart it or redeploy it and instead of showing the resource strings, the JSF application should display the resource key names.

Enabling Single Sign On

To enable single sign on with PURSe, you'll want to install a MyProxy authentication module into your portal so that when a user logs in with their PURSe username and password, that username and password is used against PURSe's MyProxy server which will return the user's PURSe proxy credential. Thus, when the user logs in, their proxy credential is already loaded.

For GridSphere, the OGCE project has created a GridSphere MyProxy Single Sign On module. See the OGCE web site for more information.

Configuring Layout

Configuring the layout of the PURSe portlets will be a portal container specific activity. Here is a list of suggested locations for the PURSe Portlets.

  • Registration Portlet - add to the "guest" or "anonymous" layout.
  • Password Reminder Portlet - add to the "guest" or "anonymous" layout.
  • User Portlet - add to each user's default login page.
  • Admin Portlet - add to the administrator's page. Note that it is very important that this portlet only be accessible by a portal administrator.