view release on metacpan or  search on metacpan

lib/Apache/AppSamurai.pm  view on Meta::CPAN

=head2 TRACKER BASED FEATURES

The following features require the tracker system to be configured.
These are pretty basic and static at this point.  (Should probably
be split out into modules.)

=head3 I<IPFailures> C<COUNT:SECONDS>

(Defualt: undef)
Block further login attempts from IPs that send C<COUNT> failures with
no more than C<SECONDS> seconds between each subsequent failure.  Once
blocked, the block will remain in effect till at least C<SECONDS> has
elapsed since the last connection attempt.

=head3 I<AuthUnique> C<0|1>

(Default: 0)
If set to 1, forces at least one credential to be unique per-login.
(Requires dynamic token or other non-static authentication type.)

=head3 I<SessionUnique> C<0|1>

(Default: 0)
If 1, prohibits a new session from using the same session ID as a previous
session.  This is generally only relevant for non-random sessions that use the
C<Keysource> directive to calculate a pseudo-cookie value.

=head1 METHODS

The following methods are to be used directly by Apache.  (This is not
a full list of all Apache::AppSamurai methods.)

=head3 authenticate()

Should be configured in the Apache config as the PerlAuthenHandler for
areas protected by Apache::AppSamurai.

C<authenticate()> is called by object reference and expects an Apache request
object as input.C<authenticate()> uses a session authentication key, either
from a cookie or from the optional C<Keysource>, and tries to open the session
tied to the session authentication key.

If the session exists and is valid, the username is extracted from the session
and the method returns C<OK> to allow the request through.

If no key is present, if the session is not present, or if the session
is invalid, a login request is returned.  (Either a redirect to a login form,
or in the case of an area set to basic authentication, a
C<401 Authorization Required> code.)

=head3 authorize()

Should be configured in the Apache config as the PerlAuthzHandler for
areas protected by Apache::AppSamurai.

C<authorize()> is called by object reference and expects an Apache request
object as input.  It then checks the authorization requirements for the
requested location.  In most cases, "require valid-user" is used in conjunction
with the "Satisfy All" Apache::AppSamurai setting.  This authorizes any logged
in user to pass.  This method could be replaced or expanded at a later date if
more granular authorization is required.  (Groups, roles, etc.)

C<OK> is returned if conditions are satisfied, otherwise C<HTTP_FORBIDDEN> is
returned.

=head3 login()

Should be configured in the Apache config as the PerlHandler, (or
"PerlResponseHandler" for mod_perl 2.x), for a special pseudo file under
the F<AppSamurai/> directory.  In example configs and
the example F<login.pl> form page, the pseudo file is named B<LOGIN>.

C<login()> expects an Apache request with a list of credentials included as
arguments.  B<credential_0> is the username.  All further credentials are
mapped in order to the authentication modules defined in L</AuthMethods>.
Each configured authentication method is checked, in order.  If all
succeed, a session is created and a session authentication cookie is returned
along with a redirect to the page requested by the web browser.

If login fails, the browser is redirected to the login form.

=head3 logout()

Should be called directly by your logout page or logout pseudo file.
This expects an Apache request handle.  It can also take a second
option, which should be a scalar URI path to redirect users to after
logout.  C<logout()> attempts to look up and destroy the session tied to the
passed in session authentication key.

Like C<login()>, you may create a special pseudo file named LOGOUT and
use PerlHandler, (or "PerlResponseHandler" for mod_perl 2.x), to map it
to the C<logout()> method.  This is particularly handy when paired with
mod_rewrite to map a specific application URI to a pseudo file mapped to
C<logout()>  (See L</EXAMPLES> for a sample config that uses this method.)


=head1 EXAMPLES

 ## This is a partial configuration example showing most supported
 ## configuration options and a reverse proxy setup.  See examples/conf/
 ## in the Apache::AppSamurai distribution for real-world example configs.

 ## Apache 1.x/mod_perl 1.x settings are enabled with Apache 2.x/mod_perl 2.x
 ## config alternatives commented out. ("*FOR MODPERL2 USE:" precedes
 ## the Apache 2.x/mod_perl 2.x version of any alternative config items.)
 ## Note that example configs in examples/conf/ use IfDefine to support
 ## both version sets without having to comment out items. Also note that it
 ## is far too ugly looking to include in this example.

 ## General mod_perl setup
 
 # Apache::AppSamurai is always strict, warn, and taint clean. (Unless
 # I mucked something up ;)
 PerlWarn On
 PerlTaintCheck On
 PerlModule Apache::Registry
 #*FOR MODPERL2 USE:
 # PerlSwitches -wT
 # PerlModule ModPerl::Registry