C4::Auth - Authenticates Koha users
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;
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.
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 query, flagsrequired and authnotrequired to &checkauth (in this module) to perform authentification. See &checkauth for an explanation of these parameters.
The 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 USER_INFO. Also the 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 gettemplate sub can be found in the Output.pm module.
($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.
Koha also has a concept of sub-permissions, also known as granular permissions. This makes the value of each key in the flagsrequired hash take on an additional meaning, i.e.,
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.
($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:
$cookie and $sessionid have valid values.$cookie and $sessionid are undef($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:
$sessionID have valid values.$sessionid are undefuse 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.
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
$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.
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.
$flags = ($userid, $flagsrequired);
$userid the userid of the member $flags is a hashref of required flags like $borrower-<{authflags}
Returns member's flags or 0 if a permission is not met.
CGI(3)
C4::Output(3)
Digest::MD5(3)