Shibboleth Tomcat Filter: Installation Notes
--------------------------------------------

If you are reading this file, it means that you have successfully downloaded and unpackaged the ShibbolethFilter 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.
- PAPIFilter 2.0.
- 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
----------------------

0. Install the PAPIFilter as its INSTALL.txt specifies.
1. Locate your Tomcat installation directory; from now onwards we'll refer to it as $CATALINA_HOME;
2. Copy the jars file papiee-shibfilter-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 Shibboleth 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):

    <filter>
        <filter-name>Shibboleth Filter</filter-name>
        <filter-class>es.rediris.shib.filter.ShibbolethFilter</filter-class>
        <init-param>
            <param-name>configfile</param-name>
            <param-value>#location of the file#</param-value>
        </init-param>
    </filter>

5. Define the following mapping for the filter AFTER the one of the PAPIFilter:

    <filter-mapping>
        <filter-name>ShibbolethFilter</filter-name>
        <url-pattern>/SSO</url-pattern>
    </filter-mapping>

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 ShibbolethFilter, you can use the following document:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<!-- Configure these values -->
	<entry key="jdbc.db_driver">com.mysql.jdbc.Driver</entry>
	<entry key="jdbc.db_url">jdbc:mysql://localhost/papi_aa?user=adminaa&amp;password=adminaa.secure.666</entry>
<!-- Default values -->
	<entry key="papifilter.lcook_name">lcook</entry>
	<entry key="poa.lcook_timeout">300000</entry>
	<entry key="papi.assert_separator">,</entry>
	<entry key="papi.attr_separator">:</entry>
	<entry key="papi.value_assert_separator">=</entry>
	<entry key="papi.multivalue_assert_separator">-</entry>
	<entry key="papi.issuer_assert_separator">@</entry>
</properties>

In order to configure your Shibboleth filter, you should define the following parameters:

+ Configuring the ShibbolethFilter itself:
	- jdbc.db_driver: specifies the driver used by the JDBC.
		* Example:
			<entry key="jdbc.db_driver">com.mysql.jdbc.Driver</entry>
			
	- jdbc.db_driver: specifies the URI used by the JDBC where the ShibbolethFilter stores the user's attributes.
		* Example:
			<entry key="jdbc.db_url">jdbc:mysql://localhost/papi_aa?user=X&amp;password=Y</entry>
			
	- papifilter.lcook_name: specifies the name of the cooking issued by the PAPIFilter which holding the value of the lcook token.
		* Example:
			<entry key="papifilter.lcook_name">lcook</entry>

+ Configuring the PAPI behaviour:
	- poa.lcook_timeout: specifies the timelife of the lcook token.
		* Example:
			<entry key="poa.lcook_timeout">300000</entry>

	- papi.assert_separator: specifies which character(s) the PoA uses as a separator in a list of attributes.
		* Example:
			<entry key="papi.assert_separator">,</entry>

	- papi.attr_separator: specifies which character(s) the PoA uses as a separator in a list of elements of a token.
		* Example:
			<entry key="papi.attr_separator">:</entry>

	- papi.value_assert_separator: specifies which character(s) the PoA uses as a separator in a pair of atttribute name and attribute value.
		* Example:
			<entry key="papi.value_assert_separator">=</entry>

	- papi.multivalue_assert_separator: specifies which character(s) the PoA uses as a separator in a list of values of an attribute.
		* Example:
			<entry key="papi.multivalue_assert_separator">-</entry>

	- 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:
			<entry key="papi.issuer_assert_separator">@</entry>