view release on metacpan or  search on metacpan

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

Characters allowed in a password.  These are matched with a Perl regex and
character classes like "\w" and "\d" are allowed.  (Default:
C<< \w\d !\@\#\$\%\^\&\*:\,\.\?\-_=\+ >>)	      

=head3 I<PassStripWhite>

If set to 1, strips any whitespace surrounding the password.
(Default: 0)

=head3 I<DefaultLogLevel>

The L</AddError()> method can take two styles of input when adding log
lines to the object's errors array.  This option sets the logging
severity for log lines passed in without a specific severity set.
The valid values are the same as those allowed in the Apache C<LogLevel>
directive: emerg, alert, crit, error, warn, notice, info, and debug.
(Default: error)

=head2 Initialize()

Performs initial setup of object instance, returning 1 on success or 0
on failure.  Checks the C<< $self->{init} >> flag for a previous run,
and returns 1 of object has already been initialized.  Once completed,
the C<< $self->{init} >> flag is set to 1 before returning.

See L</EXAMPLES> for a sample overridden C<Initialize()> method.

=head2 Authenticator()

C<Apache::AppSamurai::AuthBase::Authenticator()> is just a skeleton and
must be overridden for each authentication module.  It is called with
an object reference and takes the username and password as two scalar
inputs.  It must return 0 on an authentication failure or any other
failure.  1 should only be returned on a clean and successful authentication.

B<Please carefully test this method in any authentication module before
using in production!>  Also, it is recommended that the last command inside
all C<Authenticator()> methods is C<return 0;>.  This helps ensure that
if there is some sort of unanticipated failure, or unanticipated fall through
condition, there is one more obstacle in the way of a potential authentication
bypass.

See L</EXAMPLES> for a simple example of a C<Authenticator()> method.

=head2 Authenticate()

This is called by Apache::AppSamurai to perform the authentication check.
It is called with an object reference and takes the username and password
as scalar arguments.

The username is validated using L</CheckInputUser()>, and then the password
is validated using L</CheckInputPass()>.  (If either of those fail,
an error is added and 0 is returned.)

After validation, L</Initialize()> is called if the C<< $self->{init} >>
flag has not been set.  (Note - Apache::AppSamurai calls C<Initialize()>
separately.  This functionality is added as a fail safe, or for testing.)

Finally, the object's L</Authenticator()> method is called to perform the
actual work of checking the credentials.  It's result is returned by
C<Authenticate()> to the caller.

C<Authenticate()> should not generally need to be overridden.

=head2 CheckInputUser()

Is called with an object ref and expects a scalar username as its only
argument.  If successful, the validated username is returned.  In case of
a failure or violation, C<undef> is returned.

C<CheckInputUser()> uses settings out of C<< $self->{conf} >> as follows:

=over 4

=item *

If I<UserStripWhite> is 1, surrounding whitespace is removed.

=item *

The username is checked against I<UserChars>.

=item *

The length of the username is checked against I<UserMin> and then I<UserMax>.

=item *

If I<UserUc> is 1, the username is converted to all caps.

=item *

If I<UserLc> is 1, the username is converted to all lower case.  (Note - 
I<UserUc> takes precedence if both are set.)

=back

If all conditions are met, the validated and cleaned username is returned.

C<CheckInputUser()> should not generally need to be overridden unless an
authentication module needs more extensive filtering.

=head2 CheckInputPass()

Is called with an object ref and expects a scalar password as its only
argument.  If successful, the validated password is returned.  In case of
a failure or violation, C<undef> is returned.

Note - "password" is used in the descriptions below.  This equates the
whatever data, (password, passphrase, PIN, whatever), will be passed as
an authentication credential to the authentication module.

C<CheckInputPass()> uses settings out of C<< $self->{conf} >> as follows:

=over 4

=item *

If I<PassStripWhite> is 1, surrounding whitespace is removed.  (This is
generally not a good idea unless the specific authentication system does

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

=item *

The password is checked against I<PassChars>.  Try to allow as many characters
as the underlying authentication system can safely support to avoid reducing
the strength of the passwords or other authentication data that can be used.
(Note - The default I<PassChars> should be decent for most uses, however,
it may be loosened or restricted more in future versions.)

=item *

The length of the password is checked against I<PassMin> and then I<PassMax>.
Once again, avoid limiting the maximum password length as much as safely
possible.

=back

If all conditions are met, the validated and cleaned password is returned.

C<CheckInputPass()> should not generally need to be overridden unless an
authentication module needs more extensive filtering.

=head2 AddError()

Adds a new log message to the C<< @{$self->{errors}} >> array, which is
returned to a then processed by Apache::AppSamurai.

C<AddError()> is called using an object reference and expects one of
two types of calls:

=over 4

=item *

One argument - This should be a single scalar containing the text to be
logged.  It will be added to the errors using the log level defined in
the I<DefaultLogLevel> configuration option.

=item *

Two arguments - This should be scalar containing the log level to use,
followed by a scalar with the message to be logged.

=back

C<AddError()> should not generally need to be overridden.

=head2 Errors()

Called using an object reference and returns an array of anonymous
arrays containing C<loglevel>, C<logmessage> pairs.  If no log messages
exist, undef is returned.

C<Errors()> is called by Apache::AppSamurai after using the authentication
module's C<Authenticate()> method.  It generally does not need to be
overridden.

=head1 EXAMPLES

Here is an example authentication module based on Auth::Base.  Let's call
it Apache::AppSamurai::AuthGarbage and have it use the fictitious module
Junk::Dumpster to check credentials.

 package Apache::AppSamurai::AuthGarbage;

 use Apache::AppSamurai::AuthBase;
 use Junk::Dumpster;  # Kids, don't try this at home 

 # Inherit the AuthBase wind...
 @ISA = qw( Apache::AppSamurai::AuthBase );
 
 # Override the Configure method to add special config options
 sub Configure {
     my $self = shift;

     # Pull defaults from AuthBase and save.
     $self->SUPER::Configure();
     my $conft = $self->{conf};
     
     # Initial configuration.  Put defaults here before the @_ args are
     # pulled in.
     $self->{conf} = { %{$conft},
                       Crud => 1,
                       Dumpster => 'supadumpy',
                       @_,
                     };
     return 1;
 }

 # Set an Initiate function to do any required setup and initialization
 # (Creating object instances, pre-flight checks, etc.)
 sub Initialize {
     my $self = shift;
 
     # Create Junk::Dumpster instance
     $self->{client} = new Junk::Dumpster(crud => $self->{conf}{Crud});
 
     # Set init flag
     $self->{init} = 1;
     return 1;
 }

 # Make authentication check
 sub Authenticator {
     my $self = shift;
     my $user = shift;
     my $pass = shift;
     my ($response, $error, @tmp, $check, $realm);
     
     # This is silly.  There is no Junk::Dumpster....
     $response = $self->{client}->IsItInDere($user,$pass);
     
     if ($response) {
         # You passed the test!
         return 1;
     } elsif ($!) {        
	 # An abnormal failure: Log an error
	 $self->AddError('error', "Failure from Junk:Garbage: $!");
	 return 0;
     }
 
     # Normal failure fall through.  Log the failure and kick back