This document provides the necessary information to install and configure a PAPI Stand-Alone GPoA (for information about the PAPI protocol and its components, see http://papi.rediris.es/rep/PAPI_Protocol_Detailed.pdf).
SAGPoA is based on AARR (see http://www.rediris.es/app/aarr/), a java tool that, providing a concrete set of rules and a communication protocol, can emulate almost any authentication/authorization component. In the case of SAGPoA the file holding the rules is included in the distribution, and a Jetty web server is integrated within the application in order to handle HTTP requests and responses.
DEPENDENCIES
This tool needs some java libraries (log4j, xalan, jetty and Bouncy Castle cryptographic provider), which have been solved by packaging SAGPoA as a fatjar, which is similar to a jar file, but allows the inclusion of dependant libraries and solves any class loading features.
To generate the proper cryptographic keys, you may use OpenSSL (this document contains openssl examples of how to create them).
FILES
- SAGPoA_fat.jar -> SAGPoA application;
- papi_GPoA.conf -> configuration file;
- profilePAPIGPoA.xml -> GPoA profile ruleset;
- log4j.xml -> Default log4j configuration;
- README, INSTALL;
- papi_GPoA.conf -> configuration file;
SAGPoA OPERATION MODES
Depending on your configuration, SAGPoA has 3 ways of connecting to attribute sources:
- Another parent GPoA
- You'll need to specify its URL and the path to the parent GPoA's public key;
- By means of WAYF protocol, in a hardwired way (wayf:built-in)
- Shows a list of those AS's trusted by SAGPoA;
- By means of WAYF protocol, using a specific WAYF server (wayf:{URL})
- Forwards the request to the specified URL, according to PAPI wayf protocol (see http://papi.rediris.es/perl/pod/RedirectGPoA.html);
INSTALLATION PROCEDURE
Cryptographic keys
The following files should be available to SAGPoA for its operation. Note that these files are not included in the distribution:
- RSA keys
- A private (resp. public) RSA key, in order to encrypt (resp. decrypt) outgoing (resp. incoming) data. Here is an example of how to create them using OpenSSL sentences:
-
openssl genrsa 1024 -out privateKey.pem openssl rsa -in privateKey.pem -pubout -out publicKey.pem - AES keys
- To encrypt cookies. You need to create the simmetric keys 'hkey' and 'lkey', consisting of 32 bytes of arbitrary data. An easy way of creating them is by using the GNU program 'md5sum' over any file.
Configuration file
The papi_GPoA.conf file holds the configuration properties for the system. Following you will find a sample configuration, along with a brief description of each one:
<?xml version="1.0"?>
<config>
<aarrdef binding="papi_GPoA"/>
<protocol>
<issuer name="My World"/>
<GPoA path="/home/user/Proyectos/SAGPoA/conf/etc/GPoA/"
pubkeyName="pubkey.pem" privkeyName="privkey.pem"/>
<GPoAkeys path="/home/user/Proyectos/SAGPoA/conf/etc/"
lkeyName="lkey" hkeyName="hkey"/>
<GPoAconf serviceID="GPoA_0001" desc="GPoA-AARR Test"
path="/home/user/Proyectos/SAGPoA/conf/" cookieFile="cookies.txt"
cookieMaxAge="604800" Lcook_Timeout="300000" URL_Timeout="100000"
PAPI_Filter="any => accept" />
<AS name="serrano" desc="AS-AARR Test"
path="/home/user/Proyectos/SAGPoA/conf/etc/" pubkeyName="pubkey.pem"
URL="http://serrano.rediris.es/cgi-bin/AuthServer"; attSeparator=";"
attValSeparator="="/>
<AS name="harpo" desc="RedIRIS AS"
path="/home/user/Proyectos/SAGPoA/conf/etc/" pubkeyName="pubkey.pem"
URL="http://www.rediris.es/PAPI/AuthServer"; attSeparator=":"
attValSeparator="="/>
<!--
<ParentGPoA path="/home/user/Proyectos/SAGPoA/conf/GPoA/"
pubkeyName="gpoaPub.pem" privkeyName="gpoa.pem"
URL="http://localhost:1080/home/user"/>;
<ParentGPoA URL="wayf:built-in"/>
<ParentGPoA URL="wayf:http://www.rediris.es/PAPI/AuthServer"/>;
-->
<ParentGPoA URL="wayf:built-in"/>
<GPoAserverconf host="guagua.rediris.es" port="1080"
location="/papiGPoA"/>
</protocol>
<environment>
<instance type="source"/>
<workingdir path="."/>
<timeout seconds="6000" milliseconds="0" />
<datasource name="ldap rediris" type="ldap"
url="ldap://ldap.rediris.es:389/dc=aarr,dc=rediris,dc=es" />
<datasource name="fichero externo" type="file"
path="/home/user/Proyectos/SAGPoA/conf/database.csv" />
</environment>
<ruleset name="Test no. 2"
path="/home/user/Proyectos/SAGPoA/conf/profilePAPIGPoA.xml"/>
</config>
<aarrdef> section
The binding element sets the protocol to be used, as SAGPoA is AARR-based and the latter can deal with several bindings. Changing the value of this element will make SAGPoA crash.
<protocol> section
This is the key section for SAGPoA to run correctly. Values to these elements should be assigned carefully.
- <GPoA>
- Defines the directory containing SAGPoA's RSA keys, and their names;
- <GPoAkeys>
- Same as above, regarding AES simmetric keys;
- <GPoAconf>
- serviceID
- Is the service identifier used by the GPoA to identify itself when sending ATTREQ requests;
- desc
- A description of the component;
- path
- Directory which contains the cookies file;
- cookieFile
- Name of the cookie file;
- cookieMaxAge
- Time to live for Hcook;
- Lcook_Timeout
- Time to live for Lcook;
- URL_Timeout
- Period of time during which a signed URL generated by an authentication server is valid;
- PAPI_Filter
- Defines a regular expression to match against the user/group trying to access the resource, in order to accept or reject such subjects. The word 'any' can also be used to match all accesses. At the moment, it only accepts or rejects attributes named 'uid' or 'group';
- <AS>
- For each trusted AS, you should define the following parameters:
- name
- Name of the AS. Take into account that the name of the file holding this AS's public key should be named '<as_name>_<as_pubkeyname>'. For instance, if the AS is named 'foo', and the public key name is 'pubkey.pem', the file should be called 'foo_pubkey.pem';
- desc
- A description of this AS;
- path
- Directory which contains the keys;
- pubkeyName
- Name of the file containing the public key (see 'name' paragraph);
- URL
- Location of the AS;
- attSeparator
- Character that separates attribute-value pairs in user assertions received from this AS;
- attValSeparator
- Character that separates attributes and values in user assertions received from this AS;
- <ParentGPoA>
- Here you can define a parent GPoA or how to access Authentication Servers:
- Another GPoA
- The parameters to define are the same as for the <GPoA> label, except for the private key;
- Hardwired WAYF service (URL=wayf:built-in)
- This will make SAGPoA show the user a list of trusted AS's;
- Specific WAYF service (URL=wayf:{URL})
- It will forward the request to this URL;
- <GPoAserverconf>
- SAGPoA server configuration. These values will set the embedded Jetty Web Server.
<environment> section
The only relevant value in this section is <timeout>, defining the secons and milliseconds that SAGPoA will wait before the thread is suspended when no query is received;
<ruleset> section
Define the name and the file containing the ruleset for this binding;
COMMAND LINE EXECUTION
Due to the fact that the code and the dependant libraries are included in the fatjar distribution, the sentence to execute SAGPoA is very simple:
java -Dlog4j.configuration={log4j.xml file location} -jar aarr.jar {configuration file location}
where the local files holding log4j configuration and the configuration should be specified. A default log4j configuration file is supplied with the distribution.
CONTACT INFORMATION
In order to get further information, report bugs or any other issue, please contact the PAPI Development Team at papones@rediris.es.