view release on metacpan or  search on metacpan

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

    if ($r->auth_name) {
	my $auth_name = $r->auth_name;
	if ($r->dir_config("${auth_name}Debug")) {
	    ($r->dir_config("${auth_name}Debug") =~ /^(\d+)$/) && ($debug = $1);
	}
    }
    
    return $debug;
}

# Filter the output line before logging.  Restricts to no more than CharMax
# characters and converts everything matching BlankChars to a space to
# try and protect logging systems and log monitors from attack.
sub FilterLogLine {
    my $self = shift;
    my $line = (shift || return undef);
    my $LogCharMax = 1024;

    # Strip surrounding whitespace 
    $line =~ s/^\s*(.+?)\s*$/$1/s;
    # Convert newlines to ', '
    $line =~ s/\r?\n/, /sg;
    # Check length and truncate if needed
    $line = substr($line, 0, $LogCharMax);
    # Convert BlankChars matches to blanks
    $line =~ s/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\'\\]+/ /g;

    return $line;
}

1; # End of Apache::AppSamurai

__END__

=head1 NAME

Apache::AppSamurai - An Authenticating Mod_Perl Front End

"Protect your master, even if he is without honour...."

=head1 SYNOPSIS

All configuration is done within Apache.  Requires Apache 1.3.x/mod_perl1 or 
Apache 2.0.x/mod_perl2.  See L</EXAMPLES> for sample configuration segments.

=head1 DESCRIPTION

B<Apache::AppSamurai> protects web applications from direct attack by
unauthenticated users, and adds a flexible authentication front end
to local or proxied applications with limited authentication options.

Unauthenticated users are presented with either a login form, or a basic
authentication popup (depending on configuration.)  User supplied credentials
are checked against one or more authentication systems before the user's
session is created and a session authentication cookie is passed back to the
browser.  Only authenticated and authorized requests are proxied through
to the backend server.

Apache::AppSamurai is based on, and includes some code from,
L<Apache::AuthCookie|Apache::AuthCookie>.
Upon that core is added a full authentication and session handling framework.
(No coding required.)  Features include:

=over 4

=item *

B<Modular authentication> - Uses authentication sub-modules for the easy
addition custom authentication methods

=item *

B<Form based or Basic Auth login> - On the front end, supports standard
form based logins, or optionally Basic Auth login.  (For use with automated
systems that can not process a form.)

=item *

B<Apache::Session> - Used for session data handling

=item *

B<Session data encrypted on server> - By default, all session
data encrypted before storing to proxy's filesystem  (Uses custom
B<Apache::Session> compatible session generator and session serialization
modules)

=item *

B<Unified mod_perl 1 and 2 support> - One module set supports both
Apache 1.x/mod_perl 1.x and Apache 2.x/mod_perl 2.x

=back

=head1 SESSION STORAGE SECURITY

Server side session data may include sensitive information, including the basic
authentication C<Authorization> header to be sent to the backend server.
(This is just a Base64 encoded value, revealing the username and password
if stolen.)

To protect the data on-disk, Apache::AppSamurai includes
its own HMAC based session ID generator and encrypting session serializer.
(L<Apache::AppSamurai::Session::Generate::HMAC_SHA|Apache::AppSamurai::Session::Generate::HMAC_SHA>
and
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64>
, respectively.)
These modules are configured by default and may be used directly with
Apache::Session, or outside of Apache::AppSamurai if desired.

=head1 USAGE

Almost all options are set using C<PerlSetVar> statements, and can be used
inside most configuration sections.

Each configuration option must be prefixed by the I<AuthName> for the
Apache::AppSamurai instance you wish to apply the option to.  This
I<AuthName> is then referenced within the protected area(s).   Most of setups
only require one I<AuthName>.  You can call it "BOB" or "MegaAuthProtection".
You can even call it "authname". 

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

=head3 I<AuthMethods> C<METHOD1,METHOD2...>

(Default: undef)
A comma separated list of the authentication sub-modules to use.  The order of
the list must match the order of the C<credentials_X> parameters in the login
form. (Note - C<credential_0> is always the username, and is passed as such to
all the authentication modules.)

=head3 I<BasicAuthMap> C<N1,N2,.. = REGEX>

(Default: undef)

Custom mapping of Basic authentication password input to specific and separate
individual credentials. This allows for AppSamurai to request basic
authentication for an area, then split the input into credentials that can be
checked against multiple targets, just like a form based login.  This is very
useful for clients, like Windows Mobile ActiveSync, that only support basic
auth logins.  Using this feature you can add SecurID or other additional
authentication factors without having to pick only one.

The syntax is a bit odd.  First, specify a list of the credential numbers
you want mapped, in order they will be found within the input. Then
create a regular expression that will match the input, and group each item
you want mapped.

Example:

 PerlSetVar BobAuthBasicAuthMap "2,1=(.+);([^;]+)"

If the user logs into the basic auth popup with the password:
C<myRockinPassword;1234123456> ,the map above will set credential_1 as
C<1234123456> and credential_2 as C<myRockinPassword>, then proceed as if 
the same were entered into a form login.

=head3 ADDITIONAL AUTHENTICATION OPTIONS

Authentication submodules usually have one or more required settings.  All
settings are passed using PerlSetVar directives with variable names prefixed
with the AuthName and the module's name.

Example:

 PerlSetVar BobAuthBasicLoginUrl C<https://bob.org/login>

For AuthName C<Bob>, set the C<LoginUrl> for the C<AuthBasic> authentication
module to C<https://bob.org/login>

See L<Apache::AppSamurai::AuthBase> for general authentication module
information.  If you need an authentication type that is not supported
by the authentication modules shipped with AppSamurai, and is not
available as an add on module, please review L<Apache::AppSamurai::AuthBase>
and use the skeletal code from AuthTest.pm, which is included under
/examples/auth/ in the AppSamurai distribution.

=head2 SESSION CONFIGURATION

Each Apache::AppSamurai instance must have its local (proxy server side)
session handling defined.
L<Apache::Session|Apache::Session> provides the majority of the session
framework.  Around Apache::Session is wrapped
L<Apache::AppSamurai::Session|Apache::AppSamurai::Session>, which
adds features to allow for more flexible selection of sub-modules.

Most Apache::Session style configuration options can be passed directly to the
session system by prefixing them with C<authnameSession>.

Module selection is slightly different than the default supplied with
Apache::Session.  Plain names, without any path or ::, are handled
exactly the same: Modules are loaded from within the Apache::Session
tree.  Two additional alternatives are provided:

=over 4

=item *

I<AppSamurai/MODULE> - Load I<MODULE> from under the
B<Apache::AppSamurai::Session> tree instead of the B<Apache::Session> tree.

=item *

I<PATH::MODULE> - Load I<PATH::MODULE> literally.  Note - Since :: is required
to be present, a root module name will not work.

=back

The most common configuration options follow.  See
L<Apache::AppSamurai::Session|Apache::AppSamurai::Session> and
L<Apache::Session|Apache::Session> for
more advanced options, like using a database for storage.

B<NOTE> - "Session" is shown prepending each of these directives, Inside
the L<Apache::AppSamurai::Session|Apache::AppSamurai::Session> and
L<Apache::Session|Apache::Session> documentation, "Session" is omitted.

=head3 SessionI<Expire> C<SECONDS>

(Default: 0)
The maximum session lifetime in seconds.  After a user has been logged in this
long, they are logged out.  (Ignores weather the user is idle or not.)


=head3 SessionI<Timeout> C<SECONDS>
(Default: 3600 (1 hour)).

The maximum time a session can be idle before being removed.  After a user has
not accessed the protected application for this many seconds, they are logged
out.

=head3 SessionI<Store> C<NAME>

(Default: File)
The session 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 SessionI<Lock> C<NAME>

(Default: File)