<<

NAME

InstallAuth - Authenticates Koha users for Install process

SYNOPSIS

  use CGI;
  use InstallAuth;
  use C4::Output;

  my $query = new CGI;

  my ($template, $borrowernumber, $cookie) 
    = get_template_and_user({template_name   => "opac-main.tmpl",
                             query           => $query,
                             type            => "opac",
                             authnotrequired => 1,
                             flagsrequired   => {borrow => 1},
                          });

  output_html_with_http_headers $query, $cookie, $template->output;

DESCRIPTION

    The main function of this module is to provide
    authentification. However the get_template_and_user function has
    been provided so that a users login information is passed along
    automatically. This gets loaded into the template.
    This package is different from C4::Auth in so far as 
    C4::Auth uses many preferences which are supposed NOT to be obtainable when installing the database.
    
    As in C4::Auth, Authentication is based on cookies.

FUNCTIONS

get_template_and_user
  my ($template, $borrowernumber, $cookie)
    = get_template_and_user({template_name   => "opac-main.tmpl",
                             query           => $query,
                             type            => "opac",
                             authnotrequired => 1,
                             flagsrequired   => {borrow => 1},
                          });

    This call passes the C<query>, C<flagsrequired> and C<authnotrequired>
    to C<&checkauth> (in this module) to perform authentification.
    See C<&checkauth> for an explanation of these parameters.

    The C<template_name> is then used to find the correct template for
    the page. The authenticated users details are loaded onto the
    template in the HTML::Template LOOP variable C<USER_INFO>. Also the
    C<sessionID> is passed to the template. This can be used in templates
    if cookies are disabled. It needs to be put as and input to every
    authenticated page.

    More information on the C<gettemplate> sub can be found in the
    Templates.pm module.
checkauth
  ($userid, $cookie, $sessionID) = &checkauth($query, $noauth, $flagsrequired, $type);

Verifies that the user is authorized to run this script. If the user is authorized, a (userid, cookie, session-id, flags) quadruple is returned. If the user is not authorized but does not have the required privilege (see $flagsrequired below), it displays an error page and exits. Otherwise, it displays the login page and exits.

Note that &checkauth will return if and only if the user is authorized, so it should be called early on, before any unfinished operations (e.g., if you've opened a file, then &checkauth won't close it for you).

$query is the CGI object for the script calling &checkauth.

The $noauth argument is optional. If it is set, then no authorization is required for the script.

&checkauth fetches user and session information from $query and ensures that the user is authorized to run scripts that require authorization.

The $flagsrequired argument specifies the required privileges the user must have if the username and password are correct. It should be specified as a reference-to-hash; keys in the hash should be the "flags" for the user, as specified in the Members intranet module. Any key specified must correspond to a "flag" in the userflags table. E.g., { circulate => 1 } would specify that the user must have the "circulate" privilege in order to proceed. To make sure that access control is correct, the $flagsrequired parameter must be specified correctly.

The $type argument specifies whether the template should be retrieved from the opac or intranet directory tree. "opac" is assumed if it is not specified; however, if $type is specified, "intranet" is assumed if it is not "opac".

If $query does not have a valid session ID associated with it (i.e., the user has not logged in) or if the session has expired, &checkauth presents the user with a login page (from the point of view of the original script, &checkauth does not return). Once the user has authenticated, &checkauth restarts the original script (this time, &checkauth returns).

The login page is provided using a HTML::Template, which is set in the systempreferences table or at the top of this file. The variable $type selects which template to use, either the opac or the intranet authentification template.

&checkauth returns a user ID, a cookie, and a session ID. The cookie should be sent back to the browser; it verifies that the user has authenticated.

SEE ALSO

CGI(3)

C4::Output(3)

Digest::MD5(3)

<<