These instructions let you get a minimal installation of
PAPI up and running quickly in a modern Debian/Ubuntu system.
For sake of simplicity, we assume you are installing both
PAPI components (AS and PoA), althouh later we show you
how to configure each, maybe in different computers. We
use the names 'ashost' and 'poahost' as examples. Both may be the
same (localhost, for instance). We will use <Location> directives
although using virtual hosts is usually better.
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 other way
it works: yoy may access the AS for the first time, and after successfully
authentication you will be presented a list of PoAs you can access (you
can call this the 'portal 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 it's 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, all 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)
BasicAuth uses
In /usr/local/PAPI/AS/etc/Basic.src append these 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 didn't 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
<PAPI_Main>
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
</PAPI_Main>
<Location /papi>
PerlSendHeader On
PerlAccessHandler PAPI::Main
<PAPI_Local>
Service_ID TestPoA
GPoA_URL wayf:built-in
Req_DB /usr/local/PAPI/PoA/req_TestPoa
</PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
* In the PoA server (poahost), create the protected pages:
$ mkdir /var/www/papi
$ cat <<END > /var/www/papi/index.html
<html>
You have reached this PoA !
</html>
END
* In the PoA server (poahost):
$ /etc/init.d/apache restart
* In any browser, access to:
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 PoA's
and an AS. You can configure the PoA's so that they don't
communicate with the AS, but with the GPoA, and in that case
you don't have to configure the PoA's 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) are not complete and rely on a
GPoA to work.
The only differences among 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 copyed to a
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 >>>>>>>>>>>>>>>>>>>>>>
<Location /gpoa>
PerlSendHeader On
PerlAccessHandler PAPI::Main
<PAPI_Local>
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
</PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
Next you must declare the GPoA in the Basic.src file as it where
a 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 >>>>>>>>>>>>>>>>>>>>>>
<Location /papi_gpoa>
PerlSendHeader On
PerlAccessHandler PAPI::Main
<PAPI_Local>
Service_ID TestPoA_GPoA
GPoA_URL http://poahost/gpoa/PAPI/cookie_handler.cgi
Req_DB /usr/local/PAPI/PoA/req_TestPoa_GPoA
</PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< 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, clear the cookies before starting over!
