DESCRIPTION

This document provides the necessary information to install and configure PAPIJAAS (for information about the PAPI protocol and its components, see http://papi.rediris.es/rep/PAPI_Protocol_Detailed.pdf).

Java Authentication and Authorization Service (JAAS) allows the integration of AA systems within any java-based environment, using a PAM (Pluggable Authentication Module) framework. More information on JAAS can be found at http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASRefGuide.html.

In the PAPI nomenclature, PAPIJAAS can be seen as a PoA.

DEPENDENCIES

This package has dependencies on the following java libraries:

1. log4j (>= 1.2.13)

2. servlet-api (>=2.4)

3. Bouncy Castle cryptographic provider (bcprov, >=133)

To generate the proper cryptographic keys, you may use OpenSSL (this document contains openssl examples of how to create them).

PAPIJAAS has been developed and tested using jdk1.5.

FILES

Files included in this version of PAPIJAAS.

papijaas.jar: Compiled and packaged distribution
jaas.config: JAAS configuration file
PoAconf.xml: PAPI configuration file
'src' folder: Source files for PAPIJAAS
LICENSE, INSTALL

INSTALLATION PROCEDURE

1. Locate a directory included in your JAVA classpath, and copy 'jaas.jar' file in it;

2. Configure 'jaas.config' file and place it where you wish;

3. Place the PoAconf.xml file where you wish, and change its content according to your needings (see ``CONFIGURATION FILE'' information below);

4. When launching your JAVA environment, the following option should be added:

 -Djava.security.auth.login.config=={jaas.config path}

5. To add JAAS based authentication on your application, you should add the following code (note that HTTP request and response must be available in order to pass them to PAPI):

 RequestCallbackHandler rch = null;
 rch = new RequestCallbackHandler(request,response);

 lc = new LoginContext("PapiJaas", rch);
 lc.login();

6. After lc.login(), if authentication is valid, the LoginContext will have all the information about the subject and principals that may be required by the application.

CONFIGURATION FILE

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

Recognized Authentication Servers.

Define here the list of trusted AS, if you are going to deal with AS requests. For each AS, and using the format <ASname.parameter>, you should specify:

desc: AS description
pubkeyName: RSA public key (not supplied) file path
URL: URL for the AS

As an example, an AS called sampleAS must be configured using values like:

 <entry key="sampleAS.desc">Sample AS for PAPIJAAS</entry>
 <entry key="sampleAS.pubkeyName">/usr/local/papi/conf/sampleASkey.pem</entry>
 <entry key="sampleAS.URL">http://my.dom.ain/AuthServer </entry>

PoA keys (compulsory).

Place the location and names of the AES keys (not supplied) used to cipher cookies (Hcook and Lcook). Specify:

PoAkeys.lkeyName: Local path to the Lcook encryption/decryption key file
PoAkeys.hkeyName: Local path to the Hcook encryption/decryption key file

PoA configuration (compulsory).

Configure the following PoA values:

PoAconf.serviceID: Service identification
PoAconf.location: Is the URI for the location the PoA is controlling access to. The PoA will try to match it against the location parameter included in an AS assertion, and will grant cookies for this location
PoAconf.path: Local path where the filter will look for PoA files, such as the cookie file
PoAconf.cookieFile: Cookie index path
PoAconf.cookieMaxAge: Maximum cookie age
PoAconf.Cookie_Reject: Access token filters to be applied by the PoA when dealing with cookies
PoAconf.Lcook_Timeout: Period of time during which Lcook tokens are valid
PoAconf.acceptURL: Defines the file holding the default URL to be sent to the user browser when a LOGIN request from an AS is accepted
PoAconf.rejectURL: Defines the file holding the default URL to be sent to the user browser when a LOGIN request from an AS is rejected
PoAconf.rejectMessage: Text message to be shown to the user when access is denied using a 403 error code
PoAconf.POST_Method: Allows two values:; manual, when the user should press a submit button when re-handling a saved POST request; to use when Javascript compatibility is not available.; javascript, when the user is automatically redirected to the originally requested URL.
PoAconf.PAPI_Filter: Access token filters to be applied by the PoA when dealing with AS or GPoA assertions
attSeparator: Attribute separator character (default value is ','). Defines the way in which attribute-value pairs are separated in user assertions
valSeparator: Value separator character (default value is '-'). Defines the way in which values for the same attribute are separated in user assertions
attValSeparator: Attribute-value separator character (default value is '='). Defines the way in which attribute and value are separated inside the pairs

GPoA configuration (optional, if parent GPoA is available).

Configuration parameters for this section are:

ParentGPoA.URL: URL for the parent GPoA
GPoA.pubkeyName: Local path to the RSA public key file for the GPoA

MORE INFORMATION

For further information on these configuration parameters, take a look on the PAPI document set, available at

http://papi.rediris.es/documents.html

or contact the PAPI Development Team, at:

papones@rediris.es

ACKNOWLEDGEMENTS

PAPIJAAS has been developed within the ITEA-OSIRIS project (http://www.itea-osiris.org), funded by the ITEA office (http://www.itea-office.org)