PAPI::Conf - PAPI PoA configuration facilities

REQUIRES

Perl >= 5.6, Exporter, DynaLoader, AutoLoader

SYNOPSIS

Prior to any PAPI configuration directive, the httpd.conf file must contain:

 PerlModule PAPI::Conf

Default and/or common values for the PAPI configuration must go inside PAPI_Main sections:

 <PAPI_Main>
    HKEY_File     /usr/local/PAPI/PoA/hkey
    LKEY_File     /usr/local/PAPI/PoA/lkey
    Service_ID    defaultPAPIserviceID
    Lcook_Timeout 60
    CRC_Timeout   30
    URL_Timeout   200
    Auth_Location /PAPI/cookie_handler.cgi
    Accept_File   /usr/local/PAPI/PoA/blueball.gif
    Reject_File   /usr/local/PAPI/PoA/redball.gif
    Pubkeys_Path  /usr/local/PAPI/PoA/KEYS
    Hcook_DB      /usr/local/PAPI/PoA/hcook.db
    PAPI_AS       authserv1 http://as1.dom.ain/AuthServer Common PAPI AuthServer
    PAPI_AS       authserv2 http://as2.dom2.ain2/cgi/AS Another PAPI AuthServer
 </PAPI_Main>

The rest of directives configuring different PAPI-protected resources must go inside PAPI_Local sections.

Protecting a location local to the server the PoA lives in:

 <Location /papi/local>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID local
 # This directive makes the PoA reject all requests coming from any
 # user that the corresponding AuthServer identifies as "default"
       PAPI_Filter default => reject
    </PAPI_Local>
 </Location>

Protecting a whole remote server:

 <VirtualHost 1.2.3.4>
    ServerName remote.papi.dom.ain
    <Location />
       PerlSendHeader On
       PerlAccessHandler PAPI::Main
       <PAPI_Local>
          Service_ID remote
          Remote_URL http://remote.dom.ain
 # This directive makes all links to remote2.dom.ain in pages served
 # by the PoA to be redirected through the PoA as well
          PAPI_Redirect http://remote2.dom.ain http://remote.papi.dom.ain
       </PAPI_Local>
    </Location>
 </VirtualHost>

Accessing locations at a remote server protected by HTTP Authentication:

 <VirtualHost 1.2.3.4>
    ServerName remote.papi.dom.ain
    <Location />
       PerlSendHeader On
       PerlAccessHandler PAPI::Main
       <PAPI_Local>
          Service_ID remoteprot
          Remote_URL http://remote.dom.ain
          HTTP_Auth realm::user::password
       </PAPI_Local>
    </Location>
 </VirtualHost>

Accessing locations at a remote server protected by form authentication:

 <VirtualHost 1.2.3.4>
    ServerName remote.papi.dom.ain
    <Location />
       PerlSendHeader On
       PerlAccessHandler PAPI::Main
       <PAPI_Local>
          Service_ID remoteprot
          Remote_URL http://remote.dom.ain
          Form_Processor urlre => http://remote.dom.ain/authenForm
                         field => (username, theUser)
                         field => (password, thePassword)
       </PAPI_Local>
    </Location>
 </VirtualHost>

Protecting a whole remote domain:

 <VirtualHost 1.2.3.4>
    ServerName remotedom.papi.dom.ain
    <Location />
       PerlSendHeader On
       PerlAccessHandler PAPI::Main
       <PAPI_Local>
          Service_ID remotedom
          Remote_Domain dom.ain
       </PAPI_Local>
    </Location>
 </VirtualHost>

Defining a PoA that depends on a parent GPoA:

 <Location /papi/local>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID localchild
 # This directive defines a database for storing parameters for
 # requests made using the POST method
       Req_DB /usr/local/PAPI/PoA/localChildReqs.db
       GPoA_URL http://gpoa.dom.ain/GPoA/PAPI/cookie_handler.cgi
    </PAPI_Local>
 </Location>

Defining a GPoA:

 <Location /GPoA>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID parent
       GPoA_Priv_Key /usr/local/PAPI/PoA/gpoaKey.pem
    </PAPI_Local>
 </Location>

Defining a PoA able to send queries back to the recognized authentication servers

 <Location /papi/local>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID wayfenabled
       Req_DB /usr/local/PAPI/PoA/WayfReqs.db
# The GPoA is implemented by a WAYF service (locates the appropriate AS)
       GPoA_URL wayf:built-in
    </PAPI_Local>
 </Location>

Defining a PoA to interoperate with Athens:

 <Location /AthensConnect>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID athensconnect
       PADATH_LAA_Handler athens_resource_list.html
       PADATH_HDD_Handler athensHDD
       PADATH_Insititution_ID MYATHENSIID
       PADATH_Athens_AuthPoint https://auth.athensams.net/
       PADATH_Key /usr/local/PAPI/athensKey
       PADATH_Permission_Set_Attribute AthensPermissionSet
       PADATH_User_Id_Attribute AthensID
    </PAPI_Local>
 </Location>

Using an external authorization server based on SPOCP:

 <Location /spocpPoA>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
       Service_ID spocp-based
# Ask SPOCP server in spocp.localdomain using action "access"
       SPOCP_Server spocp.localdomain:3456
       SPOCP_Action access
    </PAPI_Local>
 </Location>

DESCRIPTION

This module contains all the configuration functions for PAPI PoAs living inside an Apache server. Configuration is performed by means of specific tags in the Apache configuration file. These tags may appear inside the sections:

<PAPI_Main>: For options applicable to all PAPI PoAs living in the same server. This section can only appear outside any local section (i.e., <Location>)
<PAPI_Local>: For options applicable to a particular PoA. This section can only appear inside a <Location> section.

The tags recognized by the configuration methods inside <PAPI_Main> and <PAPI_Local> sections are as follows:

HKEY_File filename

Defines the name of the file containing the encryption key for the Hcook tokens. The file must contain a single line with a string of up to 32 hexadecimal characters ([0-9a-fA-F]).

This file should have very restrictive access permissions.

LKEY_File filename

Defines the name of the file containing the encryption key for the Lcook tokens. The file must contain a single line with a string of up to 32 hexadecimal characters ([0-9a-fA-F]).

This file should have very restrictive access permissions.

Service_ID serviceName

This is the name the PAPI system uses for internally identifying a PoA. You can also use the tag Server, although its use is deprecated.

Hcook_DB filename

File (in Berkeley DB database format) where this PoA is going to record the Hcook tokens and their properties. The user ID the web server is running must have write access to this file.

Accept_File filename

File holding the default object to be sent to the user's browser when an action (LOGIN, TEST, LOGOUT) is accepted, and the request for that action did not contain a AURL parameter.

Reject_File filename

File holding the default object to be sent to the user's browser when an action is rejected, and the request for that action did not contain a RURL parameter.

Pubkeys_Path directoryName

Directory where public keys of the authentication servers are stored. Each recognized authentication server public key must be stored in a separate file under this directory. The file name must be ASName_pubkey.pem, where ASName is the name assigned to the authentication server (see PAPI_AS below). The key must be in PEM format. If a GPoA is defined for this PoA (see below), the public key for it must be stored in a file named _GPoA_pubkey.pem.

Domain domainName

Name of the web server this PoA belongs to. This parameter is the ``domain'' field used whenever cookies holding tokens are generated.

Auth_Location location

URI for dealing with direct connections between the PoA and PAPI authentication servers.

When a request for this location is received, the PoA checks whether it contains the string PAPIASRedirector (see RedirectGPoA and the Main Handler for details of the WAYF interface). In this case, it redirects the request to the appropriate authentication server. Otherwise, an assertion coming from the authentication server is going to be evaluated, and thus passed to the authorization requests handler.

By default, the value /PAPI/cookie_handler.cgi is used.

Signoff_Location regularExpression URL

Requests that fire a sign-off process.

When a request for a location matching the regular expression is received the PoA will proceed to invalidate access tokens and redirect the requesting client to URL, where the sign-off process can be continued.

Pass_URL_Pattern regularExpression

This directive allows the definition of a regular expression that will be matched against the requested URL. If the expression matches, the PAPI access checkings are not performed and access is automatically granted.

Hcook_Handler regularExpression

URIs containing elements that require the contents of Hcook. Locations matching the regular expression will receive, through both an Apache note (with identifier PAPIHcook) and a request header (added by the PAPI PoA to the request and called X-PAPI-Hcook), the current value of the token contained into Hcook.

Hcook_Generator functionName

Function to be used for generating the actual contents of Hcook and Lcook. The function receives two parameters: the assertion value (as received from the AS or GPoA) and the identifier of the AS that generated it. It must return a string containing the data about the user to be encoded inside access tokens. A fully qualified Perl function identifier (the usual form is Package::Function) must be used.

Lcook_Timeout seconds

Period of time during which Lcook tokens are valid.

CRC_Timeout seconds

Period of time during which URL requests with Hcook tokens containing an old random control block are considered valid by this PoA.

URL_Timeout seconds

Period of time during which a signed URL generated by an authentication server is valid. This time is measured from the moment the authentication server created the signed URL.

Max_TTL seconds

Maximum time-to-live for tokens generated at the PoA. If this parameter is used, any longer TTL value requested by an AS will be cut to the Max_TTL value.

PAPI_AS ASName ASURL ASDescription

Definition of a PAPI authentication server that is valid for this PoA. The name is used to locate the appropriate public key, the URL may be used to query the authentication server as a GPoA (if a WAYF service is defined, see below).

PAPI_Filter regularExpression => [accept|reject]

Definition of a filter applicable to this PoA. The filter definition is a regular expression to be matched against the assertion about the user that the PoA is going to receive from Authentication Servers. The filter value can be either accept (to let the request proceed and generate access tokens) or reject (to refuse the request). Filters are applied in the same order they appear in the configuration, first local filters defined inside the <PAPI_Local> section, and then global filters defined inside the <PAPI_Main> section. For back compatibility, a catch-all implicit filter equivalent to:

 PAPI_Filter .* => accept

is assumed

Cookie_Reject regularExpression

Definition of a cookie reject filter applicable to this PoA. If the user data inside the tokens matches against the regular expression, the request for access will be denied. This allow for immediate revocation of user's rights. This immediate filters are applied in the same order they appear in the configuration, first local filters defined inside the <PAPI_Local> section, and then global filters defined inside the <PAPI_Main> section.

Hash_User_Data [1|0]

If set to 1, the user data received from the AS is transformed through a hash function. This way, access to the cookies (even decrypting them) does not reveal data about users. This also applies to PoAs subordinated to a GPoA.

User_Data_Rewrite regularExpression replacementString

With this directive, the assertion received for a certain access request can be rewritten in order to be stored inside the access tokens. As many of these directives as required may be defined. The current value of the access assertion is matched against (and possibly substituted) the regular expression of the corresponding directive, according to the order in which they are defined in the configuration file. Both the regular expression and the replacement string follow Perl conventions.

Client_Address_In_Tokens [1|0]

If set to 1, client IP address is included into user data inside access tokens, and verified upon reception. A mismatch makes access to be denied. It allows the binding of a PAPI session to a certain address, possibly required by some PAPI applications.

Attribute_Separator separatorString

The string defines the characters that will be used by the PoA to identify each individual attribute inside an assertion (either inside an access token or coming from an AS or GPoA). Blanks are always included in the list of separators. By default, it takes the value ``,''.

Value_Separator separatorString

The string defines the characters that will be used by the PoA to identify the attribute names and values for each individual attribute inside an assertion (either inside an access token or coming from an AS or GPoA). Blanks are always included in the list of separators. By default, it takes the value ``=''.

Max_Nonce_Errors number

The value of this parameter defines the maximum number of times that invalid access tokens (those with a nonce field that does not match the one in the token database) will be accepted prior to issuing a collision, that is, an attempt of invalid access by cookie duplication. By default, it is set to 3.

Debug [1|0]

If set to 1, the debug mode is activated.

The following tags are only applicable to PoAs used to connect to Athens-enabled resources using the mechanisms defined by Athens Devolved Authentication (AthensDA) (see http://www.athensams.net/development/devolved_authentication/ for details):

PADATH_LAA_Handler location: URI which will trigger Athens interactions in LAA (Local Authentication Assertion) 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 (Home Domain Discovery) 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.

The following tags are only applicable to PoAs using an external authorization server based on SPOCP (see http://www.spocp.org/ for details):

SPOCP_Server serverSpec: Defines the location of the SPOCP server to be used. Two formats can be used to specify the server location:; 1. If serverSpec begins with the '/' character, an internal socket (in the ``UNIX'' domain) is assumed, and the SPOCP server will be contacted using it.; 2. In any other case, a TCP connection will be attempted, and the well-known format host:port shall be used to define it.
SPOCP_Action actionName: Defines the name of the action to be used when querying the SPOCP server (by default, it takes the value accept).
SPOCP_Accept_If_Down [1|0]: If set to 1, a failure in connecting to the SPOCP server will be considered a positive response to any authorization query. If set to 0 (the default), a failure in connecting to the SPOCP server will cause the PoA to reject the solicited access.

The following tags are only applicable to PoAs belonging to a hierarchy of points of access that share a common policy, where initial requests for access are resolved at a parent Groupwide-PoA (a GPoA):

GPoA_URL URL: The URL for accessing the authorization procedures of the GPoA this PoA is associated with. It can contain:; 1. A ``normal'' URL, using a standard method (typically http). In this case, it must point to the URL corresponding to the Auth_Location (see above) of the GPoA.; 2. A reference to a WAYF service, using the method identifier wayf. There is a PAPI built-in WAYF service, that presents a simple list of the known authentication servers, and that can be selected with the keyword built-in (the URL parameter takes the form wayf:built-in). It is also possible to use other handlers with more sophisticated or user-friendly interfaces. Internal handlers (inside the same server) can be defined by means of a reference to a file that will be passed to Apache in order to complete the request. External handlers allow the use of any other URL outside the server.; Any of these handlers must implement the WAYF interface (see RedirectGPoA).
Req_DB filename: File (in Berkeley DB database format) where this PoA is going to record the parameters received for requests redirected through the GPoA. When the user browser is redirected back to the PoA by the GPoA, these data will be used to rebuild the original request. This is applicable to requests made using the POST method. The user ID the web server is running must have write access to this file.

The following tags are only applicable to points of access that implement a Groupwide-PoA (a GPoA) controlling the access to a set of PoAs:

GPoA_Priv_Key filename: The file where the private key for this GPoA is stored (using PEM format). The GPoA uses it to digitally sign the result of the validation process it has performed by request of a child PoA, and send to it this result.; This file should have very restrictive access permissions.
GPoA_Rewrite PoARegExp regExp => replacementString: This directive allows the GPoA to control the information it sends to its subordinated PoAs. When a PoA with and identifier matching PoARegExp requests user data to the GPoA, the assertion that GPoAs has received is matched against regExp, and the replacement is performed if necessary.
GPoA_Hash_User_Data [1|0]: If set to 1, user data is transformed through a hash function prior to sending it to the subordinated PoA. This way, subordinated PoAs cannot access data about users.

The following tags are only applicable to PoAs controlling the access to external resources:

Remote_URL URL

Remote Server this PoA redirect requests to.

Remote_Domain domain

Make the PoA to proxy access to an entire domain, mapping forth and back URLs of the form:

 http://proxy.poa/host/location/...

into

 http://host.remote.domain/location/...

Local_IP_Address IP

If this parameter is set, the PoA will use the local defined IP address to connect to the remote site(s).

Proxy_Server URL

If this parameter is set, the PoA will progress all requests through the proxy identified by the URL.

No_XML [1|0]


The PoA in proxy mode is able to deal with XHTML tags, but that implies
that certain sloppy practices (tolerated by browsers but out of the
standards) may cause problems in the rewriting process. Setting this
directive to 1, XML/XHTML processing is disabled.


=item Strip_Location [I<1>|I<0>]

When a PoA in proxy mode receives a request, it passes the URI unaltered to the remote server. If this directive is set to 1, the PoA will strip the value of the local Location from the URL to be requested from the remote site.

Rewrite_MIME_Types MIMEtype MIMEtype . . .

By default, a PoA in proxy mode only applies its rewriting engine to HTML/XHTML contents. It may be necessary to use the rewriting engine on some other content types (JavaScript is the most salient example). This directive allows the definition of a (blank separated) list of MIME types to which the rewriting engine (as specified by PAPI_Redirect and PAPI_Redirect_by_URL directives) will be applied on.

HTTP_Auth realm::username::password

Use the values of username and password for the security realm defined by realm using HTTP Authentication (either Basic or Digest). As many of these tags as necessary may be used, each one for different security realms at the remote resources. It is applicable to connect either to any remote server or to the proxy defined by Proxy_Server.

Form_Processor urlre=>regularExpression match=>regularExpression formIndex=>formIdx form=>formId buttonName=>name buttonIndex=>index field=>(field1, value1) field=>(field2, value2) . . .

Use the values defined by value1...valueN to fill the fields identified by field1...fieldN in the form named formId (or form of index formIdx) at the URLs matching regularExpression. Once the values are set, they are submitted to the remote server by activating the button identified by name or index. Whenever the user requests a matching URL, the PAPI proxy will fill the appropriate values and send the form data to the remote server, sending back to the user the result of this process. formId and formIdx allow for identifying one form in those pages with more than one of them, and buttonName or buttonIndex allow for using a particular button within the form to submit the data. If formId and formIdx are omitted, the first form in the page is used. If buttonName and buttonIndex are omitted, the first button in the form is used. If the optional parameter match is present, these rules will only be applied if the content of the page being processed matches regularExpression.

PAPI_Redirect regularExpression replacementString

Definition of a rule for rewriting URLs through this PoA. URLs matching the regular expression defined by the first parameter are rewritten using the replacement string defined by the second parameter.

PAPI_Redirect_by_URL URLPattern regularExpression replacementString

This is a slightly more sophisticated version of the above PAPI_Redirect. The rewriting rule is only applied for those URLs matching URLPattern.

PAPI_Request_Redirect regularExpression replacementString

Similar to PAPI_Redirect above, but the rewriting rule is applied to the URL being requested through the proxy: while the two previous directives apply to the content received from the remote server, PAPI_Request_Redirect applies to request received from the client.

PAPI_POST_Redirect regularExpression replacementString

The rewriting rule will be applied to data sent through this PoA using the HTTP POST Method.

PAPI_Header_Redirect headerPattern regularExpression replacementString

The rewriting rule will be applied to the contents of the headers sent through this PoA that match the header pattern.

When dealing with redirects bear in mind that:

1. Redirects are applied in the order they appear in the configuration file.

2. Local redirects are evaluated prior to global redirects.

3. Both the regular expression and the replacement string follow Perl conventions.

Rewrite_URL_Pattern regularExpression

By default, a PoA in proxy mode only applies its rewriting engine to HTML/XHTML contents. It may be necessary to use the rewriting engine on some other elements and sometimes it is not possible (or desirable) to do so on a content-type basis, as defined by Rewrite_MIME_Types above. This directive allows the definition of a regular expression that will be matched against the requested URL. If the expression matches, the rewriting engine (as specified by PAPI_Redirect and PAPI_Redirect_by_URL directives) will be applied on. As many of these directives as necessary can be used.

Reject_URL_Pattern regularExpression

This directive allows he definition of a regular expression that will be matched against the requested URL. If the expression matches, the requested URL will not be delivered (a 403 FORBIDDEN code will be returned instead). This directive is intended to protect partial zones of a server proxied by means of PAPI, allowing for a finer access control.

Eval_Proxy_Redirects [1|0]

If this directive is set to 1, the strings used as values in the above seven directives (HTTP_Auth, Form_Processor, PAPI_Redirect, PAPI_Request_Redirect, PAPI_Redirect_by_URL, Rewrite_URL_Pattern and Reject_URL_Pattern) are evaluated in the current Perl environment (using the Perl eval function) prior to be applied. This means that it is possible to use any internal PoA variable in any of the values of the directives.

Since the PAPI main handler fills a set of Apache notes with the attribute values contained in the access tokens (see Attribute_Separator and Value_Separator) prior to calling the proxy module, it is also possible to apply user's attributes (as stored inside the access tokens) in these directives by using the construction:

 $r->notes(PAPIAttr-<ATTRIBUTENAME>)

Proxy_Chunk_Size bytes

When accessing large contents in proxy mode it is possible to do so in chunks, passing them to the requesting browser as they become available at the proxy. This directive defines the size in bytes of these chunks. By default, it takes the value 32768 (32 KB).

Redirect_All [1|0]: By default, content redirects (as described above) only apply to URLs inside tag attributes that can be activated inside the requested document, such as URLs inside href parameters for link tags, or inside src parameters in image or script tags. If the value of this directive is set to 1, redirect regular expressions are applied to the whole text in the requested document.; Since this directive may cause severe content alterations, it should be used with extreme care.

FUNCTIONS

PAPI_Local($$$;*): This function processes all the tags found inside a <PAPI_Local> section in an Apache configuration file, updating the corresponding ApachePoA object.
PAPI_Main($$$;*): This function processes all the tags found inside a <PAPI_Main> section in an Apache configuration file, updating the corresponding ApachePoA object.

REQUIRES

SYNOPSIS

DESCRIPTION

FUNCTIONS

SEE ALSO