PAPI - Configuración de un PoA
La configuración de un PAPI PoA ha cambiado desde la versión 1.4. En dicha
versión, las directivas de configuración del PoA se definen en el fichero de
configuración de Apache como si fuesen directivas de configuración del propio
servidor web. Para que esto fuera posible, se hacia uso del módulo PAPI::Conf
el cual debía ser cargado desde el fichero de configuración de Apache mediante
la directiva PerlModule.
En la versión 1.5 de PAPI, las directivas de configuración se definen fuera del
fichero de configuración de Apache, y por tanto fuera del ámbito de dicho
servidor web. Para ello se le ha proporcionado a PAPI un fichero con sintaxis
XML, donde se definen dichas directivas.
PAPI 1.5 detecta que recursos del servidor web se desean proteger y busca en el
fichero XML las directivas que se definen para dicho recurso; procediendo a
protegerlo según se detalla en éste último.
Antes de explicar cómo configurar los PoAs de PAPI-1.5 es necesario entender como
procesa PAPI los diferentes ficheros de configuración, así como el orden en el que
se leen. Ya que esto le ofrecerá al usuario una visión más global de PAPI-1.5.
La configuración de PAPI-1.5 se dispara desde Apache en el momento que éste se
inicia, esto se consigue mediante una directiva mod_perl en la configuración de
Apache que debe estar al final del fichero de configuración de Apache para que
reconozca todos los recursos antes de lanzar la configuración de PAPI.
En el fichero de configuración de Apache, se definen los recursos a papizar, y se
les añaden una serie de directivas propias de mod_perl que le permiten a PAPI
detectarlos al procesar éste la configuración de Apache; y tratarlos de forma
especial.
Cuando se dispara la configuración de PAPI, éste parsea el fichero XML procesando
los recursos allí definidos, acto seguido PAPI recopila todos los recursos
definidos en Apache y que deben ser papizados, y los compara con los que ha
procesado en el fichero XML.
Por último si encuentra recursos que han sido definidos en Apache y cuya
configuración de PAPI no se haya declarado en el fichero XML o viceversa, es
decir, recursos no definidos en Apache pero si en el fichero XML; se muestra
un mensaje de error que avisa de posibles agujeros de seguridad, junto con un
listado de los recursos que no hayan sido definidos en ambos ficheros.
PAPI-1.5 se sirve de varios ficheros para obtener/carga la configuración.
Estos ficheros son:
- httpd.conf
Fichero de configuración de Apache.
- Apache_PoA-1.5.conf
Contiene directivas para Apache y se llama/carga desde httpd.conf
- PAPI_Apache2_conf.pl
Este fichero se llama/carga desde Apache_PoA-1.5.conf al arrancar Apache y es el que dispara el proceso de configuración de PAPI.
- papi_conf.xml
Fichero XML con las directivas PAPI y su correspondiente DTD
En el fichero de configuración de Apache httpd.conf se debe indicar los
recursos que se desean proteger con PAPI, para ello se deben añadir las
siguientes directivas mod_perl en las secciones Location, Directory y Files
que se desean papizar.
El fichero Apache_PoA-1.5.conf debe incluirse desde el fichero de configuración de Apache,
o copiar su contenido a éste fichero.
Si desea incluirlo (es lo recomendado) puede seguir el siguiente ejemplo
#
## Fichero de configuración para papi.
#
Include /usr/local/apache/conf/PAPIConf/PoA/Apache_PoA-1.5.conf
De donde se deduce que el fichero se ha copiado al directorio
/usr/local/apache/conf/PAPIConf/PoA/.
En este fichero (Apache_PoA-1.5.conf) es donde se configura el proceso de configuración de PAPI,
por medio de variables de entorno de mod_perl.
- PoA_CONFIG_FILE
Esta variable define la localización del fichero XML de configuración de PAPI.
Recibe una cadena que representa la ruta donde está ubicado el fichero
anteriormente citado. Dicha variable se define como se muestra a continuación.
PerlSetEnv PoA_CONFIG_FILE /usr/local/apache/conf/PAPIConf/PoA/papi_conf.xml
Es importante, que junto al fichero papi_conf.xml se encuentre el fichero DTD
que contiene la declaración de tipo para dicho fichero XML. Ya que este último
espera encontrar su correspondiente DTD en el directorio en el que se encuentre.
Aunque esto puede modificarse en la declaración del DTD interna del fichero XML.
Como se muestra a continuación.
<!DOCTYPE PAPI_Configuration SYSTEM "file://new/path/for/DTD/papi_conf.dtd">
- CONFIG_VERBOSE
Esta variable determina si el proceso de configuración se realiza en modo
``verboso'' o no, de forma que si la variable es true, la configuración de
PAPI 1.5 será volcada a la salida estándar, y en el caso de que su valor sea
false, no se volcará nada por la salida estándar. El propósito de esta
variable es más ayudar a la depuración que a los usuarios de PAPI 1.5. Por lo
que se ha hecho opcional la aparición de la misma.
En el siguiente ejemplo, la variable está comentada, por lo que la configuración
no será volcada por la salida estándar.
#PerlSetEnv CONFIG_VERBOSE true
- XML_CHECKER_ACTIVE
- CONFIG_DEVELOP
El fichero apache_PoA-1.5.conf además de la variables descritas
anteriormente, tiene dos secciones <Perl></Perl>
. En la
primera de ellas se define una variable y se requiere el script que dispara la
configuración del PAPI PoA, tal como se muestra a continuación:
<Perl>
$Apache2::PerlSections::Save = 1;
require "PAPI/PAPI_Apache2_conf.pl";
</Perl>
La variable $Apache2::PerlSections::Save
se usa para salvar toda la
configuración de Apache que se realiza dentro de una PerlSection, con el fin
de mostrarla posteriormente por pantalla, o guardarla en un fichero. Esto
es útil para depurar el proceso ``dinámico'' de configuración de Apache. El
fichero PAPI/PAPI_Apache2_conf.pl es el script que dispara la configuración
de PAPI, y que se instala junto con los módulos de Perl, por lo que se
recomienda que no se modifique a menos que se desee modificar el proceso de
configuración de PAPI y se haya definido otro fichero.
La segunda PerlSection tiene la finalidad de imprimir por salida estándar la
configuración generada o modificada de apache durante el proceso de
configuración de PAPI; siempre y cuando la variable
$Apache2::PerlSections::Save
se haya establecido a 1
.
<Perl>
print Apache2::PerlSections->dump;
</Perl>
Como ya se ha comentado anteriormente, PAPI 1.5 se configura mediante un fichero
XML. Se ha intentado mantener los nombres de las directivas de PAPI 1.4 para los
tags del fichero XML, de forma que para aquellos que ya hayan trabajado con
PAPI, no les resultará muy costoso adaptarse a nuevo método de configuración.
El fichero XML mantiene el mismo criterio de configuración que la versión
1.4 de PAPI, donde se usaba en el fichero httpd.conf de Apache. Es decir,
sigue existiendo una sección donde se definen los valores por defecto y/o
comunes para PAPI
<Global>
<Accept_File>/home/user/src/InstalledPAPIs/PAPI-1.5/PoA/blueball.gif</Accept_File>
<Reject_File>/home/user/src/InstalledPAPIs/PAPI-1.5/PoA/redball.gif</Reject_File>
<Debug>0</Debug>
<HKey>YWNhOWZkNzE4MDRhFDRKJKJffg54DfkxNzgwMzNmOTU=</HKey>
<LKey>ZjYwNTk2DFrdfTYHNjhkMmZlZjM0NDMwMDlhNWYyMWU=</LKey>
<Pubkeys_Path>/home/user/src/InstalledPAPIs/PAPI-1.5/PoA</Pubkeys_Path>
<Hcook_DB>/home/user/src/InstalledPAPIs/PAPI-1.5/PoA/hcookdb</Hcook_DB>
<Lcook_Timeout>18000</Lcook_Timeout> <CRC_Timeout>1800</CRC_Timeout>
<URL_Timeout>1800</URL_Timeout>
<Req_DB>/home/user/src/InstalledPAPIs/PAPI-1.5/PoA/req_db.mldbm</Req_DB>
<PAPI_AS id="PAPI-1.33" url="http://squirtle.rediris.es/cgi-bin/AuthServer">PAPIusando Apache-1.5</PAPI_AS>
<Location path="/test" id="test0" filtered="false" independent="false">
<PAPI_Filter regex="default" action="reject"></PAPI_Filter>
<Form_Processor url="http://loc.al.domain/testForm" form_id="Form ID0">
<Field name="username">theUser_0</Field>
<Field name="password">thePassword_0</Field>
</Form_Processor>
</Location>
</Global>
Y también se definen secciones de tipo Server, Location, Directory y File. Que se
corresponden con las secciones de Apache VirtualHots, Location, Directory y File
respectivamente.
Las secciones Location, Directory y File que definen recursos en Apache del Main Host,
es decir, que no pertenezcan a ningún VirtualHost; se deben definir en el fichero XML de PAPI
en la sección Global, tal y como se puede observar en el ejemplo anterior, donde la sección de
tipo Location ha sido incluida en la sección Global
Todos aquellos recursos de Apache que se definan en el ámbito de algún VirtualHost, deben
ubicarse dentro de una sección de tipo Server en el fichero XML de PAPI.
Como se muestra a continuación:
<Server name="server.local.domain" port="80" independent="0">
<Location path="/prueba" id="test2" filtered="true" independent="false">
<GPoA_URL>wayf:built-in</GPoA_URL>
</Location>
</Server>
- papi_conf.xml
Suponemos que el recurso /papi/local está definido en el Main Host de Apache; por tanto
la sección Location debe incluirse dentro del Global del fichero XML
<Global>
...
<Location path="/papi/local" id="papiLocal" filtered="true" independent="false">
# This directive makes the PoA reject all requests coming from any
# user that the corresponding AuthServer identifies as "default"
<PAPI_Filter regex="default" action="reject"></PAPI_Filter>
</Location>
...
</Global>
- httpd.conf
Esta sección debe estar definida en Apache y con las directivas mod_perl que han indicado
con anterioridad en este documento.
<Location /papi/local>
# Otras directivas de Apache
PerlSetVar Service_ID poa20
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</location>
- papi_conf.xml
<Server name="remote.papi.dom.ain" port="80" independent="0">
<Location path="/" id="remote" filtered="true" independent="false">
<Remote_URL>http://remote.dom.ain </Remote_URL>
# 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 src_regex="http://remote2.dom.ain" dst="http://remote.papi.dom.ain"></PAPI_Redirect>
</Location>
</Server>
- httpd.conf
<VirtualHost 1.2.3.4>
ServerName remote.papi.dom.ain
<Location />
PerlSetVar Service_ID remote
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
</VirtualHost>
- papi_conf.xml
<Server name="remote.papi.dom.ain" port="80" independent="0">
<Location path="/" id="remoteprot" filtered="true" independent="false">
<Remote_URL>http://remote.dom.ain</Remote_URL>
<HTTP_Auth realm="formID" user="usuario" password="pass" />
</Location>
</Server>
- httpd.conf
<VirtualHost 1.2.3.4>
ServerName remote.papi.dom.ain
<Location />
PerlSetVar Service_ID remoteprot
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
</VirtualHost>
- papi_conf.xml
<Server name="remote.papi.dom.ain" port="80" independent="0">
<Location path="/" id="remoteprot" filtered="true" independent="false">
<Remote_URL>http://remote.dom.ain</Remote_URL>
<Form_Processor url="http://remote.dom.ain/authenForm" form_id="Form ID0">
<Field name="username">theUser</Field>
<Field name="password">thePassword</Field>
</Form_Processor>
</Location>
</Server>
- httpd.conf
<VirtualHost 1.2.3.4>
ServerName remote.papi.dom.ain
<Location />
PerlSetVar Service_ID remoteprot
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
</VirtualHost>
- papi_conf.xml
<Server name="remote.papi.dom.ain" port="80" independent="0">
<Location path="/" id="remoteprot" filtered="true" independent="false">
<Remote_Domain>dom.ain</Remote_Domain>
</Location>
</Server>
- httpd.conf
<VirtualHost 1.2.3.4>
ServerName remotedom.papi.dom.ain
<Location />
PerlSetVar Service_ID remoteprot
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
</VirtualHost>
- papi_conf.xml
<Global>
...
<Location path="/" id="localchild" filtered="true" independent="false">
# This directive defines a database for storing parameters for
# requests made using the POST method
<Req_DB>/usr/local/PAPI/PoA/localChildReqs.db</Req_DB>
<GPoA_URL>http://gpoa.dom.ain/GPoA/PAPI/cookie_handler.cgi </GPoA_URL>
</Location>
...
</Global>
- httpd.conf
<Location /papi/local>
PerlSetVar Service_ID remoteprot
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
- papi_conf.xml
<Global>
...
<Location path="/GPoA" id="parent" filtered="true" independent="false">
<GPoA_Priv_Key>/usr/local/PAPI/PoA/gpoaKey.pem</GPoA_Priv_Key>
</Location>
...
</Global>
- httpd.conf
<Location /GPoA>
PerlSetVar Service_ID parent
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
- papi_conf.xml
<Global>
...
<Location path="/GPoA" id="wayfenabled" filtered="true" independent="false">
<Req_DB>/usr/local/PAPI/PoA/WayfReqs.db</Req_DB>
# The GPoA is implemented by a WAYF service (locates the appropriate AS)
<GPoA_URL>wayf:built-in</GPoA_URL>
</Location>
...
</Global>
- httpd.conf
<Location /papi/local>
PerlSetVar Service_ID wayfenabled
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
No portado aún
- papi_conf.xml
<Global>
...
<Location path="/GPoA" id="spocp-based" filtered="true" independent="false">
<!-- Ask SPOCP server in spocp.localdomain using action "access" -->
<SPOCP_Server>spocp.localdomain:3456</SPOCP_Server>
<SPOCP_Action>access</SPOCP_Action>
</Location>
...
</Global>
- httpd.conf
<Location /spocpPoA>
PerlSetVar Service_ID spocp-based
PerlOptions +ParseHeaders
SetHandler perl-script
PerlAccessHandler PAPI::Main
</Location>
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:
- <Global> this directive replaces <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>)
- <Server name=``fqdn'' port=``80'' independent=false``>
For directives aplicable to a VirtualServer. This section can not apear inside
a <Global> section. This section contain <Location>, <Directory> and <File>
sections.
Its attribute list are:
- name FQDN
Set the fully qualified domain namne of the virtuar server.
- port
The port where the virtual server is listening.
- independent < true | false >
This attribute will be removed soom. So we recomend set it to false.
- <Location path='/' id='Service_ID' filtered='' independet=''>
- <Directory path='/' id='Service_ID' filtered='' independet=''>
- <Files path='/' id='Service_ID' filtered='' independet=''>
Those directive replace <PAPI_Local>
For options applicable to a particular PoA. This section corresponds with <Location>
<Directory> and <Files> section defined at Apache configuration file.
- path path
The same path defined at <Location> of Apache
- 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.
- filtered
- independet
The tags recognized by the configuration methods inside <Global>, <Location>,
Directory>, and <Files> and <PAPI_Local> sections are as follows:
- <HKey> filename </HKey>
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]).
- <LKey> filename </LKey>
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]).
- <Hcook_DB>filename</Hcook_DB>
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</Accept_File>
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</Reject_File>
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</Pubkeys_Path>
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</Auth_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.
- Pass_URL_Pattern ??????????
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<Hcook_Handler>
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</Lcook_Timeout>
Period of time during which Lcook tokens are valid.
- <CRC_Timeout>seconds</CRC_Timeout>
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</URL_Timeout>
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</Max_TTL>
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 id='' url='' jnlp_codebase=''>AS Description</PAPI_AS>
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).
The jnlp_codebase... I don't know
- <PAPI_Filter regex='regularExpression' action='[ 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 <Location | Directory | Files> sections, and then global filters
defined inside the <Global> section. For back compatibility, a catch-all
implicit filter equivalent to:
<PAPI_Filter regex='.*' action='accept'/>
- <Cookie_Reject>regularExpression</Cookie_Reject>
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 ]</Hash_User_Data>
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.
Nevertheless, is important to note that this feature may have undesirable
interactions with some other ones, like the use of Hcook_Handler.
- <User_Data_Rewrite src_regex='regularExpression' dst='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 ] </Client_Address_In_Tokens>
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</Attribute_Separator>
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</Value_Separator>
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 ]</Debug>
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</SPOCP_Server>
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</SPOCP_Action>
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 ]</SPOCP_Accept_If_Down>
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</GPoA_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.
- <Req_DB>filename</Req_DB>
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</GPoA_Priv_Key>
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.
- <GPoA_Rewrite PoA_regex='PoARegExp' src_regex='regExp' dst='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 ]</GPoA_Hash_User_Data>
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. It is important to note that this feature may have
undesirable interactions with some other ones, like the use of Hcook_Handler.
The following tags are only applicable to PoAs controlling the access
to external resources:
- <Remote_URL>URL</Remote_URL>
Remote Server this PoA redirect requests to.
- <Remote_Domain>domain</Remote_Domain>
Make the PoA to proxy access to an entire domain, mapping forth and back URLs
of the form:
http://proxy.poa/host/location/...
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</Proxy_Server>
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> ]</Strip_Location>
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 ...</Rewrite_MIME_Types>
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 directives) will be
applied on.
- <HTTP_Auth realm='' user='' 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 url='regularExpression' form_id='formId' buttonName='name' buttonIndex='index'> <field name='field1'>value1</field> . . .</Form_Processor>
Use the values defined by value1...valueN to fill the fields identified
by field1...fieldN in the form named formId 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 allows for identifying one
form in those pages with more than one form, and buttonName or
buttonIndex allow for using a particular button within the form to submit
the data. If formId is omitted, the first form in the page is used. If
buttonName and buttonIndex are omitted, the first button in the form
is used.
- <PAPI_Redirect src_regex='regularExpression' dst='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_POST_Redirect regularExpression replacementString ????????????
The rewriting rule will be applied to data sent through this PoA using
the HTTP POST Method.
- <Rewrite_URL_Pattern>regularExpression</Rewrite_URL_Pattern>
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 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 five
directives (HTTP_Auth, Form_Processor, PAPI_Redirect,
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, 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.
Rodrigo Castro (RedIRIS) - Spain.
Diego R. Lopez (RedIRIS) - Spain.
Daniel García (RedIRIS) - Spain.