SYNOPSIS

Inside the Apache configuration file:

 <PAPI_...>
 . . .
 
 PADATH_LAA_Handler              athens_resource_list.html
 PADATH_HDD_Handler              athensHDD
 PADATH_Insititution_ID          MYATHENSIID
 PADATH_Athens_AuthPoint         https://auth.athensams.net/
 PADATH_Key                      /opt/PAPI/athensKey
 PADATH_Permission_Set_Attribute apset
 PADATH_User_Id_Attribute        auid
 . . .

REQUIRES

The AthensDA Perl package.

A valid institutional ID and a valid key to run Athens Devolved Authentication procedures.

See http://www.athensams.net/ and http://www.athensams.net/development/devolved_authentication/ for more details.

DESCRIPTION

This package provides functions to connect a PAPI PoA to Athens-enabled resources by means of the mechanisms defined by Athens Devolved Authentication (AthensDA).

According to these mechanisms, the PoA is able to act as a Athens XAP (eXtensible Authentication Point), both in HDD (Home Domain Discovery) and LAA (Local Authentication Assertion) modes. For more details, see the AthensDA documents.

Eight configuration directives are related to PAPI-Athens interoperation:

PADATH_LAA_Handler location

URI which will trigger Athens interactions in LAA mode.

When a request for this location is received and accepted by the PAPI authorization mechanisms, the PoA will contact the AAP (Athens Authentication Point) in order to establish a Athens session.

PADATH_HDD_Handler location

URI which will answer AAP queries in HDD mode.

When a request for this location is received and accepted by the PAPI authorization mechanisms, the PoA will assume it is coming from the AAP, validate the HDD query, and produce the appropriate response, sending it back to the AAP.

PADATH_Institution_ID AthensIdentifier

The Athens institution ID to be used, as provided by Athens.

PADATH_Athens_AuthPoint URL

The URL for the AAP, where queries and responses are sent by the PADATH functions. It must follow the specification of Athens for your institution. The default value is ``https://auth.athensams.net/''.

PADATH_Key filename

The name of the file containing the encryption key used for the interactions of PADATH with the AAP. It must contain the data provided by your Athens Devolved Authentication agreeement, in the format expected by the AthensDA package: a single line consisting of a string composed of the cipher identifier (AES is the only currently supported cipher), a colon, and the value of the key as supplied by Athens.

PADATH_Permission_Set_Attribute attributeName

The attribute, from those included inside the user assertion the PoA is using, that contains the Athens permission set to be used in the interactions with the AAP. By default, it takes the value ``AthensPermissionSet''.

PADATH_User_Id_Attribute attributeName

The attribute, from those included inside the user assertion the PoA is using, that contains the value to be sent to the AAP as user identifier. By default, it takes the value ``uid''.

PADATH_AAP_TTL seconds

Defines the maximum acceptable shift in the timestamps of AthensDA packets received from the AAP. By default, it takes the value recommended by the AthensDA documents: 60 seconds.

FUNCTIONS

PADATH::reqLAA ($request, $poadef)

This function is called to generate an initial request to the AAP in LAA mode. It encodes the data requested by the AAP (from the attributes within the assertion used by the PoA), including a return URI that will make the PoA call the PADATH::respLAA function with the appropriate parameters when the AAP answers the request.

PADATH::respLAA ($request,$poadef)

This function is called when a response from the AAP is recieved in LAA mode. It validates the response and redirects the user's browser to the actual location that was intended to be accessed when the LAA procedure was started through PADATH::reqLAA

PADATH::respHDD ($request, $poadef)

This function validates the request coming from the AAP and builds the appropriate response from the attributes within the assertion used by the PoA, sending it to the AAP via a HTTP redirect.

Arguments:

$request: An Apache Request object, containing the data for the user's request.

$poadef: A PoA object, containing the configuration for this PoA.

SEE ALSO

PAPI Configuration

PAPI Handler

PAPI PoA for Apache