view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Apache::Access::Headers - mod_perl HTTP header authorization module

SYNOPSIS
     # in httpd.conf
     PerlSetVar HeadersAccessConf conf/headers_access.conf
        
     DocumentRoot /usr/local/apache/htdocs
     <Directory "/usr/local/apache/htdocs">
        PerlModule Apache::Access::Headers
        PerlAccessHandler Apache::Access::Headers
     </Directory>

DESCRIPTION
    This module is intended to be used as a mod_perl PerlAccessHandler. It's
    function is to authorize requests for server resources based on the
    existence of and content of HTTP headers.

    Authorizing HTTP headers may be be set by a web browser, a software
    agent, or an authenitcating proxy server. This module was originally
    written to work with the latter.

    Note: The default reponse from the handler is currently FORBIDDEN. This
    behavior is not yet configurable.

CONFIGURING APACHE
    Module configuration is simple ( read: limited ). Currently, the module
    only works with a single configuration file, and works best when
    configured for a server's document root. See the LIMITATIONS section for
    an explanation of the modules current short-comings.

    Add the following line to httpd.conf outside all Directory, Location and
    VirtualHost blocks:

     PerlSetVar HeadersAccessConf /path/to/conf/headers_access.conf
 
    And add the following lines to the DocumentRoot Directory block:

      PerlModule Apache::Access::Headers
      PerlAccessHandler Apache::Access::Headers 

CONFIGURATION FILE
  General Options

    Although the modules is currently limited to a single xml-based
    configuration file, this configuration file is quite flexible.

    The shell of the conf file is:

     <headers_authz>
      <headers>
      [...]
      </headers>
     </headers_authz>  

    The important part of the conf file is the <header> blocks within the
    <headers> block. Each <header> block must contain two items: an <id> tag
    and a <path> tag.

    The <id> tag specifies the name of the HTTP header that that must be set
    to allow access to the urls matched by the <path> tags. <path> tags are
    treated as regular expressions ( i.e., m|^$k$| where $k is the value of
    the <path> tag ).

    Using the Sample Configuration File below, a request for
    /secrets/index.html must contain an X-Can-View-Secret-Stuff header with
    a non-zero value in order to be successfully authorized.

    Likewise, a request for /secrets.html requires that either an
    X-Can-View-Secret-Stuff header or an X-Can-View-Super-Secret-Stuff
    header is present and set to a non-zero value.

    As mentioned above, <path> tags are treated as regular expressions.
    You'll notice, then, that the <path> tag for <id>X-Secret-User-I1 in the
    sample conf contains parantheses. Parentheses tells the module to
    require that the value assigned to the needed header ( i.e.
    X-Secret-User-ID ) equal $1.

    For example, using the sample conf, a request for /users/jeffo/ must
    have an X-Secret-User-ID header set to 'jeffo'. If X-Secret-User-ID
    header is present but set to 'tori', the request will be denied.

  Other Options

    There are three special configuration options. They are outlined here:

    ALL
       If the <id> of a <header> block is 'ALL', then _all_ requests for