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 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.
(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.
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.
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.
| 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 | Available in PURSe Portlets 1.0.x, this parameter was an extension to PURSe and has now been removed. |
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. |
signerCertificate | Unsupported. |
signerKey | Unsupported. |
signerPass | Unsupported. |
proxyUploadInstruTemplate | 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. |
caAdminTemplate | Template used to send email to administrator who approves the
account creation. Default value is
${purse.dir}/etc/caAdminTemplate. |
raTokenMailTemplate | Template used to send email to registration authority (RA) who approves the
account creation. Default value is
${purse.dir}/etc/raTokenTemplate. |
forgotPasswordTemplate | Template used to send email to user who has requested to
reset his/her password. Default value is
${purse.dir}/etc/forgotPasswordTemplate. |
subjectLine | Subject line for user emails. Default value is PURSE
Registration. |
adminSubjectLine | Subject line for PURSe admin email. Default value is
Admin Subject line. |
raSubjectLine | Subject line for RA email. Default value is
RA Subject line. |
caSubjectLine | Subject line for CA email. Default value is
CA 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. |
addEmailToDN | Set 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"). |
caPassword | Available 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.
All of the strings used in the PURSe Portlets are configured using resource bundles. There are two resource bundle files:
TOMCAT_HOME/webapps/purse-portlets/WEB-INF/classes.
TOMCAT_HOME/webapps/purse-portlets/WEB-INF/
tag.properties file is where you can set the
properties:
portal_name - the name of the portalportal_admin - the name of the portal administratorportal_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)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 the layout of the PURSe portlets will be a portal container specific activity. Here is a list of suggested locations for the PURSe Portlets.