PAPI::BasicAuth - Perl functions to provide PAPI authentication data using a DB_File database

SYNOPSIS

Inside the AuthServer.cf file:

 $cfg = \%PAPI::AuthServer::cfgVar;
 
 $$cfg{workingDirectory} = "/usr/local/PAPI/AS/etc";
  
 . . .
 
 $$cfg{authenticationHook} = \&PAPI::BasicAuth::VerifyUser;
 $$cfg{credentialHook} = \&PAPI::BasicAuth::UserCredentials;
 $$cfg{attrRequestHook} = \&PAPI::BasicAuth::UserAttributes;
 $$cfg{basicAuthDB} = "Basic.pdb";

A sample source file for the database:

 # Sample BasicAuth source file. All passwords are "password"
 # You must run 'pdimport' on this file.
 # Users
 user::user1::papAq5PwY/QQM::::group1::
 user::user2::papAq5PwY/QQM::::group1::
 user::user3::papAq5PwY/QQM::::group2::
 user::user4::papAq5PwY/QQM::::group2::
 # Groups
 group::group1::group1::siteA,siteB
 group::group2::group2::siteA
 # Sites
 site::siteA::Sample Site A::http://site.a::PAPIPoA::1800::sitea::/::index.html::<papi var="PAPIgid"/>
 site::siteB::Sample Site B::http://site.b::PAPIPoA::1800::siteb::/::index.html::

The database can be built using:

 # pdimport -n -s sample.source.file sample.database

DESCRIPTION

These functions implement PAPI user authentication and credential data provision using a simple hash-tied Berkeley DB database. The database can be easily managed by means of the programs pdexport and pdimport, included into the BasicAuth source directory.

The database holds three classes of resources: users, groups and sites. Each resource has an identifier (the resource ID) and is stored inside the Berkeley DB database using the string ``CLASS::ID'' as key. CLASS may be any of the class identifiers: user, group, or site. Data is stored in the form of a string of fields, using ``::'' as separator. For each class of resources these data are:

User resources
```
    PASSWORD::ALT::GROUPLIST::SITELIST
```
Where:

PASSWORD
Password for this user (crypt() encoded)

ALT

Alternate name for this user

GROUPLIST

Comma-separated list of group IDs this user belongs to

SITELIST

Comma-separated list of site IDs this user has access to

Group resources
```
    ALT::SITELIST
```
Where:

ALT
Alternate name for the users in this group

SITELIST

Comma-separated list of site IDs this group has access to

Site resources

    DESC::POA::AUTHURI::TTL::SERVICE::LOCATION::ACCESSURI::ASSERTION

Where:

DESC: Textual description of the site

POA

Base URL (method, server and, optionally, port) for the Point of Access for this site

AUTHURI

URI for requesting tokens to the Point of Access (relative to the value of LOCATION)

TTL

Time to live for the tokens requested to the PoA for this site

SERVICE

Service identifier at the PoA for this site

LOCATION

Start location at the PoA for this site

ACCESSURI

URI for initially accessing content protected by the PoA at this site (relative to the value of LOCATION)

ASSERTION

Format of the assertion on user attributes to be sent to the PoA for this site.

FUNCTIONS

VerifyUser($con, $cfg): This function is intended to be hooked at the authenticationHook in a PAPI AuthServer. It uses the connection variables username and password to validate them against the DB database defined by the configuration variable basicAuthDB.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
UserCredentials($con, $cfg): This function is intended to be hooked at the credentialHook in a PAPI AuthServer. It uses the connection variable username to return a list of site definitions the user can connect to. It returns data for the sites included in the user entry itself and in the entries for those group the user belongs to. The Berkeley DB database to be accessed must be defined by the configuration variable basicAuthDB.; If the configuration variable useDefaultSite exists and is set to a non-zero value, it also includes an empty site definition, so the AuthServer appends a new site using the default values it is applying.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
GroupList($con, $cfg): This function is intended to be hooked at the credentialHook in a PAPI AuthServer. It returns a site list consisting of the sites related to the groups whose identifiers are included into the configuration variable groupList. The list has to be comma-separated.; If the configuration variable useDefaultSite exists and is set to a non-zero value, it also includes an empty site definition, so the AuthServer appends a new site using the default values it is applying.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
AllSites($con, $cfg): This function is intended to be hooked at the credentialHook in a PAPI AuthServer. It returns a site list consisting of all the sites included into the database.; If the configuration variable useDefaultSite exists and is set to a non-zero value, it also includes an empty site definition, so the AuthServer appends a new site using the default values it is applying.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
DefCredentials (): This function is intended to be hooked at the credentialHook in a PAPI AuthServer. It just returns an empty site list, so the default values configured for the AuthServer are used. To be used as a stub when no other more sophisticated credentials assignment methods are requested.; Arguments:; None
UserAttributes($con, $cfg): This function is intended to be hooked at the attrRequestHook in a PAPI AuthServer. It uses the connection variable PAPIPOAURL to look for a defined site in the database acceptable to the user. The user id is read from the connection variable PAPIuid (probably derived by the AuthServer from a authentication coookie). If a suitable site is found, it returns the assertion format and the time-to-live defined for the site. If no site is found matching the requesting URL, it sets the PAPIerror variable and a negative value is returned.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
GroupListAttributes($con, $cfg): This function is intended to be hooked at the attrRequestHook in a PAPI AuthServer. It uses the connection variable PAPIPOAURL to look for a defined site in the database acceptable to a list of groups, identified by the configuration variable groupList. If a suitable site is found, it returns the assertion format and the time-to-live defined for the site. If no site is found matching the requesting URL, it sets the PAPIerror variable and a negative value is returned.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
AllSiteAttributes($con, $cfg): This function is intended to be hooked at the attrRequestHook in a PAPI AuthServer. It uses the connection variable PAPIPOAURL to look for a defined site in the database. If a suitable site is found, it returns the assertion format and the time-to-live defined for the site. If no site is found matching the requesting URL, it sets the PAPIerror variable and a negative value is returned.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.
DefAttributes($con, $cfg): This function is intended to be hooked at the attRequestHook in a PAPI AuthServer. It uses the connection variable PAPIPOAURL to match against the default site defined for the AuthServer. It can be used as a stub when no other more sophisticated methods are requested.; Arguments:; $con: Hash with the PAPI AuthServer connection variables.; $cfg: Hash with the PAPI AuthServer configuration variables.

SYNOPSIS

DESCRIPTION

FUNCTIONS

SEE ALSO