<<

NAME

C4::Auth - Authenticates Koha users

SYNOPSIS

  use CGI;
  use C4::Auth;
  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, catalogue => '*', tools => 'import_patrons' },
  }
    );

  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.

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, catalogue => '*', tools => 'import_patrons' },
          }
        );

    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.

If the GranularPermissions system preference is ON, the value of each key in the flagsrequired hash takes on an additional meaning, e.g.,

1

The user must have access to all subfunctions of the module specified by the hash key.

*

The user must have access to at least one subfunction of the module specified by the hash key.

specific permission, e.g., 'export_catalog'

The user must have access to the specific subfunction list, which must correspond to a row in the permissions table.

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
    my $authflags = getuserflags($flags, $userid, [$dbh]);

Translates integer flags into permissions strings hash.

$flags is the integer userflags value ( borrowers.userflags ) $userid is the members.userid, used for building subpermissions $authflags is a hashref of permissions

get_user_subpermissions

my $user_perm_hashref = get_user_subpermissions($userid);

Given the userid (note, not the borrowernumber) of a staff user, return a hashref of hashrefs of the specific subpermissions accorded to the user. An example return is

{ tools => { export_catalog => 1, import_patrons => 1, } }

The top-level hash-key is a module or function code from userflags.flag, while the second-level key is a code from permissions.

The results of this function do not give a complete picture of the functions that a staff user can access; it is also necessary to check borrowers.flags.

get_all_subpermissions

my $perm_hashref = get_all_subpermissions();

Returns a hashref of hashrefs defining all specific permissions currently defined. The return value has the same structure as that of get_user_subpermissions, except that the innermost hash value is the description of the subpermission.

haspermission
  $flags = ($userid, $flagsrequired);

$userid the userid of the member $flags is a hashref of required flags like $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)

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 501:

Expected text after =item, not a number

Around line 506:

Expected text after =item, not a bullet

<<