PAPI Tomcat Filter: Installation Notes
--------------------------------------
If you are reading this file, it means that you have successfully downloaded and unpackaged the PAPIFilter for Tomcat distribution. Please make sure that the distribution includes the required files, as defined in the README.txt file.
DEPENDENCIES
------------
- Java SE 5.0 or higher;
- The Apache Commons Collections, version 3.2 or greater. You can download it from: http://commons.apache.org/downloads/download_collections.cgi
- The Apache log4j, version 1.25 or greater. You can download it from: http://logging.apache.org/log4j/1.2/download.html
- The Bouncy Castle Provider package. You may download this package from: http://www.bouncycastle.org/download/bcprov-jdk15-132.jar
These three jar dependencies should be installed in the $CATALINA_HOME/common/lib directory.
INSTALLATION PROCEDURE
----------------------
1. Locate your Tomcat installation directory; from now onwards we'll refer to it as $CATALINA_HOME;
2. Copy the jars file papiee-crypt-1.0.jar and papiee-papiv1-1.0.jar in the $CATALINA_HOME/shared/lib directory;
3. Place the configuration file of this filter where you wish, and change its content according to your needings (see "CONFIGURATION FILE" information below);
4. To make PAPI filter control a certain Tomcat location, include the following lines in the corresponding web.xml file (note that the defined filters will be applied in order of appearance):
PAPI Filter
es.rediris.papi.filter.PAPIFilter
configfile
#location of the file#
5. Define a mapping for the filter, and a regular expression defining which applications the filter is defined for ('/* for all):
PAPI Filter
/*
For more information about configuring web.xml, please refer to the Tomcat configuration.
CONFIGURATION FILE
------------------
The configuration file is an standard XML Properties file.
Basically, if you want a quick deployment of the PAPIFilter, you can use the following document:
/home/papi/papifilter/keys/lkey
/home/papi/papifilter/keys/hkey
My_PoA
/jsp-examples/
http://server/GPoA/papiPoA
/home/papi/papifilter/keys/_GPoA_pubkey.pem
/home/papi/papifilter/registry/fileregistry.txt
.* => accept
300000
100000
FileRegistry
plain
604800
The user has no valid credentials for this resource.
hcook
lcook
,
:
=
-
@
In order to configure your PAPI filter, you should define the following parameters:
+ Configuring the PAPI Filter itself:
- papifilter.hcook_name: specifies the name of the cooking which holding the value of the hcook token.
* Example:
hcook
- papifilter.lcook_name: specifies the name of the cooking which holding the value of the lcook token.
* Example:
lcook
- papifilter.reject_message: specifies which error message the PAPIFilter is going to send when the user hasn't valid credentials for accessing the protected resource.
* Example:
The user has no valid credentials for this resource.
+ Configuring the PoA behaviour:
- poa.lkey_filename: specifies the path of the file containing the lkey
* Example:
/home/papi/papifilter/keys/lkey
- poa.hkey_filename: specifies the path of the file containing the hkey
* Example:
/home/papi/papifilter/keys/hkey
- poa.service_id: specifies the service ID of the PoA
* Example:
My_PoA
- poa.location: specifies the root location (in the web server) of the PoA
* Example:
/jsp-examples/
- poa.hcook_maxage: specifies the timelife of the hcook token.
* Example:
604800
- poa.lcook_timeout: specifies the timelife of the lcook token.
* Example:
300000
- poa.url_timeout: specifies the timelife of the token received in a Cheked response from a GPoA.
* Example:
100000
- poa.papi_filter: specifies a list of filters (separated by commas) for checking the user rights accessing to the protected resource. The format of a filter is 'regular expression => [accept|reject]'. That regular expression is matched with the attributes of the user.
* Example:
mail=*.@domain.net => accept,.* => reject
- poa.parentgpoa.uri: specifies the URI of a GPoA parent.
* Example:
http://server/GPoA/papiPoA
- poa.parentgpoa.pubkey_filename: specifies the path of the file containing the public key, in PEM format, of the GPoA.
* Example:
/home/papi/papifilter/keys/_GPoA_pubkey.pem
- poa.registry: specifies which registry service the PoA has to use. At the moment, the one based on files is only available.
* Example:
FileRegistry
- poa.token_handler: specifies which token handler the registry service has to use. At the moment, the plain one is only available.
* Example:
plain
+ Configuring the file registry:
- poa.fileregistry.filename: specifies which token handler the registry service has to use. At the moment, the plain one is only available.
* Example:
/home/papi/papifilter/registry/fileregistry.txt
+ Configuring the PAPI behaviour:
-
@
- papi.assert_separator: specifies which character(s) the PoA uses as a separator in a list of attributes.
* Example:
,
- papi.attr_separator: specifies which character(s) the PoA uses as a separator in a list of elements of a token.
* Example:
:
- papi.value_assert_separator: specifies which character(s) the PoA uses as a separator in a pair of atttribute name and attribute value.
* Example:
=
- papi.multivalue_assert_separator: specifies which character(s) the PoA uses as a separator in a list of values of an attribute.
* Example:
-
- papi.issuer_assert_separator: specifies which character(s) the PoA uses as a separator between the list of attributes and the ID of the Identity Provider.
* Example:
@