1 package Koha::REST::V1::Auth;
3 # Copyright Koha-Suomi Oy 2017
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
22 use Mojo::Base 'Mojolicious::Controller';
24 use C4::Auth qw( check_cookie_auth checkpw_internal get_session haspermission );
28 use Koha::Account::Lines;
33 use Koha::OAuthAccessTokens;
34 use Koha::Old::Checkouts;
38 use Koha::Exceptions::Authentication;
39 use Koha::Exceptions::Authorization;
41 use MIME::Base64 qw( decode_base64 );
42 use Module::Load::Conditional;
43 use Scalar::Util qw( blessed );
44 use Try::Tiny qw( catch try );
54 This subroutine is called before every request to API.
66 my $namespace = $c->req->url->to_abs->path->[2] // '';
68 my $is_public = 0; # By default routes are not public
71 if ( $namespace eq 'public' ) {
73 } elsif ( $namespace eq 'contrib' ) {
78 and !C4::Context->preference('RESTPublicAPI') )
80 Koha::Exceptions::Authorization->throw(
81 "Configuration prevents the usage of this endpoint by unprivileged users");
84 if ( $c->req->url->to_abs->path =~ m#^/api/v1/oauth/# || $c->req->url->to_abs->path =~ m#^/api/v1/public/oauth/#) {
85 # Requesting OAuth endpoints shouldn't go through the API authentication chain
88 elsif ( $namespace eq '' or $namespace eq '.html' ) {
92 $status = authenticate_api_request($c, { is_public => $is_public, is_plugin => $is_plugin });
96 unless (blessed($_)) {
99 json => { error => 'Something went wrong, check the logs.' }
102 if ($_->isa('Koha::Exceptions::UnderMaintenance')) {
103 return $c->render(status => 503, json => { error => $_->error });
105 elsif ($_->isa('Koha::Exceptions::Authentication::SessionExpired')) {
106 return $c->render(status => 401, json => { error => $_->error });
108 elsif ($_->isa('Koha::Exceptions::Authentication::Required')) {
109 return $c->render(status => 401, json => { error => $_->error });
111 elsif ($_->isa('Koha::Exceptions::Authentication')) {
112 return $c->render(status => 401, json => { error => $_->error });
114 elsif ($_->isa('Koha::Exceptions::BadParameter')) {
115 return $c->render(status => 400, json => $_->error );
117 elsif ($_->isa('Koha::Exceptions::Authorization::Unauthorized')) {
118 return $c->render(status => 403, json => {
120 required_permissions => $_->required_permissions,
123 elsif ($_->isa('Koha::Exceptions::Authorization')) {
124 return $c->render(status => 403, json => { error => $_->error });
126 elsif ($_->isa('Koha::Exceptions')) {
127 return $c->render(status => 500, json => { error => $_->error });
132 json => { error => 'Something went wrong, check the logs.' }
140 =head3 authenticate_api_request
142 Validates authentication and allows access if authorization is not required or
143 if authorization is required and user has required permissions to access.
147 sub authenticate_api_request {
148 my ( $c, $params ) = @_;
152 $c->stash( 'is_public' => 1 )
153 if $params->{is_public};
155 # The following supports retrieval of spec with Mojolicious::Plugin::OpenAPI@1.17 and later (first one)
156 # and older versions (second one).
157 # TODO: remove the latter 'openapi.op_spec' if minimum version is bumped to at least 1.17.
158 my $spec = $c->openapi->spec || $c->match->endpoint->pattern->defaults->{'openapi.op_spec'};
160 $c->stash_embed( { spec => $spec } );
161 $c->stash_overrides();
165 my $authorization = $spec->{'x-koha-authorization'};
167 my $authorization_header = $c->req->headers->authorization;
169 if ($authorization_header and $authorization_header =~ /^Bearer /) {
170 # attempt to use OAuth2 authentication
171 if ( ! Module::Load::Conditional::can_load(
172 modules => {'Net::OAuth2::AuthorizationServer' => undef} )) {
173 Koha::Exceptions::Authorization::Unauthorized->throw(
174 error => 'Authentication failure.'
178 require Net::OAuth2::AuthorizationServer;
181 my $server = Net::OAuth2::AuthorizationServer->new;
182 my $grant = $server->client_credentials_grant(Koha::OAuth::config);
183 my ($type, $token) = split / /, $authorization_header;
184 my ($valid_token, $error) = $grant->verify_access_token(
185 access_token => $token,
189 my $patron_id = Koha::ApiKeys->find( $valid_token->{client_id} )->patron_id;
190 $user = Koha::Patrons->find($patron_id);
193 # If we have "Authorization: Bearer" header and oauth authentication
194 # failed, do not try other authentication means
195 Koha::Exceptions::Authentication::Required->throw(
196 error => 'Authentication failure.'
200 elsif ( $authorization_header and $authorization_header =~ /^Basic / ) {
201 unless ( C4::Context->preference('RESTBasicAuth') ) {
202 Koha::Exceptions::Authentication::Required->throw(
203 error => 'Basic authentication disabled'
206 $user = $c->_basic_auth( $authorization_header );
208 # If we have "Authorization: Basic" header and authentication
209 # failed, do not try other authentication means
210 Koha::Exceptions::Authentication::Required->throw(
211 error => 'Authentication failure.'
217 my $cookie = $c->cookie('CGISESSID');
219 # Mojo doesn't use %ENV the way CGI apps do
220 # Manually pass the remote_address to check_auth_cookie
221 my $remote_addr = $c->tx->remote_address;
222 my ($status, $session) = check_cookie_auth(
224 { remote_addr => $remote_addr });
226 if ( $c->req->url->to_abs->path eq '/api/v1/auth/otp/token_delivery' ) {
227 if ( $status eq 'additional-auth-needed' ) {
228 $user = Koha::Patrons->find( $session->param('number') );
231 elsif ( $status eq 'ok' ) {
232 Koha::Exceptions::Authentication->throw(
233 error => 'Cannot request a new token.' );
236 Koha::Exceptions::Authentication::Required->throw(
237 error => 'Authentication failure.' );
240 elsif ( $c->req->url->to_abs->path eq '/api/v1/auth/two-factor/registration'
241 || $c->req->url->to_abs->path eq '/api/v1/auth/two-factor/registration/verification' ) {
243 if ( $status eq 'setup-additional-auth-needed' ) {
244 $user = Koha::Patrons->find( $session->param('number') );
247 elsif ( $status eq 'ok' ) {
248 $user = Koha::Patrons->find( $session->param('number') );
249 if ( $user->auth_method ne 'password' ) {
250 # If the user already enabled 2FA they don't need to register again
251 Koha::Exceptions::Authentication->throw(
252 error => 'Cannot request this route.' );
257 Koha::Exceptions::Authentication::Required->throw(
258 error => 'Authentication failure.' );
262 if ($status eq "ok") {
263 $user = Koha::Patrons->find( $session->param('number') );
266 elsif ($status eq "anon") {
269 elsif ($status eq "additional-auth-needed") {
271 elsif ($status eq "maintenance") {
272 Koha::Exceptions::UnderMaintenance->throw(
273 error => 'System is under maintenance.'
276 elsif ($status eq "expired" and $authorization) {
277 Koha::Exceptions::Authentication::SessionExpired->throw(
278 error => 'Session has been expired.'
281 elsif ($status eq "failed" and $authorization) {
282 Koha::Exceptions::Authentication::Required->throw(
283 error => 'Authentication failure.'
286 elsif ($authorization) {
287 Koha::Exceptions::Authentication->throw(
288 error => 'Unexpected authentication status.'
294 $c->stash('koha.user' => $user);
295 C4::Context->interface('api');
297 if ( $user and !$cookie_auth ) { # cookie-auth sets this and more, don't mess with that
298 $c->_set_userenv( $user );
301 if ( !$authorization and
302 ( $params->{is_public} and
303 ( C4::Context->preference('RESTPublicAnonymousRequests') or
304 $user) or $params->{is_plugin} )
306 # We do not need any authorization
307 # Check the parameters
308 validate_query_parameters( $c, $spec );
312 # We are required authorization, there needs
313 # to be an identified user
314 Koha::Exceptions::Authentication::Required->throw(
315 error => 'Authentication failure.' )
320 my $permissions = $authorization->{'permissions'};
321 # Check if the user is authorized
322 if ( ( defined($permissions) and haspermission($user->userid, $permissions) )
323 or allow_owner($c, $authorization, $user)
324 or allow_guarantor($c, $authorization, $user) ) {
326 validate_query_parameters( $c, $spec );
332 Koha::Exceptions::Authorization::Unauthorized->throw(
333 error => "Authorization failure. Missing required permission(s).",
334 required_permissions => $permissions,
338 =head3 validate_query_parameters
340 Validates the query parameters against the spec.
344 sub validate_query_parameters {
345 my ( $c, $action_spec ) = @_;
347 # Check for malformed query parameters
349 my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
350 my $existing_params = $c->req->query_params->to_hash;
351 for my $param ( keys %{$existing_params} ) {
352 push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
355 Koha::Exceptions::BadParameter->throw(
362 Allows access to object for its owner.
364 There are endpoints that should allow access for the object owner even if they
365 do not have the required permission, e.g. access an own reserve. This can be
366 achieved by defining the operation as follows:
368 "/holds/{reserve_id}": {
371 "x-koha-authorization": {
383 my ($c, $authorization, $user) = @_;
385 return unless $authorization->{'allow-owner'};
387 return check_object_ownership($c, $user) if $user and $c;
390 =head3 allow_guarantor
392 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
397 sub allow_guarantor {
398 my ($c, $authorization, $user) = @_;
400 if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
404 my $guarantees = $user->guarantee_relationships->guarantees->as_list;
405 foreach my $guarantee (@{$guarantees}) {
406 return 1 if check_object_ownership($c, $guarantee);
410 =head3 check_object_ownership
412 Determines ownership of an object from request parameters.
414 As introducing an endpoint that allows access for object's owner; if the
415 parameter that will be used to determine ownership is not already inside
416 $parameters, add a new subroutine that checks the ownership and extend
417 $parameters to contain a key with parameter_name and a value of a subref to
418 the subroutine that you created.
422 sub check_object_ownership {
425 return if not $c or not $user;
428 accountlines_id => \&_object_ownership_by_accountlines_id,
429 borrowernumber => \&_object_ownership_by_patron_id,
430 patron_id => \&_object_ownership_by_patron_id,
431 checkout_id => \&_object_ownership_by_checkout_id,
432 reserve_id => \&_object_ownership_by_reserve_id,
435 foreach my $param ( keys %{ $parameters } ) {
436 my $check_ownership = $parameters->{$param};
437 if ($c->stash($param)) {
438 return &$check_ownership($c, $user, $c->stash($param));
440 elsif ($c->param($param)) {
441 return &$check_ownership($c, $user, $c->param($param));
443 elsif ($c->match->stack->[-1]->{$param}) {
444 return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
446 elsif ($c->req->json && $c->req->json->{$param}) {
447 return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
452 =head3 _object_ownership_by_accountlines_id
454 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
459 sub _object_ownership_by_accountlines_id {
460 my ($c, $user, $accountlines_id) = @_;
462 my $accountline = Koha::Account::Lines->find($accountlines_id);
463 return $accountline && $user->borrowernumber == $accountline->borrowernumber;
466 =head3 _object_ownership_by_borrowernumber
468 Compares C<$borrowernumber> to currently logged in C<$user>.
472 sub _object_ownership_by_patron_id {
473 my ($c, $user, $patron_id) = @_;
475 return $user->borrowernumber == $patron_id;
478 =head3 _object_ownership_by_checkout_id
480 First, attempts to find a Koha::Checkout-object by C<$issue_id>. If we find one,
481 compare its borrowernumber to currently logged in C<$user>. However, if an issue
482 is not found, attempt to find a Koha::Old::Checkout-object instead and compare its
483 borrowernumber to currently logged in C<$user>.
487 sub _object_ownership_by_checkout_id {
488 my ($c, $user, $issue_id) = @_;
490 my $issue = Koha::Checkouts->find($issue_id);
491 $issue = Koha::Old::Checkouts->find($issue_id) unless $issue;
492 return $issue && $issue->borrowernumber
493 && $user->borrowernumber == $issue->borrowernumber;
496 =head3 _object_ownership_by_reserve_id
498 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
501 TODO: Also compare against old_reserves
505 sub _object_ownership_by_reserve_id {
506 my ($c, $user, $reserve_id) = @_;
508 my $reserve = Koha::Holds->find($reserve_id);
509 return $reserve && $user->borrowernumber == $reserve->borrowernumber;
514 Internal method that performs Basic authentication.
519 my ( $c, $authorization_header ) = @_;
521 my ( $type, $credentials ) = split / /, $authorization_header;
523 unless ($credentials) {
524 Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
527 my $decoded_credentials = decode_base64( $credentials );
528 my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
530 unless ( checkpw_internal($user_id, $password ) ) {
531 Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
534 my $patron = Koha::Patrons->find({ userid => $user_id });
535 if ( $patron->password_expired ) {
536 Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Password has expired' );
544 $c->_set_userenv( $patron );
546 Internal method that sets C4::Context->userenv
551 my ( $c, $patron ) = @_;
553 my $passed_library_id = $c->req->headers->header('x-koha-library');
556 if ( $passed_library_id ) {
557 $THE_library = Koha::Libraries->find( $passed_library_id );
558 Koha::Exceptions::Authorization::Unauthorized->throw(
559 "Unauthorized attempt to set library to $passed_library_id"
560 ) unless $THE_library and $patron->can_log_into($THE_library);
563 $THE_library = $patron->library;
566 C4::Context->_new_userenv( $patron->borrowernumber );
567 C4::Context->set_userenv(
568 $patron->borrowernumber, # number,
569 $patron->userid, # userid,
570 $patron->cardnumber, # cardnumber
571 $patron->firstname, # firstname
572 $patron->surname, # surname
573 $THE_library->branchcode, # branch
574 $THE_library->branchname, # branchname
575 $patron->flags, # flags,
576 $patron->email, # emailaddress