view release on metacpan or  search on metacpan

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

# Apache::AppSamurai::AuthBasic - AppSamurai authentication against webserver
# using basic authentication.                                  

# $Id: AuthBasic.pm,v 1.18 2008/04/30 21:40:05 pauldoom Exp $

##
# Copyright (c) 2008 Paul M. Hirsch (paul@voltagenoir.org).
# All rights reserved.
#
# This program is free software; you can redistribute it and/or modify it under
# the same terms as Perl itself.
##

package Apache::AppSamurai::AuthBasic;
use strict;
use warnings;

use vars qw($VERSION @ISA);
$VERSION = substr(q$Revision: 1.18 $, 10, -1);

use Carp;
use Apache::AppSamurai::AuthBase;

# Below is used to make client connection to backend server to test auth
# and collect any cookies we want to keep
use LWP::UserAgent;
use HTTP::Request;
use MIME::Base64;

@ISA = qw( Apache::AppSamurai::AuthBase );

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},
		      LoginUrl => 'https://127.0.0.1', # URL to authenticate
		                                       # aginst
		      KeepAuth => 0, # Keep Authorization: Basic XXX header 
		                     # and continue to send to the proxied
                                     # servers. BE CAREFUL!
		      PassBackCookies => 0, # Pass all Set-Cookies back to
                                            # client browser
		      AllowRedirect => 0, # Follow redirects (Keep off and get
		                          # the URL right!)
		      UserAgent => '', # The User-Agent: header to report
		      RequireRealm => '', # If set, this realm must match that
		                          # returned by the backend server
		      SuccessCode => 200, # Auth considered a failure unless
                                          # this code is returned after login
		      Timeout => 10, # Timeout for connecting to auth server
		      PassMin => 3,
		      PassChars => '\w\d !\@\#\$\%\^\&\*,\.\?\-_=\+', # NOTE:
                                          # No : since that perplexes Mr. 
                                          # Basic Auth
		      @_,
		  };
    return 1;
}

sub Initialize {
    my $self = shift;

    # Holding space for alterlist items
    $self->{alterlist} = {};

    # Create LWP client and empty request
    $self->{client} = new LWP::UserAgent(timeout => $self->{conf}{Timeout});
    ($self->{client}) || ($self->AddError("Initialization of LWP::UserAgent failed: $!") && return 0);
    $self->{request} = new HTTP::Request("GET", $self->{conf}{LoginUrl});
    ($self->{request}) || ($self->AddError("Initialization of HTTP::Request failed: $!") && return 0);

    # Turn off all redirects if configured
    ($self->{conf}{AllowRedirect} == 1) || ($self->{client}->requests_redirectable([]));

    # Set the User-Agent for the request (You may want to use
    # "HEADER:User-Agent" as the value in your Apache config.  AppSamurai.pm
    # will fill in the client's User-Agent: header value per-request, then.)
    ($self->{conf}{UserAgent} eq '') || ($self->{request}->header('User-Agent' => $self->{conf}{UserAgent}));

    $self->{init} = 1;
    return 1;
}


# Connect to the server to check that authentication is required, 
# then send a second request with authentication and check for
# good return code
sub Authenticator {
    my $self = shift;
    my $user = shift;
    my $pass = shift;
    my ($response, $error, @tmp, $check, $realm);

    # Initial connect and check return for 401
    # Note - This pre-check is to make sure the target is actually listening
    $response = $self->{client}->request($self->{request});
    if ($response->code() != 401) {
	# Well, that ain't right!
	$self->AddError('error', "Failure or bad return code while connecting to \"" . $self->{conf}{LoginUrl} . "\": Code \"" . $response->code() . "\", $!");
	return 0;
    } 

    # Check for Basic in the list of WWW-Authorization values and
    # optional realm
    @tmp = $response->header("WWW-Authenticate");
    $check = 0;
    foreach (@tmp) {
        if (/^basic( realm=\"([^\"]*?)\")?$/i) {
	    $realm = $2;
	    
	    if ($self->{conf}{RequireRealm} ne '') {
		# Note - Realm matched without case sensitivity.
		unless ($realm =~ /^\Q$self->{conf}{RequireRealm}\E$/i) {
		    $self->AddError('error', "URL \"" . $self->{conf}{LoginUrl} . "\" returned the wrong realm: \"" . $realm . "\" (Check BasicAuthRequireRealm setting)");
		    return 0;
		}
	    }
	    
	    $check = 1;
	    last;
	}
    }
    unless ($check) {
	$self->AddError('error', "URL \"" . $self->{conf}{LoginUrl} . "\" did not list \"Basic\" as an allowed authentication method");
	return 0;
    }
    

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

the basic auth header,  If you use this feature, please leave the
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64> module configured as the session serialization
module.

=head2 I<PassBackCookies> C<0|1>

(Default: 0)
If 1, collects set cookies from the auth server and, upon successful login,
set them in the client web browser.

Even when using basic auth, many apps set cookies for various reasons.
This feature is most useful then the auth server and the protected
backend webserver are the same.  It may also be useful in the case of
using a ticket issuer of some sort as the auth server.  

B<Cross Server Warning:>
This feature does not alter the domain or path of the cookie.  It also does
not filter the cookie domain or path, nor does it translate cookies in
subsequent requests. For new applications, examine the cookie being set
in the browser and ensure that it should be sent to the protected 
servers and applications for this Apache::AppSamurai instance.

B<Session Storage Warning:>
This feature temporarily stores the cookie in the session data store on the
Apache::AppSamurai proxy server.
By default Apache::AppSamurai uses AES (Rijndael) to encrypt session data before storing it to disk, greatly reducing the risk of keeping
the cookie.  If you use this feature, please leave the
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64> module configured as the session serialization
module.

=head2 I<AllowRedirect> C<0|1>

(Default: 0)
If set to 1, allows the auth server to replay with a C<302 Redirect> code,
following the redirect to its eventual destination.

B<This feature should almost never be used!>  Instead, try to find the
eventual URL destination the auth server is expecting.  If you connect to
the auth server's port, (using C<openssl s_client -connect "SERVERNAME:PORT">
for SSL, or just C<telnet SERVERNAME PORT>), and request the page, it should
return a 401 code.

(The skill of being a human web browser is a useful one
to have for web work.
L<http://www.esqsoft.com/examples/troubleshooting-http-using-telnet.htm> gives
a very quick look at how to do it.  After that, check out
L<http://en.wikipedia.org/wiki/HTTP> or the HTTP RFCs for more info.)

=head2 I<SuccessCode> C<CODE>

(Default: 200)
This is the numerical HTTP response code the auth module should expect from
the auth server if the login was a success. 200 is usually correct.

B<Verifying this code is highly recommended!>  Some servers and apps return
a 200 on various failures. (In part, thanks to Internet Explorer's "helpful"
error handling feature that displays its usual generic "Uh, something
happened!" error message on code 500 and other errors that return a page
under a certain length.)

=head2 I<Timeout> C<SECONDS>

(Default: 10)
The number of seconds to wait for the auth server to respond.

=head2 I<PassChars> C<REGEX-CHARS>

(Default: C<< \w\d !\@\#\$\%\^\&\*,\.\?\-_=\+ >>)
This is actually a configuration item included in Apache::AppSamurai::AuthBase.
It is mentioned here because the AuthBasic version overrides the usual
default by removing the C<:> character.  (C<:> is used to split the username
and password inside the Base64 encoded authorization header.)

=head2 OTHERS

All other configuration items are inherited from
L<Apache::AppSamurai::AuthBase|Apache::AppSamurai::AuthBase>.  Consult
its documentation for more information.

=head1 METHODS

=head2 Configure()

Other than the AuthBasic specific configuration options, (described in
L</USAGE>), this is just a wrapper for the AuthBase C<Configure()>.

=head2 Initialize()

Performs the following additional actions:

=over 4

=item *

Creates C<< %{$self->{alterlist}} >> to hold header and cookie alterlist
rules.  (See L<Apache::AppSamurai|Apache::AppSamurai> for alterlist
information.)

=item *

Creates a L<LWP::UserAgent|LWP::UserAgent> instance and saves it in
C<< $self->{client} >>.

=item *

Creates a L<HTTP::Request|HTTP::Request> instance, containing the auth
server URL, and saves it in C<< $self->{request} >>.

=item *

If C<UserAgent> is set, collects (if C<header:> is used), then sets the
C<User-Agent> header in the request.

=back

=head2 Authenticator()

Performs the following actions, logging error(s) and returning 0 if any
actions fail:

=over 4