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.
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.
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.
(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.
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).
Now that you have the PURSe portlets and their dependencies deployed to your portal server, you'll need to configure these portlets.
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.
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.
| Property | Description |
|---|---|
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. |
dbDriver | JDBC driver to use when connecting to PURSe database. Default
value is com.mysql.jdbc.Driver. |
dbConnectionURL | JDBC connection URL. |
dbUsername | Username to use when connection to PURSe database. |
dbPassword | Password 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.
|
outgoingProtocol | Email protocol for sending email.
Default value is smtp.
|
outgoingHost | Outgoing mail server. |
outgoingPort | Outgoing mail port. Default value is 25. |
userAccount | This 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. |
password | Unsupported. |
incomingProtocol | Unsupported. |
incomingHost | Unsupported. |
incomingPort | Unsupported. |
signerCert | Unsupported. |
signerKey | Unsupported. |
signerPass | Unsupported. |
proxyUploadTemplate | Unsupported. |
sendTokenTemplate | Template used to send mail with the initial token generated when
a user starts the registration process. Default value is
${purse.dir}/etc/tokenMailTemplate. |
caAcceptTemplate | Template used to send mail when CA accepts the user's request.
Default value is ${purse.dir}/etc/caAcceptTemplate. |
caRejectTemplate | Template used to send mail when CA rejects the user's request.
Default value is ${purse.dir}/etc/caRejectTemplate. |
expireWarnTemplate | Template used to send mail to users to warn about impending
credential expiration. Default value is
${purse.dir}/etc/expireWarnTemplate. |
renewTemplate | Template used to send mail to users when renewal is successful.
Default value is ${purse.dir}/etc/renewTemplate. |
caTemplate | Template to send mail to CA with details about user request.
Default value is ${purse.dir}/etc/caMailTemplate. |
caAdmtemplate | Template used to send email to administrator who approves the
account creation. Default value is
${purse.dir}/etc/caAdminTemplate. |
subjectLine | Subject line for user emails. Default value is PURSE
Registration. |
adminSubjectLine | Subject line for CA email. Default value is
Admin Subject line. |
portalBaseUrl | Base 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
|
renewBaseUrl | Base URL of the PURSe certificate renewal page. Note that certificate renewal is currently not supported in PURSe portlets. |
binLocation | Location of bin directory in GLOBUS_LOCATION install. |
tmpLocation | Location 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).
|
myProxyHost | MyProxy hostname. |
myProxyPort | MyProxy port number. Default is 7512. |
myProxyBin | Location of directory holding the MyProxy administrative commands.
For a GT4 install this should be $GLOBUS_LOCATION/sbin.
|
myProxyDn | Distinguished 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. |
myProxyDir | Directory 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. |
caDir | Directory 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. |
caHash | The hash of the CA bundle created by simpleCA. The hash is an 8 hexadecimal digit string. |
caPassword | Set 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.
All of the strings used in the PURSe Portlets are configured using resource bundles. There are five resource bundle files:
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.
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 the layout of the PURSe portlets will be a portal container specific activity. Here is a list of suggested locations for the PURSe Portlets.