DESCRIPTION
PAPI is a system for providing access control to restricted information resources across the Internet. It intends to keep authentication as an issue local to the organization the user belongs to, while leaving the information providers full control over the resources they offer. The authentication mechanisms are designed to be as flexible as possible, allowing each organization to use its own authentication schema, keeping user privacy, and offering information providers data enough for statistics. Moreover, access control mechanisms are transparent to the user and compatible with the most commonly employed Web browsers, i.e., Netscape/MSIE/Lynx, and any operating system.
The system consists of two independent elements: the authentication server (AS) and the point of access (PoA). This structure makes the final system much more flexible and able to be integrated to different environments. There is no need of a one-to-one mapping between ASs and PoAs: a given PoA may manage to deal with requests from any number of ASs and direct them to any number of web servers.
The purpose of the AS is to provide users with a single authentication point and make available to them (in a completely transparent manner) all the temporary keys that will let them access the services they are authorized to.
The PoA manages actual access control to a set of web locations for a given organization. The information provider (or the owner of the web servers) have the responsibility of managing this point of access. A PAPI PoA can be adapted to any web server, whatever its implementation is. Moreover, a given web server can have more than one PoA, and a PoA can control more than one web server. Other important property of this system is that is completely compatible with any other access control system in use, since it does not impose any constraints on additional procedures used for these purposes. In other words, PAPI access control is completely orthogonal to procedures such as password protection, IP filters, TLS-based access control, etc.
A more detailed discussion on the PAPI objectives, components and protocols can be found in the PAPI web pages and the PAPI Guide for Beginners.
BUILDING AND INSTALLING PAPI
Building and installing PAPI is straightforward. You just have to unzip and untar the distribution, go the PAPI source directory and execute the following commands:
# perl Makefile.PL # make # make install
The installation procedures check for the availability of the required elements you have to install on your system prior to PAPI. These elements are:
- Perl >= 5.6
- openssl >= 0.9.5 (openssl >= 0.9.6g is recommended)
- The Perl CGI::Lite package
- The Perl Convert::ASN1 package
- The Perl DB_File package
- The Perl Digest::MD5 package
- The Perl MIME::Base64 package
- The Perl URI::Escape package
- openssl >= 0.9.5 (openssl >= 0.9.6g is recommended)
These elements are only required if building a PAPI PoA:
- Apache >= 1.3.8
- The current version of PAPI only runs on Apache (and mod_perl) versions 1.x. A port of PAPI to Apache 2 is under development.
- Apache's mod_perl >= 1.20
- When building mod_perl, remember to build it with EVERYTHING=1.
- The Perl Data::Dumper package
- The Perl HTML::TokeParser package
- The Perl HTML::TreeBuilder package
- The Perl HTTP::Cookies package
- The Perl HTTP::Request::Form package
- The Perl LWP::UserAgent package (>= 2.001)
- The Perl MLDBM package
- The Perl MLDBM::Sync package
- The Perl URI::URL package
- The Perl AthensDA package, a valid Athens institutional ID and a valid key to run Athens Devolved Authentication procedures
- The Perl HTML::TokeParser package
- If you plan to provide access to Athens-enabled resources using PAPI. See http://www.athensams.net/ and http://www.athensams.net/development/devolved_authentication/ for more details.
- The SPOCP authorization server
- If you plan to implement your authorization policy by means of a SPOCP server (see http://www.spocp.org/).
These elements are only required if building a PAPI AS:
- The Perl Sys::Syslog package
- If Unix syslog-based logging is required.
- The Perl Net::LDAP package (>= 0.30)
- The Perl Net::LDAP::Entry package
- The Perl Net::LDAP::Message package
- The Perl Net::LDAP::Search package
- The Perl Net::LDAP::Entry package
- If LDAP-based authentication is required.
- The Perl Mail::POP3Client package
- If POP-based authentication is required.
- The Perl Net::IMAP::Simple package
- If IMAP-based authentication is required.
- The Perl Time::Local package
- If X509 certificate-based authentication is required.
The installation procedures install the PAPI library packages and the components of the PoA according to your host Perl installation, so you can use them from any program (including Apache itself for running the PoA) using standard Perl procedures, like use.
The authentication server and its associated files are installed in the directory selected during the configuration phase, when the command perl Makefile.PL was executed (by default, /usr/local/apache/cgi-bin). You can copy (or move) them as required.
RUNNING PAPI
Authentication Server
The PAPI Authentication Server built for this version of PAPI is a Perl program intended to be run as a CGI by the Web server. You should install the file AuthServer (the AS executable file) in any location your Web server is able to execute CGIs from. It is highly configurable and its designed to support different methods for authentication, credential generation and logging, by means of hooks, intended to contain references to functions performing the actual tasks. This distribution comes with some of these functions, so administrators may hook them as appropriate, or develop their own methods using the ones in the distribution as examples.
The configuration of the AuthServer is stored into a configuration file, with the same name as the AuthServer itself and the extension .cf. This means that, if you run the AuthServer with its default name, the configuration file is called AuthServer.cf. The configuration file is itself a Perl source file, so you can use whatever Perl statements to configure the AuthServer. Configuration is stored inside a hash named %PAPI::AuthServer::cfgVar, so the statements into the configuration file should end writing to this hash.
A list of the minimum set of required configuration variables, and more information about the PAPI Authentication Server in this distribution can be found in the AuthServer page. For the extra configuration variables required by the different authentication methods provided in this distribution, look at their corresponding pages:
- Basic PAPI authentication
- LDAP-based authentication
- POP-based authentication
- IMAP-based authentication
- X.509 certificate-based authentication
- Basic PAPI logging
- LDAP-based authentication
Point of Access
A PAPI Point of Access grants or denies the access to the network resources it controls using the cryptographic tokens defined by the PAPI protocol. The PoA included in this distribution is designed to be used with Apache's mod_perl, and makes an extensive use of the Apache Perl API.
The configuration of the PoA is made directly inside the Apache configuration file. To activate PAPI configuration directives you must include the following directive before using any of them:
PerlModule PAPI::Conf
The recommended practice is to provide a set of common or default values for all the PoAs hosted by the Apache server using the section <PAPI_Main>:
<PAPI_Main> . . . [Common/default PAPI PoA directives] . . . </PAPI_Main>
To establish a PAPI PoA you just have to add the following two lines inside the appropriate <Location> section in the Apache configuration file:
PerlSendHeader On PerlAccessHandler PAPI::Main
Using the section <PAPI_Local> after the two PoA activation lines it is possible to apply specific PAPI directives to this PoA:
<PAPI_Local> . . . [Specific PAPI PoA directives] . . . </PAPI_Local>
More information about the configuration and behavior of the PAPI PoA included in this distribution can be found in the documentation pages for each of its components: