view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      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
       resources matched by the attached <path> tags. This is useful for
       allowing access to <path>/</path> and <path>index.html</path>, etc.

    REFERER
       If the <id> of a <header> block is 'REFERER', then the referer header
       is checked against an array of referer values specified by <referer>
       tags in the <header> block.

       For example, using the sample conf file, requests for
       /images/background.gif coming from a page on http://www.rulez.com/,
       or http://www.picnicman.com/ will be accepted.

       <referer> tags are treated as regexes ( like <path> tags ). The regex
       used is 'm|^$ar|' where $ar is the contents of the <referer> tags.

       One little trick is to use 'https?://' at the start of the regex to
       allow connections from either secure or insecure pages.

       Note: If the referer is not matched, FORBIDDEN will not be
       automatically returned. In this case, the module continues to loop
       over <path> values, looking for a secondary match.

       i.e. if a request for /images/button.gif does not come from a valid
       referer, but contains a X-Can-View-Secret-Stuff header, the image
       will be served.

       This behavior is open to debate. Admittedly, it's a hack meant to
       overcome some problems with the original spec. If you don't like it,
       then don't use REFERER as an <id>. :)

    <prefix></prefix>
       You'll notice a commented-out <prefix> tag in the sample conf file.
       The prefix tag was added because some - *cough* - authenticating
       proxies prepend a string to header values defined in the
       authtencation database.

       If the <prefix> tag is set, then all header checks will look for
       $PREFIX . $HEADER.

       For example, if <prefix> is set to 'Rulez-', requests for
       /secret/index.html would require not a X-Can-View-Secret-Stuff
       header, but a Rulez-X-Can-View-Secret-Stuff header.

  Sample Configuration File

     <header_access>
      <headers>
       <!-- <prefix>Rulez-</prefix> -->
       <header>
        <id>ALL</id>
        <path>/</path>
        <path>/index.html</path>
       </header>
       <header>
        <id>REFERER</id>
        <referer>https?://www.rulez.com/</referer>
        <referer>https?://ww.picnicman.com/</referer>
        <path>/images/.*</path>
        <path>/cgi/*.cgi</path>
       </header>
       <header>
        <id>X-Can-View-Secret-Stuff</id>
        <path>/secret/.*</path>
        <path>/secrets.html</path>
        <path>/images/.*</path>
       </header>
       <header>
        <id>X-Can-View-Super-Secret-Stuff</id>
        <path>/super-secret/.*</path>
        <path>/secrets.html</path>