NAME

CGI::Authent - request a HTTP authentification under specified conditions

version 0.2.1

SYNOPSIS

use CGI::Authent Basic => 'The realm name', test => 'CGI::Authent::between "h:m-h:m"';

DESCRIPTION

Send the HTTP 401 UnAuthentified header if a condition (by default "defined $ENV{REMOTE_USER}") fails. Since your script doesn't get the password the user entered, you cannot use it as the only authentification scheme. And it was not intended to work like this. You have to find some other way to check the username/password pair.

It was written primarily to overcome a bug in MS IIS/3.0. IIS usualy sends a HTTP 401 response if it finds out that it cannot access a file using the current users premissions (IUSR_... or the login/password you entered), but since IIS doesn't check the permissions to the script before launching perl, you get an error message :

    CGI Error

    The specified CGI application misbehaved by not returning a complete set
    of HTTP headers. The headers it did return are:

    Can't open perl script "...": Permission denied 

instead of a login/password dialog.

So instead of restricting the permissions for the scripts, you will add

    use CGI::Authent;

at the very beginning of your scripts and update CGI/Authent.config.pl to suggest your servers authentification method.

The login/password pair your user will enter into the dialog /s?he/ will get will be checked by the server and mapped to an account, so all you have to do, if all authentified users are to be able to access your script, is to check the system variable REMOTE_USER - the default test.

If you want to restrict the access to a group of users you may check whether the script as it runs has enough permissions to access a file and then restrict the access to this file.

    use CGI::Authent {test => 'CGI::Authent::can_read "c:\\inetpub\\group1.lck"'}

Ussage

    use CGI::Authent;
     Use the default options as set in CGI/Authent.config.pl.
    use CGI::Authent {options}, [$msg];
    use CGI::Authent options, [$msg];
     Replace the default options from CGI/Authent.congfig.pl, by the ones
     presented here.

Options

 NTLM => 1/0
  Should we use/suggest NTLM authentification?
  
 Basic => ''/'IP'/'_default'/'the realm'
  Should we use the Basic authentification?
  '', 'IP' and '_default' both mean that the realm will
  be the servers IP address, which is default for MS IIS.
 
 msg => 'the message that should be showed if the authentification fails'
 
 test => \&some_boolean_function / 'some perl code' / '_default'
      / 'Authent::can_read "filename"' / 'Authent::between "h:m-h:m"'
  The test that should be performed. You may use either a reference to
  a function, or a string to be eval()uated. The string '_default' has
  a special meaning, it gets translated to 'defined $ENV{REMOTE_USER}',
  so it checks if the user was authentificated by the server.
  If the function/expression returns a true value, the script runs,
  otherwise the user gets asked for a login/password pair.

 header => 'Some: additional headers'
  You may add some headers to the response that will be sent if the test fails.
  You may add several headers either as
   header => 'Header1\r\nHeader2'
  or
   header1 => 'Header1',
   header2 => 'Header2'
   
 Authenticate => 'Additional authentification methods'
  You may specify additional authentification methods here.
  The string you specify will be prepended by 'WWW-Authenticate: ' and
  added to the headers.
  You may use the same methods for several methods as with headers.

Tests

The default test is 'defined $ENV{REMOTE_USER}' which only checks whether the user entered any login/password pair that was accepted by the server.

Other predefined tests are :

 CGI::Authent::can_read $file[, $file2, ...]
  Does the script have permissions to read the file(s)?
 
 CGI::Authent::isbetween 'h:m-h:m';
  It the time in this range?

 CGI::Authent::between 'h:m-h:m';
  It the time in this range? This version will disallow
  access buring other times completely! No request for authentification,
  just 403 Forbiden response!

You may of course combine several tests :

 test => 'CGI::Authent::can_read "c:\\inetpub\\group1.lck" and CGIAuthent::between '8:00-17:00'
          or
          CGI::Authent::can_read "c:\\inetpub\\group2.lck" and CGI::Authent::between '17:00-8:00'
         '

Other functions

 CGI::Authent::forbide [$message]
  Send the "HTTP 403 Forbiden" response.

 CGI::Authent::login [$message]
  Send the "HTTP 401 UnAuthentified" response.

REMINDER

CGI::Authent doesn't validate the passwords. It cannot even see them. It just does a few tests and if the tests fail it sends to the user a request for authentication. But it's the server's task to validate the credentials passed by the browser.

If you want for example to validate passwords against a database, consult your servers documentation. You will probably have to install some filter or plugin. It should be relatively easy to find such beasts on the net. I've written an ISAPI filter for this, you may get it at http://jenda.krynicky.cz/authfilter.1.0.zip . Take it as an example, not as a solution!

Guts

All options are parsed and added to the headers before yout test runs, so you may change the headers from it.

The headers are in $CGI::Authent::header, the message is in $CGI::Authent::message.

AUTHOR

Jan Krynicky <Jenda@Krynicky.cz> 7/26/1999

cpanm CGI::Authent

perl -MCPAN -e shell
install CGI::Authent