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 appropriate GridSphere PURSe portlet war file from the main page. There is a war file for GridSphere 2.1.x and one for GridSphere 2.2.x. 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 Pluto.) 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

Note: If you used the PURSe install script, it will generate a purse.properties file for you that you can then further customize as needed.

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 Available in PURSe Portlets 1.0.x, this parameter was an extension to PURSe and has now been removed.
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.
signerCertificateUnsupported.
signerKeyUnsupported.
signerPassUnsupported.
proxyUploadInstruTemplateUnsupported.
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.
caAdminTemplateTemplate used to send email to administrator who approves the account creation. Default value is ${purse.dir}/etc/caAdminTemplate.
raTokenMailTemplateTemplate used to send email to registration authority (RA) who approves the account creation. Default value is ${purse.dir}/etc/raTokenTemplate.
forgotPasswordTemplateTemplate used to send email to user who has requested to reset his/her password. Default value is ${purse.dir}/etc/forgotPasswordTemplate.
subjectLineSubject line for user emails. Default value is PURSE Registration.
adminSubjectLineSubject line for PURSe admin email. Default value is Admin Subject line.
raSubjectLineSubject line for RA email. Default value is RA Subject line.
caSubjectLineSubject line for CA email. Default value is CA 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.
addEmailToDNSet to true if you want the email address of the user added to the generated DN (e.g., "/O=My Org/OU=My Department/CN=purseuser/EMAIL=purseusers_email@mygridproject.org").
caPasswordAvailable in PURSe Portlets 1.0.x, this parameter was an extension to PURSe and has now been removed.

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 two resource bundle files:

  • PursePortletResources.properties - this is the main resource bundle which covers all strings in the various PURSe Portlet web forms, etc. This file is deployed to TOMCAT_HOME/webapps/purse-portlets/WEB-INF/classes.
  • tag.properties - this properties file is part of PURSe and is used in generating PURSe emails. The PURSe Portlets also use this file to "brand" the PURSe portlets with the name of your portal, etc. This file is available in TOMCAT_HOME/webapps/purse-portlets/WEB-INF/
The tag.properties file is where you can set the properties:
  • portal_name - the name of the portal
  • portal_admin - the name of the portal administrator
  • portal_admin_email - the email address of the portal administrator (i.e., the email address that you want to be displayed to the user in emails and in the portlets)
Branding the PURSe portlets has been simplified in the 1.1.0 release so that editing these three properties will result in your portal's name being used throughout the PURSe portlets, where appropriate.

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.

To install, copy the OGCE GridSphere SSO jar into your Tomcat's shared/lib directory. Then add the following authentication module definition to your GridSphere's authmodules.xml file (in TOMCAT_HOME/webapps/gridsphere/WEB-INF/authmodules.xml).

    <auth-module>
        <name>MyProxyAuth</name>
        <description>MyProxy authentication</description>

<implementation>org.ogce.security.modules.MyProxyAuthModule</implementation>
        <active>true</active>
        <priority>10</priority>
        <auth-config>
            <param-name>hostname1</param-name>
            <param-value>myproxy1.mydomain.org</param-value>
        </auth-config>
        <auth-config>
            <param-name>port1</param-name>
            <param-value>7512</param-value>
        </auth-config>
        <auth-config>
            <param-name>lifetime1</param-name>
            <param-value>2</param-value>
        </auth-config>
        <auth-config>
            <param-name>hostname2</param-name>
            <param-value>myproxy2.mydomain.org</param-value>
        </auth-config>
        <auth-config>
            <param-name>port2</param-name>
            <param-value>7512</param-value>
        </auth-config>
        <auth-config>
            <param-name>lifetime2</param-name>
            <param-value>2</param-value>
        </auth-config>
    </auth-module>
      

For more information on OGCE's GridSphere MyProxy Single Sign On module, see the OGCE web site.

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