view release on metacpan or  search on metacpan

Wyrd/Services/Auth.pm  view on Meta::CPAN

use 5.006;
use strict;
use warnings;
no warnings qw(uninitialized);

package Apache::Wyrd::Services::Auth;
our $VERSION = '0.98';
use Apache::Wyrd::Services::CodeRing;
use Apache::Wyrd::Services::TicketPad;
use Digest::SHA qw(sha256_hex);
use Apache::Wyrd::Request;
use Apache::Constants qw(AUTH_REQUIRED HTTP_SERVICE_UNAVAILABLE REDIRECT DECLINED);
use Apache::Wyrd::Cookie;
use Apache::URI;
use MIME::Base64;
use LWP::UserAgent;
use HTTP::Request::Common;

=pod

=head1 NAME

Apache::Wyrd::Services::Auth - Cookie-based authorization handler

=head1 SYNOPSIS

    <Directory /var/www/restricted/>
      SetHandler perl-script
      PerlHandler Apache::Wyrd::Services::Auth BASENAME::Handler
      PerlSetVar  LoginFormURL   /login.html
      PerlSetVar  NoCookieURL    /cookies.html
      PerlSetVar  LSKeyURL       https://login.someserver.com/login.html
      PerlSetVar  LSLoginURL     https://login.someserver.com/login.html
      PerlSetVar  LSDownURL      /lsdown.html
      PerlSetVar  AuthPath       /
      PerlSetVar  UserObject     BASENAME::User
      PerlSetVar  ReturnError    error_message
      PerlSetVar  AuthLevel      restricted
      PerlSetVar  Debug          0
      PerlSetVar  TieAddr        1
    </Directory>

=head1 DESCRIPTION

Auth provides a secure cookies-based login system for a Wyrd-enabled server
that might not itself be equipped with SSL.  It can do so if provided a
connection to an SSL-enabled Apache server with an
C<Apache::Wyrd::Services::LoginServer> available on a secure port.  It uses
a standard SSL channel to circumvent an unauthorized party from obtaining
login credentials (username/password) by packet-sniffing.

To do so, it maintains a cookie-based authorization scheme which is
implemented using stacked handlers.  It handles authorization by login
and/or cookie, and passes the user information to handlers down the
stack via mod_perl's C<notes> table.  The Auth module should be the
first handler in a chain of handlers.

The Auth Module first checks for a "challenge" variable under CGI which
it expects to contain a username/password pair encrypted via it's own
private encryption key (see the use of the
C<Apache::Wyrd::Services::Key> object in relation to the
C<Apache::Wyrd::Services::CodeRing> object).  This challenge is
generated by a LoginServer (see below), and is part of the regular login
sequence.  If this variable is provided, it will attempt to create a
user object from it and set a cookie on the browser (B<auth_cookie>)
which keeps this user object stored for later use.

If the challenge is not found, it checks for a cookie called
auth_cookie, and decrypts it, passing it on in an XML notes item called
"user" if it finds it.  (The user note is in perl code, stored and
retrieved by the next handler via C<XML::Dumper>.)

If the cookie is not found, it checks first to see if cookies are
enabled on the browser, and if not, sends the browser to a url to
explain the need for cookies.  It does this check by reloading the page
with a test cookie defined and checking for that cookie in the following
request.