<<

NAME

C4::Auth - Authenticates Koha users

SYNOPSIS

  use CGI;
  use C4::Auth;

  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},
  }
    );

  print $query->header(
    -type => 'utf-8',
    -cookie => $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.

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
    Output.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.

check_api_auth
  ($status, $cookie, $sessionId) = check_api_auth($query, $userflags);

Given a CGI query containing the parameters 'userid' and 'password' and/or a session cookie, determine if the user has the privileges specified by $userflags.

check_api_auth is is meant for authenticating users of web services, and consequently will always return and will not attempt to redirect the user agent.

If a valid session cookie is already present, check_api_auth will return a status of "ok", the cookie, and the Koha session ID.

If no session cookie is present, check_api_auth will check the 'userid' and 'password parameters and create a session cookie and Koha session if the supplied credentials are OK.

Possible return values in $status are:

"ok" -- user authenticated; $cookie and $sessionid have valid values.
"failed" -- credentials are not correct; $cookie and $sessionid are undef
"maintenance" -- DB is in maintenance mode; no login possible at the moment
"expired -- session cookie has expired; API user should resubmit userid and password
check_cookie_auth
  ($status, $sessionId) = check_api_auth($cookie, $userflags);

Given a CGISESSID cookie set during a previous login to Koha, determine if the user has the privileges specified by $userflags.

check_cookie_auth is meant for authenticating special services such as tools/upload-file.pl that are invoked by other pages that have been authenticated in the usual way.

Possible return values in $status are:

"ok" -- user authenticated; $sessionID have valid values.
"failed" -- credentials are not correct; $sessionid are undef
"maintenance" -- DB is in maintenance mode; no login possible at the moment
"expired -- session cookie has expired; API user should resubmit userid and password
get_session
  use CGI::Session;
  my $session = get_session($sessionID);

Given a session ID, retrieve the CGI::Session object used to store the session's state. The session object can be used to store data that needs to be accessed by different scripts during a user's session.

If the $sessionID parameter is an empty string, a new session will be created.

getuserflags
 $authflags = getuserflags($flags,$dbh);
Translates integer flags into permissions strings hash.

$flags is the integer userflags value ( borrowers.userflags ) $authflags is a hashref of permissions

haspermission
  $flags = ($dbh,$member,$flagsrequired);

$member may be either userid or overloaded with $borrower hashref from GetMemberDetails. $flags is a hashref of required flags lik $borrower-&lt;{authflags}

Returns member's flags or 0 if a permission is not met.

SEE ALSO

CGI(3)

C4::Output(3)

Digest::MD5(3)

<<