PAPI Quick Installation Guide
=============================
These instructions let you get a minimal installation of
PAPI up and running quickly in a modern Debian/Ubuntu system.
For the sake of simplicity, we assume you are installing both
PAPI components (AS and PoA), although later we will show you
how to configure each, may be in different computers. We
use the names 'ashost' and 'poahost' as examples. Both may be the
same (localhost, for instance).
These instructions make use of the WAYF (Where Are You From)
capability of PAPI. It means that when you try to access a protected
resource (PoA), you are redirected to the AS to authenticate first, then
you are returned to the PoA, where you (most probably in real life,
certainly in this example) will be granted access. There is another way
for PAPI to work: yoy may access the AS first, and after a successfull
authentication you will be presented with a list of PoAs you can access. This
is usually caled the 'portal mode', while the one using the WAYF is usually
called (surprisingly) the 'WAYF mode'.
$ cd $BUILDDIR
$ tar xzf PAPI-1.4.1.tar.gz
$ cd PAPI-1.4.1
$ perl Makefile.PL
...
You must provide a location for installing the PAPI Authentication
Server software. It must be a directory configured to hold CGI
programs in your Apache installation [/usr/local/apache/cgi-bin]
-> /usr/lib/cgi-bin
...
The program was not able to determine a location for your OpenSSL
installation, required to build PAPI. Please type the full path to
the OpenSSL directory [/usr/local/ssl]
-> /usr
...
* If there are messages about missing Perl modules, install them and do
it again (you can skip the module Athens::DA if interaction with Athens
is not a requirement for you).
* If you don't have CGI::Lite, install it (necessary for the AS)
* Usually, this is necessary (for the PoA):
$ ln -s /usr/include/apache-1.3 /usr/include/apache
$ make
$ make install
* It will install:
/usr/lib/cgi-bin/{AuthServer,AuthServer.cf}
/usr/local/lib/perl/x.y.z/PAPI/*
/usr/local/lib/perl/x.y.z/auto/PAPI/*
/usr/bin/{pdimport,pdexport}
and several man pages
** In the AS (assuming its ID will be 'MyAS'):
$ mkdir -p /usr/local/PAPI/AS/etc
$ cp $BUILDDIR/PAPI-1.4.1/AS/etc/*html /usr/local/PAPI/AS/etc
$ cp $BUILDDIR/PAPI-1.4.1/AS/etc/Basic.sample.src /usr/local/PAPI/AS/etc/Basic.src
* Now, generate a pair of public/private keys:
$ openssl genrsa -out MyAS_privkey.pem 1024
$ openssl rsa -in MyAS_privkey.pem -pubout -out MyAS_pubkey.pem
$ mv MyAS_privkey.pem /usr/local/PAPI/AS/etc
* Send the MyAS_pubkey.pem to all the servers with PoAs that are going
to use our AS (in these systems it must be installed as
/usr/local/PAPI/PoA/KEYS/MyAS_pubkey.pem).
- If you are going to configure a PoA in this system:
$ mkdir -p /usr/local/PAPI/PoA/KEYS
$ cp MyAS_pubkey.pem /usr/local/PAPI/PoA/KEYS/MyAS_pubkey.pem
* Edit /usr/lib/cgi-bin/AuthServer.cf:
- Make sure this line exists:
use PAPI::BasicLog;
$$cfg{workingDirectory} = '/usr/local/PAPI/AS/etc';
# This SHOULD be https, but for testing you can use http
$$cfg{asLocation} = 'http://ashost/cgi-bin/AuthServer';
$$cfg{serverID} = 'MyAS';
$$cfg{privateKey} = 'MyAS_privkey.pem';
- Generate this value using, for example, md5sum:
- cat `find /var/tmp -type f -print` | md5sum | cut -c1-32
$$cfg{symKey} = "................................"
- For the first tests:
$$cfg{basicAuthDB} = "Basic.pdb"
...
$$cfg{authenticationHook} = \&PAPI::BasicAuth::VerifyUser;
$$cfg{credentialHook} = \&PAPI::BasicAuth::AllSites;
$$cfg{attrRequestHook} = \&PAPI::BasicAuth::AllSiteAttributes;
With BasicAuth, everything is configured in a simple file: Basic.pdb
- You can leave these commented out. They are tipically defined to
- point to red and green balls when you use the portal mode instead
- of WAYF, as we do in this sample setup.
#$$cfg{acceptURL} = 'http://as.papi.dom.ain/accept-file';
#$$cfg{rejectURL} = 'http://as.papi.dom.ain/reject-file';
- For the first tests, you can comment:
#$$cfg{splitModeURL} = ...
#$$cfg{splitModeParamList} = ...
- Logging:
$$cfg{logHook} = \&PAPI::BasicLog::FileLog;
$$cfg{logFile} = "/var/tmp/PAPIAS.log";
* Define at least one user and one site (PoA) for BasicAuth to use
In /usr/local/PAPI/AS/etc/Basic.src append the following lines
IMPORTANT: Change 'poahost'! It must match the name you use to access
the PoA:
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
# User 'papitest', password: 'papitest'
user::papitest::hw0rgZVZz0QRs::::::
#
site::PAPI_test_site::PAPI Test site::http://poahost::/PAPI/cookie_handler.cgi::1800::TestPoA::/papi::index.html::
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
$ cd /usr/local/PAPI/AS/etc
$ pdimport -n -s Basic.src Basic.pdb
** In the PoA:
If you have not done this before:
- mkdir -p /usr/local/PAPI/PoA/KEYS
- mv ..../MyAS_pubkey.pem /usr/local/PAPI/PoA/KEYS
(The name *MUST* be the ID of the AS with "_pubkey.pem" appended).
- ps -ef | md5sum | cut -c1-32 > /usr/local/PAPI/PoA/lkey
- cat /var/log/messages | md5sum | cut -c1-32 > /usr/local/PAPI/PoA/hkey
- chown -R www-data /usr/local/PAPI
- Configure one simple PoA. At the end of /etc/apache/httpd.conf:
include "papi.conf"
- Contents of the file /etc/apache/papi.conf (change 'ashost'):
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
PerlModule PAPI::Conf
Service_ID test_PoA
Debug 1
HKEY_File /usr/local/PAPI/PoA/hkey
LKEY_File /usr/local/PAPI/PoA/lkey
Lcook_Timeout 60
CRC_Timeout 30
URL_Timeout 200
Auth_Location /PAPI/cookie_handler.cgi
Accept_File /usr/local/PAPI/PoA/blueball.png
Reject_File /usr/local/PAPI/PoA/redball.png
Pubkeys_Path /usr/local/PAPI/PoA/KEYS
Hcook_DB /usr/local/PAPI/PoA/hcook.db
PAPI_AS MyAS http://ashost/cgi-bin/AuthServer Test AuthServer
PerlSendHeader On
PerlAccessHandler PAPI::Main
Service_ID TestPoA
GPoA_URL wayf:built-in
Req_DB /usr/local/PAPI/PoA/req_TestPoa
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
* In the PoA server (poahost), create the protected pages:
$ mkdir /var/www/papi
$ cat < /var/www/papi/index.html
You have reached this PoA !
END
* In the PoA server (poahost):
$ /etc/init.d/apache restart
* In any browser, try to access:
http://poahost/papi/index.html
Your browser will be redirected to the AS for authentication and
then to the protected pages. To authenticate use papitest/papitest
*** Configuration of a GPoA
A GPoA is a special kind of PoA that sits between regular PoAs
and an AS. You can configure the PoAs so that they don't
communicate with the AS, but with the GPoA, and in that case
you don't have to configure the PoAs in the AS, just the
GPoA. It is specially useful because some implementations of
the PAPI protocol (such as phpPoA and the PAPIFilter for
java based resources) rely on a GPoA to work.
The only differences between a GPoA and a regular PoA are:
- You must generate a pair of public and private keys
for the GPoA
- In the Apache configuration of a GPoA you must declare
the GPoA_Priv_Key directive
- The public key of the GPoA must be installed by the PoAs
using it
A regular PoA can use a GPoA just declaring its URL in
the GPoA_URL Apache directive.
$ openssl genrsa -out GPoA_privkey.pem 1024
$ openssl rsa -in GPoA_privkey.pem -pubout -out GPoA_pubkey.pem
$ mv GPoA_pubkey.pem /usr/local/PAPI/PoA/KEYS/_GPoA_pubkey.pem
(the directory must math the Pubkeys_Path Apache directive
and the filename must be exactly that)
$ mkdir /usr/local/PAPI/GPoA
$ mv GPoA_privkey.pem /usr/local/PAPI/GPoA
(you can put it anywhere, you just have to declare its
path in the GPoA_Priv_Key Apache directive inside the
GPoA configuration).
Append these lines to the Apache configuration and restart Apache:
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
PerlSendHeader On
PerlAccessHandler PAPI::Main
Service_ID TestGPoA
GPoA_URL wayf:built-in
Req_DB /usr/local/PAPI/PoA/req_TestGPoA
GPoA_Priv_Key /usr/local/PAPI/GPoA/GPoA_privkey.pem
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
Next you must declare the GPoA in the Basic.src file as any
regular PoA (Remember to change 'poahost'! ):
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
site::PAPI_test_gpoa::PAPI Test GPoA::http://poahost::/PAPI/cookie_handler.cgi::1800::TestGPoA::/gpoa::index.html::
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
* Using the GPoA
The previously defined PoA can use this GPoA just
declaring:
GPoA_URL http://poahost/gpoa/PAPI/cookie_handler.cgi
instead of 'GPoA_URL wayf:built-in'
For example (create /var/www/papi_gpoa/index.html and change 'poahost'!):
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
PerlSendHeader On
PerlAccessHandler PAPI::Main
Service_ID TestPoA_GPoA
GPoA_URL http://poahost/gpoa/PAPI/cookie_handler.cgi
Req_DB /usr/local/PAPI/PoA/req_TestPoa_GPoA
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
This way you don't have to declare this PoA in Basic.src
** Finally
* Watch the logs!
- Messages generated by the AS will go to /var/tmp/PAPIAS.log
- Messages generated by the PoA go to the Apache error_log
* If something goes wrong, do not forget to clear the cookies
before starting over!