C4::Auth - Authenticates Koha users
use CGI qw ( -utf8 );
use C4::Auth;
use C4::Output;
my $query = CGI->new;
my ($template, $borrowernumber, $cookie)
= get_template_and_user(
{
template_name => "opac-main.tt",
query => $query,
type => "opac",
authnotrequired => 0,
flagsrequired => { 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.tt",
query => $query,
type => "opac",
authnotrequired => 0,
flagsrequired => { 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 logged_in_user variable (which is a Koha::Patron object). 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_cookie_auth($cookie, $userflags);
Given a CGISESSID cookie set during a previous login to Koha, determine if the user has the privileges specified by $userflags. $userflags is passed unaltered into haspermission and as such accepts all options avaiable to that routine with the one caveat that check_api_auth will also allow 'undef' to be passed and in such a case the permissions check will be skipped altogether.
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 $session = create_basic_session({ patron => $patron, interface => $interface });
Creates a session and adds all basic parameters for a session to work
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.
my $required_permissions = get_cataloguing_page_permissions();
Returns the required permissions to access the main cataloguing page. Useful for building the global can_see_cataloguing_module template variable, and also for reusing in cataloging-home.pl.
$flagsrequired = '*'; # Any permission at all
$flagsrequired = 'a_flag'; # a_flag must be satisfied (all subpermissions)
$flagsrequired = [ 'a_flag', 'b_flag' ]; # a_flag OR b_flag must be satisfied
$flagsrequired = { 'a_flag => 1, 'b_flag' => 1 }; # a_flag AND b_flag must be satisfied
$flagsrequired = { 'a_flag' => 'sub_a' }; # sub_a of a_flag must be satisfied
$flagsrequired = { 'a_flag' => [ 'sub_a, 'sub_b' ] }; # sub_a OR sub_b of a_flag must be satisfied
$flagsrequired = { 'a_flag' => { 'sub_a' => 1, 'sub_b' => 1 } }; # sub_a AND sub_b of a_flag must be satisfied
$flags = ($userid, $flagsrequired);
$userid the userid of the member $flags is a query structure similar to that used by SQL::Abstract that denotes the combination of flags required. It is a required parameter.
The main logic of this method is that things in arrays are OR'ed, and things in hashes are AND'ed. The `*` character can be used, at any depth, to denote `ANY`
Returns member's flags or 0 if a permission is not met.
$flags = ($iprange);
$iprange A space separated string describing an IP range. Can include single IPs or ranges
Returns 1 if the remote address is in the provided iprange, or 0 otherwise.
CGI(3)
C4::Output(3)
Crypt::Eksblowfish::Bcrypt(3)
Digest::MD5(3)