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,} /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/ - 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!