AuthTicket.pm
Handle authorization for web services or restricted areas of a website.
This object oriented module is meant to be sub-classed.
Keep in mind that you'll want to create your own class that inherits this one. See the SUB-CLASSING EXAMPLE section below.
use WWW::AuthTicket;
my $auth = WWW::AuthTicket->new(-env => \%ENV, -secret_key => '[ABC123]');
my ($auth_ok, $msg) = $auth->verify_auth_cookie();
unless ($auth_ok) {
## send to log in screen (problem described in $msg)
}
my ($successful, $msg) = $auth->authenticate_user($username, $password);
if ($successful) {
print "Set-Cookie: " . $auth->issue_auth_cookie() . "\n";
} else {
## failure reason in $msg
## log out
print "Set-Cookie: " . $auth->void_auth_cookie() . "\n";
new()
Object constructor. Specify parameters as key/value pairs. Possible keys are:
A reference to the %ENV hash
A string of any length for the hashing algorithm
Length of time in minutes before the authorization should expire (default is no expiration, just the end of the browser's session). You would only need to specify this parameter when you are going to call issue_auth_cookie() because this value gets embedded in the cookie itself with issue_auth_cookie().
issue_auth_cookie()
If you want to call the cookie something other than the default name, "auth"
Use this to specify a domain for use in the cookie. Default is to use the "SERVER_NAME" environment variable which makes the cookie valid only for that particular host. You would specify a value here if you want the cookie to be good for other hosts under your domain.
my $auth = WWW::AuthTicket->new(-env => \%ENV, -secret_key => '*foobarbaz*');
authenticate_user()
Given a username/user ID and password, verifies the credentials and returns a boolean for whether or not the verification was successful and a message explaining any failure that might have occurred.
NOTE: This module can (and should) be sub-classed in order to provide your own customized authentication handling - like with a database. Values pulled from your user database can be added to the authorization cookie and also extracted from it after the cookie has been verified. See the get_cookie_value() method.
get_cookie_value()
add_cookie_value()
Use this method to add name/value pairs you want included in the authorization cookie. This method is useful for inclusion in your own authenticate_user() method that you create when you sub-class the AuthTicket class. Use it to save user-specific info that you pull back from your user database so that you don't have to look it up in the database for every request the user sends.
my $num_added = $self->add_cookie_value('userid' => $uid, 'authlevel' => $authlevel, ...);
It can return the number of values added for checking, but that is optional. You could just call it in a void context.
These values can then be retreived from the cookie using the get_cookie_value() method.
Returns the value from the specified part of the authorization cookie - verify_auth_cookie() method must be called first.
verify_auth_cookie()
my $userid = $auth->get_cookie_value('userid'); # example
Returns a CGI::Cookie-formatted cookie. Use after authenticate_user() returns successful.
CGI::Cookie
void_auth_cookie()
Returns a CGI::Cookie-formatted cookie that deletes the auth cookie. Use for logging a user out.
Parses and verifies the authorization cookie. Returns a boolean for whether or not the verification was successful and a message explaining any failure that might have occurred.
make_return_address()
Returns a CGI::Cookie-formatted cookie that contains the URI the user is trying to access. Here's how to use this: say a user is trying to access a URI that requires them to be logged in, but they are either not logged in or their login has expired. Use this to save the URI for the page they were trying to access so that after they log in you can send them where they were trying to go before they were interrupted with the log-in process.
print "Set-Cookie: " . $auth->make_return_address() . "\n";
get_return_address()
Returns the URI from the cookie set with make_return_address().
my $requested_uri = $auth->get_return_address();
clear_return_address()
Returns a CGI::Cookie-formatted cookie that deletes the return address cookie that was set with make_return_address(). Use after a successful log in so that the user doesn't get redirected to the saved URI over and over again.
print "Set-Cookie: " . $auth->clear_return_address() . "\n";
package MyAuthTicket;
use strict;
use vars qw(@ISA);
@ISA = ("WWW::AuthTicket");
## add or override methods here
sub authenticate_user {
...
1;
Then use MyAuthTicket instead of AuthTicket. All methods from AuthTicket are now available in MyAuthTicket plus whatever you add to MyAuthTicket.
use MyAuthTicket;
my $auth = MyAuthTicket->new(-env => \%ENV, -secret_key => '*foobarbaz*');
None known.
This is kind of a hacked up version the TicketTool module in _Writing_Apache_Modules_with_Perl_and_C_ by Lincoln Stein & Doug MacEachern (O'Reilly)
John Winger (john 2 wingeronline. com)
(c) 2007 John W. Winger III.
This program is free software. You may copy or redistribute it under the same terms as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
You can't have =items (as at line 73) unless the first thing after the =over is an =item
You forgot a '=back' before '=head1'
To install WWW::AuthTicket, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::AuthTicket
CPAN shell
perl -MCPAN -e shell install WWW::AuthTicket
For more information on module installation, please visit the detailed CPAN module installation guide.