PAPI::AuthServer - A highly configurable PAPI Authentication Server based on HTML forms

DESCRIPTION

This is a highly configurable HTML-form based PAPI Authentication Server designed to run as a CGI, although it can also be run inside Apache's mod_perl.

Configuration is performed through a configuration file, a Perl source file that essentially contains assignments to a hash named PAPI::AuthServer::cfgVar. The name of the configuration file is built by appending the string .cf to the value of the Perl $0 special variable (the name of the file the program lives in). This way, if the AuthServer is inside a file named /usr/local/PAPI/AS/AuthServer, its configuration file will be /usr/local/PAPI/AS/AuthServer.cf.

Data corresponding to the current connection, either received from the user (inside the authentication form) or dynamically generated inside the AuthServer is stored in another hash named PAPI::AuthServer::conVar.

The Authentication Server may be called with four different operation codes:

LOGIN: Is the operation by default. Directs the server to perform user authentication and redirect PAPI requests to the appropriate PoAs.
ATTREQ: Corresponds to a request for user attributes coming from a PoA. Directs the server to validate the request, authenticate the user if not already authenticated, and send the results back to the requesting PoA.
TEST: Directs the server to verify current access rights with the appropriate PoAs.
LOGOUT: Directs the server to request access right cancellations from the appropriate PoAs.

The operation code is selected by setting a form variable with the operation name (case is significant) to any non-null value.

The Authentication server uses the value of the following variables. These variables are passed as the AuthServer performs its tasks, and are used to determine its behavior:

PAPIrefURL: Is the original URL the user was trying to access when it was redirected to the AuthServer for a LOGIN request. This variable can be used for automatically redirecting the user to the resource (s)he originally intended to access upon successful authentication.
PAPIPOAREF: Is the reference for the original user's request at the PoA querying the AuthServer in an ATTREQ operation. This value is returned to the PoA once the answer to the ATTREQ is built, so the PoA can continue the processing of the request that caused the ATTREQ query.
PAPIPOAURL: Is the URL that fired the ATTREQ query from the PoA to the AuthServer. This value is used by the AuthServer to:; 1. Determine the data to be sent back to the requesting PoA, by means of the assertion formats defined for the user and the requesting site.; 2. Establish the URL to which the assertion will be sent by means of a HTTP redirect.; 3. Send it back to the requesting PoA along with the assertion, so the PoA can continue the processing of the request that caused the ATTREQ query.

CONFIGURATION VARIABLES

Bootstrapping Variables

Since they are used for defining the location of other configuration elements, these variables must be the first to be defined. The current version only employs one of these variables:

workingDirectory: The path where files related to the Authentication Server live.

HTML Templates

Define the format of pages used for interacting with the user. Inside this templates, the constructs <papi var=``VarName''/> are substituted by the value of the variable identified by 'VarName' inside the Authentication Server, whether coming from connection or configuration data. For example, assume that rejectTemplate has the following contents:

 <P>Your request has been rejected by the authentication server</P>
 <P><B>User:</B> <papi var="username"/></P>
 <P><B>Reason:</B> "<papi var="PAPIerror"/>"</P>

If an authentication request for the user ``papiUser'' (as defined by the connection variable username) fails and the authentication function sets PAPIerror to ``Unknown user'', the page returned to the user's browser would have the following contents:

 <P>Your request has been rejected by the authentication server</P>
 <P><B>User:</B> papiUser</P>
 <P><B>Reason:</B> "Unknown user"</P>

The AS also honors the Shell and Perl backtick convention. Any string enclosed between backuotes (the character `) will be substituted by the result of executing the corresponding command in the system. This way, a template containing:

 `date`

Will have it substituted by the current date and time.

loginTemplate: Sent to users when they first contact the Authentication Server.
acceptTemplate: Sent to users when authentication is accepted for login to the server.
testTemplate: Sent to users when authentication is accepted for testing credential status.
logoutTemplate: Sent to users when authentication is accepted for removing credentials.
rejectTemplate: Sent to users when authentication is rejected,
siteInfoTemplate: Used to build the information sent to the user about each of the sites (s)he is authorized to.

Authentication cookie

The ability to answer to ATTREQ queries coming from different PoAs without re-authenticating the user requires the use of a HTTP cookie to store data about the user. This cookie is named PAPIAuthNcook and is a session cookie that is set at the user's browser and re-coded each time an ATTREQ query is answered to difficult unauthorized access by cookie copying. If a LOGOUT operation is requested, the cookie is invalidated.

The format of the authentication cookie is:

 varList::nonce::TTL::clientAddress

Where:

varList

Is a list of connection variables, established at the moment of the user's authentication. It is built as follows:

 variable1Name:variable1Value::variable2Name:variable2Value:: . . .

nonce

Is a nonce, generated each time that the cookie has to be coded or re-coded. The value of the nonce is stored in the cookie database (defined by the configuration variable authCookieDB), so only an instance of the authentication cookie is valid at a given moment for a given user.

TTL

Is the time at which the cookie will become invalid (in seconds since the 1st January 1970).

clientAddress

The IP address of the client this cookie was generated for. A cookie coming from a client not matching its clientAddress is considered invalid.

The contents of the cookie are encrypted using the symmetric key of the AuthServer (see below).

The configuration variables involved with the management of authentication cookies are:

authCookie: Defines a (comma separated) list of connection variables to be included into authentication cookies.
authCookieDB: Defines the location of the file where the AuthServer will store the valid nonces for authentication cookies. Since this file (and locks related to it) has to be written by the UID the Apache server is running with, you need to grant this UID with write permissions in the directory the file is defined.
authCookieTimeToLive: Defines the duration (in seconds) of authentication cookies.

Split mode operation

This PAPI Authentication Server is able to accept authentication data through TLS. This means that the URL for the AS can be a TLS-based one (i.e., one that uses the https method). To do so while returning different authorization tokens from the PoAs by means of cookies, split mode has to be used.

In split mode, the AS automatically redirects itself to another (usually the non-TLS counterpart of the original) URL when it receives user authentication data through the TLS secure channel. The redirection passes data about the user encrypted using the server symmetric key and can only be performed for a short period of time.

splitModeURL: The URL to redirect the user's browser once authentication data has been accepted. If this variable is set, split mode is applied. Otherwise, normal mode (non TLS-capable) is used.
splitModeParamList: A (comma separated) list of parameters to be passed to the second phase URL, encrypted using this AS private key. This way, it is possible to pass to the second phase procedures any form data provided by the user and required by them. The connection variables PAPIop and PAPIrefURL (if set) are always passed.
splitModeTimeout: The time in seconds for which the redirect will be accepted by the AS. This timeout is intended to avoid the malicious replay of split mode URLs. By default, is set to 5 seconds.

Values for Authentication and Requests

These values are used for building the requests and the authentication tokens to be sent to PAPI Points of Access (PoAs).

acceptURL

The URL where the PoA must redirect the user's browser for loading an object when a request from the Authentication Server is accepted (if no other is specified by the PoA definition, see LDAPAuth and credentialHook below). This value is encoded as a parameter called AURL in each request made by the AS. If this parameter is not included in the request, the PoA will use its own accept URL.

Inside this URL, any backtick calls are substituted by the result of executing the corresponding system command, and the constructs <papi var=``VarName''/> are substituted by the value of the variable identified by 'VarName' inside the Authentication Server, whether coming from connection or configuration data.

rejectURL

The URL where the PoA must redirect the user's browser for loading an object when a request from the Authentication Server is rejected (if no other is specified by the PoA definition, see LDAPAuth and credentialHook below). This value is encoded as a parameter called RURL in each request made by the AS. If this parameter is not included in the request, the PoA will use its own reject URL.

symKey

The symmetric key this Authentication Server uses to encrypt those data to be reused between different requests of the user's browser, like connection data in split mode and authentication cookies.

uidVar

Identifies the name of the connection variable where the Authentication Server is going to look for a user identifier when operations that do not request complete user identification (TEST and LOGOUT) are performed. If not set, the default value nologin will be asumed as the user identification for these operations.

privateKey

The private key this Authentication Server uses to sign requests,

serverID

The identifier for this Authentication Server, as sent to the PoAs.

defTimeToLive

The default time to live to be requested for user's tokens.

defPoA

The default PoA to be used.

defService

The default service that will be requested to PoAs. Bear in mind that sites with a blank service identifier are not included in the list of sites directly contacted upon successful authentication to get the authorization tokens.

defLocation

The default location that will be requested to PoAs.

defDescription

The default description to be used for sites.

defAuthURI

The default authorization URI at PoAs (relative to the PoA location).

defAccessURI

The default URI to be used when accessing PoA-protected content from the page sent upon successful authentication (relative to the PoA location).

defAssertion

The format of the assertion about the user to be sent to the PoAs, if no other is defined by means of specific site definitions. Inside this string, the constructs <papi var=``VarName''/> are substituted by the value of the variable identified by 'VarName' inside the Authentication Server, whether coming from connection or configuration data. Furthermore, backtick expansion for system commands is also supported. If not set (and no other format has been obtained for a PoA), the assertion sent is equivalent to:

 <papi var="PAPIuid"/>-<papi var="PAPIgid"/>

Hooks

These are function references used to provide hooks for performing user authentication, credential data and logging. The keys for these references are as follows.

authenticationHook: The function referenced by this hook receives two references, one to the connection data hash and the other to the configuration hash. It must return an identifier of the user that will be used for building any assertion to be sent to the PoAs, or 'undef' if the authentication fails. In this case, the function may set the element PAPIerror into the connection data hash, so this information can be logged and/or forwarded to the user.
credentialHook: The function referenced by this hook receives the references to the same two hashes. It must return a list, where each item is a hash describing the authorized sites for the user. The hash describing a authorized site must contain the following elements:; ttl: Time to live for the authorization; service: Service to be requested to the PoA. If the service ID is blank, this site will not be included in the list of sites directly contacted upon successful authentication to get the authorization tokens.; location: Location to be requested to the PoA; poa: Point of Access to be used; desc: Description of the site; authURI: Authorization URI at the PoA; accessURI: Access URI at the PoA; AURL: URL to be used for signaling acceptance of the request by the PoA; RURL: URL to be used for signaling rejection of the request by the PoA; assertion: Format of the assertion to be sent to the PoA; If any of these keys is not used, default values will apply. Any other values (to be used when processing the template defined by siteInfoTemplate) can be included.; If this procedure fails, the function may set the element PAPIerror into the connection data hash, so this information can be logged and/or forwarded to the user.
attrRequestHook: The function referenced by this hook receives the same couple of hash references. It is in charge of finding a suitable PoA definition in the Authentication Server and to build the appropriate assertion to be sent back in response to an ATTREQ query to the requesting PoA.; Typically, it should use the PAPIPOAURL connection variable to determine the appropriate PoA definition, and the variables stored into PAPIAuthNcook to establish user identity, and compose the appropriate assertion.; It must return an array with two elements:; TimeToLive: The first element in the array must contain the time to live assigned for the PoA definition found by the function.; Assertion: The actual contents of the assertion to be sent back to the requesting PoA, once attributes and internal variables have been substituted into the appropriate assertion format.; If no suitable PoA definition is found, or user data contained in PAPIAuthNcook is insufficient to establish the assertion format, the function must return TimeToLive set to zero, and may set the element PAPIerror into the connection data hash, so this information can be logged and/or forwarded to the user.
logHook: The function referenced by this hook receives a log string and the same two hash references as the functions above. The predefined values ``accept'' and ``reject'' for the log string imply an specific processing. Any other value is logged together with the client name/address and the value of PAPIuid. It is intended to log the data of the request and its outcome.

Other Elements

Any other elements can be included into the configuration hash, either for using them inside the templates or for passing their values to the functions referenced by any of the hooks.

CONNECTION VARIABLES

All the variables in the forms defined by the HTML templates are available using its name as key through the connection hash. Obviously, functions referenced by hooks may use this hash to pass values among them.

The following connection variable keys are set by the Authentication Server and passed through the hooks into the connection hash, so they MUST be considered reserved:

PAPIIkey: In split mode, is used to pass the required data to the URL in charge of performing the second phase of the authentication procedures
PAPIPOAREF: When processing an ATTREQ operation, it is set to an internal reference used by the PoA issuing the query. This reference points to the original user request that initiated the operation at the PoA. It is returned to the PoA when completing the response to ATTREQ, so it can continue servicing the user's request.
PAPIPOAURL: When processing an ATTREQ operation, it is set to the URL (at the PoA) where the user's browser must be redirected to process the response of the AuthServer.
PAPIerror: Is the last error detected by the Authentication Server or any of the functions referenced by the hooks.
PAPIgid: Is an optional group identifier, typically set by the function referenced by authenticationHook
PAPIhash: Is a hash of the current value of PAPIuid, intended to be used (if required) in building the assertions to be sent to PoAs.
PAPInonce: Is a nonce for the current operation and the current user, intended to be used (if required) in building the assertions to be sent to PoAs.
PAPIop: Is set to the requested operation: LOGIN, TEST, ATTREQ or LOGOUT.
PAPIrefURL: Is set to the value of the referring URL, that is, the URL of the resource the user was trying to access when redirected to the AuthServer. It is passed through the different phases of execution and can be used to redirect the user back to the original resource.
PAPIsiteList: Refers to the site information built from siteInfoTemplate and data returned from the function referenced by credentialHook.
PAPIuid: Is set to the value returned from the function referenced by authenticationHook.
host: Contains the IP address of the user's browser.
LOGIN, ATTREQ, TEST, LOGOUT: One of these variables (and just one of them) set to any non-null value, means that the AuthServer is being called to perform the corresponding operation.