view release on metacpan or  search on metacpan

Headers.pm  view on Meta::CPAN

				push @ALLOWED_REFERERS, $r ;
			}
		}

		# store the allowed headers for each path $p
		foreach my $p ( @{ $h->{'path'} } )
		{
			push @{ $PATH_TO_HEADERS{ $p } }, $h->{'id'}[0] ;
		}
	}

	# create a global array of paths/regexes for efficiency
	# ( so this doesn't have to be done each time through the handler )
	@PATH_REGEXES = sort keys %PATH_TO_HEADERS ;
	
	# set header prefix if needed
	if ( $ref->{'header_authz'}[0]{'headers'}[0]{'prefix'} )
	{
		$HEADER_PREFIX = $ref->{'header_authz'}[0]{'headers'}[0]{'prefix'}[0] ;
	}

	return &OK ;
}

1;

__END__
=pod 

=head1 NAME

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

=head1 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>

=head1 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.

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

=head1 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 

=head1 CONFIGURATION FILE

=head2 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 B<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-ID</id> 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.

=head2 Other Options

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

=over 3