view release on metacpan or  search on metacpan

lib/CGI/Auth/Auto.pm  view on Meta::CPAN

Be aware that then ALL of your runmodes in the cgi app will be protected.

By default, to trigger a logout by CGI::Application, we are looking for 

   rm=logout

In the query string.

What if you want it to be something else? Like runmode=log_me_out ?
Do this:
   
   use CGI::Auth::Auto;
   use MyCGIApp;
   $CGI::Auth::Auto::CGI_APP_COMPATIBLE = 'runmode=log_me_out';
   
   my $auth = new CGI::Auth::Auto;
   $auth->check;

   my $cgiapp = new MyCGIApp;
   $cgiapp->run;   
   
=head2 logout() EXAMPLE

Method logout() forces logout. This calls CGI::Auth method endsession() (see CGI::Auth doc), this sets the 
cookie expiry to 'now', and clears the CGI::Auth session id value from the cookie.
Effectively logging you out.
Keep in mind that logout() calls a CGI.pm redirect and then exits! 
This is to assure nothing else runs after that.

	if ($mycode_has_decided_to_boot_this_user){
		$auth->logout;
	}	

If the user maybe called an bad instruction or submitted funny data, or you detect a possible
intrusion etc.. Then your code should log it, and then call logout() as a last step.

	my $auth = new CGI::Auth::Auto;
	$auth->check;

   # check user input
	

	if( $we_really_dont_like_this_user_input ){

		# ok log it
		# ...
		
		# ok drop this auth and log user out, will exit(0)
		$auth->logout;
	}
	
	# nothing wrong.. continue script..
	# ...


=head1 EXAMPLE SCRIPT

This example script is included in the distribution.
Example assumes you installed CGI::Auth support files in $ENV{DOCUMENT_ROOT}/../cgi-bin/auth

Make this $ENV{DOCUMENT_ROOT}/../cgi-bin/auth.cgi to test it. Don't forget chmod 0755.

	#!/usr/bin/perl -w
	BEGIN { use CGI::Carp qw(fatalsToBrowser); eval qq|use lib '$ENV{DOCUMENT_ROOT}/../lib';|; } # or wherever your lib is 
	use strict;
	use CGI::Auth::Auto;
	use CGI qw(:all);
	
	my $auth = new CGI::Auth::Auto({
		-authdir => "$ENV{DOCUMENT_ROOT}/../cgi-bin/auth"
	}); # the program guesses for authdir, you can leave out if it resides alongside your script
	$auth->check;
	
   my $html =
	 header() .
	 start_html() .
	 h1("hello ".$auth->username) .
	 p('You are logged in now.') .
	 p('Would you like to log out? <a href="'.$ENV{SCRIPT_NAME}.'?logout=1">logout</a>');	
	
   print $html;

	exit;


Parameter -authdir is where you have the CGI::Auth support files. You need the user.dat file there, etc.
See CGI::Auth for more.

In the example user.dat provided, username:default password:

=head1 BUGS

Please report bugs via email to author.

=head1 CHANGES

A previous temptation was to add CGI::Session automation in addition to the cookie system. 
This way, by simply using this module, you will have authentication and state maintained
for you. I consider this now out of scope here. after simply running check() you could safely
run CGI::Session::new() without fear of creating multiple sessions. Since check() already 
decided by that point that the user is truly authenticated.

A custom login.html template has been included in this distribution under cgi-bin/auth/login.html.
This template is minimal as compares to the candy one that comes with CGI::Auth. 

=head1 DEBUG

To turn on debug info, in your cgi script, before you call check() :

   $CGI::Auth::Auto::DEBUG = 1;

=head1 ERRORS

The most common error is that you are not passing the right authdir to the object.

The authdir needs to exist and contain a user.dat simple text file.
If you do not provide an authdir argument, that's ok, we try to guess for it.
If your script is in /home/myself/cgi-bin/script.pl , then your auth dir is guessed as
/home/myself/cgi-bin/auth
And it must exist and contain the user.dat file. This can be a blank text file to begin with.
Make sure it is chown and chmod properly.

If your cgi is failing, turn on L<DEBUG> and run it again. A lot of useful information may be there.

=head2  Auth::check - Invalid 'User Name' field at ...

Erase your user.dat and recreate.

=head1 users.dat

This file must reside inside your auth dir.
If you script is in cgi-bin/script.cgi,
you must have a cgi-bin/auth/sess dir and a cgi-bin/auth/users.dat file
an example file is included in this distribution
please read CGI::Auth for more info on managing that file.

=head1 login.html

If you define the 'logintmpl' or 'logintmplpath' arguments to constructor, the program
tries to find login.html template or dies.
If not, it uses a barebones hard coded output.

So, again, if you have a cgi-bin/auth/login.html template:

   my $auth = new CGI::Auth::Auto({ -logintmpl => 'login.html' });

If not:

   my $auth = new CGI::Auth::Auto;

If you do but it resides elsewhere:

   my $auth = new CGI::Auth::Auto({ -logintmplpath => '/home/myself/public_html/templates' });


=head1 SEE ALSO

CGI::Auth, CGI::Cookie, HTML::Template

=head1 CONTRIBUTIONS

Dulaunoy Fabrice

=head1 AUTHOR

Leo Charre leocharre at cpan dot org

=cut