view release on metacpan or  search on metacpan

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

=head3 FURTHER SESSION CONFIGURATION

See L<Apache::AppSamurai::Session|Apache::AppSamurai::Session> and
L<Apache::Session|Apache::Session> for more on the
session system.

=head2 TRACKER SYSTEM CONFIGURATION

The B<Tracker> system is a based on a set of special Apache::Session
stores that are visible between Apache processes.  (In fact, with a shared
central database, they could be visible to an entire cluster of servers.)
It is provided to store various state information for built-in and add-on
features.

Tracker storage uses
L<Apache::AppSamurai::Tracker|Apache::AppSamurai::Tracker>,
which is a modified version of Apache::AppSamurai::Session.  

Security Note - The Tracker system does not use encryption, so never store
sensitive information in a tracker.  If you need to track sensitive items,
encrypt or hash them beforehand.

=head3 TrackerI<Store> C<NAME>

(Default: File)
The tracker storage module name. "File" is the default, which maps to
B<Apache::Session::Store::File|Apache::Session::Store::File>
(Note - See the top of this section,
L</SESSION CONFIGURATION>, for details on the three ways to specify a path
for this option and the following options that point to a module.)

=head3 TrackerI<Lock> C<NAME>

(Default: File)
The tracker locking module name.  "File" is used by default, which maps to
B<Apache::Session::Lock::File|Apache::Session::Lock::File>

=head3 TrackerI<Cleanup> C<SECONDS>

(Default: undef)
If defined, tracked items that have been untouched in this many seconds
are removed.  In the future this may be configurable per-tracker type,
but for now it provides a rudimentary cleanup system.

=head3 FURTHER TRACKER SYSTEM CONFIGURATION

See L<Apache::AppSamurai::Tracker|Apache::AppSamurai::Tracker> for more
on tracker system configuration.

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