Koha/REST/V1/Auth.pm

   1 package Koha::REST::V1::Auth;
   2
   3 # Copyright Koha-Suomi Oy 2017
   4 #
   5 # This file is part of Koha.
   6 #
   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.
  11 #
  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.
  16 #
  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>.
  19
  20 use Modern::Perl;
  21
  22 use Mojo::Base 'Mojolicious::Controller';
  23
  24 use C4::Auth qw( check_cookie_auth checkpw_internal get_session haspermission );
  25 use C4::Context;
  26
  27 use Koha::ApiKeys;
  28 use Koha::Account::Lines;
  29 use Koha::Checkouts;
  30 use Koha::Holds;
  31 use Koha::Libraries;
  32 use Koha::OAuth;
  33 use Koha::OAuthAccessTokens;
  34 use Koha::Old::Checkouts;
  35 use Koha::Patrons;
  36
  37 use Koha::Exceptions;
  38 use Koha::Exceptions::Authentication;
  39 use Koha::Exceptions::Authorization;
  40
  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 );
  45
  46 =head1 NAME
  47
  48 Koha::REST::V1::Auth
  49
  50 =head2 Operations
  51
  52 =head3 under
  53
  54 This subroutine is called before every request to API.
  55
  56 =cut
  57
  58 sub under {
  59     my ( $c ) = @_;
  60
  61     my $status = 0;
  62
  63     try {
  64
  65         # /api/v1/{namespace}
  66         my $namespace = $c->req->url->to_abs->path->[2] // '';
  67
  68         my $is_public = 0; # By default routes are not public
  69         my $is_plugin = 0;
  70
  71         if ( $namespace eq 'public' ) {
  72             $is_public = 1;
  73         } elsif ( $namespace eq 'contrib' ) {
  74             $is_plugin = 1;
  75         }
  76
  77         if ( $is_public
  78             and !C4::Context->preference('RESTPublicAPI') )
  79         {
  80             Koha::Exceptions::Authorization->throw(
  81                 "Configuration prevents the usage of this endpoint by unprivileged users");
  82         }
  83
  84         if ( $c->req->url->to_abs->path eq '/api/v1/oauth/token' ) {
  85             # Requesting a token shouldn't go through the API authentication chain
  86             $status = 1;
  87         }
  88         elsif ( $namespace eq '' or $namespace eq '.html' ) {
  89             $status = 1;
  90         }
  91         else {
  92             $status = authenticate_api_request($c, { is_public => $is_public, is_plugin => $is_plugin });
  93         }
  94
  95     } catch {
  96         unless (blessed($_)) {
  97             return $c->render(
  98                 status => 500,
  99                 json => { error => 'Something went wrong, check the logs.' }
 100             );
 101         }
 102         if ($_->isa('Koha::Exceptions::UnderMaintenance')) {
 103             return $c->render(status => 503, json => { error => $_->error });
 104         }
 105         elsif ($_->isa('Koha::Exceptions::Authentication::SessionExpired')) {
 106             return $c->render(status => 401, json => { error => $_->error });
 107         }
 108         elsif ($_->isa('Koha::Exceptions::Authentication::Required')) {
 109             return $c->render(status => 401, json => { error => $_->error });
 110         }
 111         elsif ($_->isa('Koha::Exceptions::Authentication')) {
 112             return $c->render(status => 401, json => { error => $_->error });
 113         }
 114         elsif ($_->isa('Koha::Exceptions::BadParameter')) {
 115             return $c->render(status => 400, json => $_->error );
 116         }
 117         elsif ($_->isa('Koha::Exceptions::Authorization::Unauthorized')) {
 118             return $c->render(status => 403, json => {
 119                 error => $_->error,
 120                 required_permissions => $_->required_permissions,
 121             });
 122         }
 123         elsif ($_->isa('Koha::Exceptions::Authorization')) {
 124             return $c->render(status => 403, json => { error => $_->error });
 125         }
 126         elsif ($_->isa('Koha::Exceptions')) {
 127             return $c->render(status => 500, json => { error => $_->error });
 128         }
 129         else {
 130             return $c->render(
 131                 status => 500,
 132                 json => { error => 'Something went wrong, check the logs.' }
 133             );
 134         }
 135     };
 136
 137     return $status;
 138 }
 139
 140 =head3 authenticate_api_request
 141
 142 Validates authentication and allows access if authorization is not required or
 143 if authorization is required and user has required permissions to access.
 144
 145 =cut
 146
 147 sub authenticate_api_request {
 148     my ( $c, $params ) = @_;
 149
 150     my $user;
 151
 152     $c->stash( 'is_public' => 1 )
 153         if $params->{is_public};
 154
 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'};
 159
 160     $c->stash_embed( { spec => $spec } );
 161     $c->stash_overrides();
 162
 163     my $cookie_auth = 0;
 164
 165     my $authorization = $spec->{'x-koha-authorization'};
 166
 167     my $authorization_header = $c->req->headers->authorization;
 168
 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.'
 175             );
 176         }
 177         else {
 178             require Net::OAuth2::AuthorizationServer;
 179         }
 180
 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,
 186         );
 187
 188         if ($valid_token) {
 189             my $patron_id = Koha::ApiKeys->find( $valid_token->{client_id} )->patron_id;
 190             $user         = Koha::Patrons->find($patron_id);
 191         }
 192         else {
 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.'
 197             );
 198         }
 199     }
 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'
 204             );
 205         }
 206         $user = $c->_basic_auth( $authorization_header );
 207         unless ( $user ) {
 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.'
 212             );
 213         }
 214     }
 215     else {
 216
 217         my $cookie = $c->cookie('CGISESSID');
 218
 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(
 223                                                 $cookie, undef,
 224                                                 { remote_addr => $remote_addr });
 225
 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') );
 229                 $cookie_auth = 1;
 230             }
 231             elsif ( $status eq 'ok' ) {
 232                 Koha::Exceptions::Authentication->throw(
 233                     error => 'Cannot request a new token.' );
 234             }
 235             else {
 236                 Koha::Exceptions::Authentication::Required->throw(
 237                     error => 'Authentication failure.' );
 238             }
 239         }
 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' ) {
 242
 243             if ( $status eq 'setup-additional-auth-needed' ) {
 244                 $user        = Koha::Patrons->find( $session->param('number') );
 245                 $cookie_auth = 1;
 246             }
 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.' );
 253                 }
 254                 $cookie_auth = 1;
 255             }
 256             else {
 257                 Koha::Exceptions::Authentication::Required->throw(
 258                     error => 'Authentication failure.' );
 259             }
 260
 261         } else {
 262             if ($status eq "ok") {
 263                 $user = Koha::Patrons->find( $session->param('number') );
 264                 $cookie_auth = 1;
 265             }
 266             elsif ($status eq "anon") {
 267                 $cookie_auth = 1;
 268             }
 269             elsif ($status eq "additional-auth-needed") {
 270             }
 271             elsif ($status eq "maintenance") {
 272                 Koha::Exceptions::UnderMaintenance->throw(
 273                     error => 'System is under maintenance.'
 274                 );
 275             }
 276             elsif ($status eq "expired" and $authorization) {
 277                 Koha::Exceptions::Authentication::SessionExpired->throw(
 278                     error => 'Session has been expired.'
 279                 );
 280             }
 281             elsif ($status eq "failed" and $authorization) {
 282                 Koha::Exceptions::Authentication::Required->throw(
 283                     error => 'Authentication failure.'
 284                 );
 285             }
 286             elsif ($authorization) {
 287                 Koha::Exceptions::Authentication->throw(
 288                     error => 'Unexpected authentication status.'
 289                 );
 290             }
 291         }
 292     }
 293
 294     $c->stash('koha.user' => $user);
 295     C4::Context->interface('api');
 296
 297     if ( $user and !$cookie_auth ) { # cookie-auth sets this and more, don't mess with that
 298         $c->_set_userenv( $user );
 299     }
 300
 301     if ( !$authorization and
 302          ( $params->{is_public} and
 303           ( C4::Context->preference('RESTPublicAnonymousRequests') or
 304             $user) or $params->{is_plugin} )
 305     ) {
 306         # We do not need any authorization
 307         # Check the parameters
 308         validate_query_parameters( $c, $spec );
 309         return 1;
 310     }
 311     else {
 312         # We are required authorization, there needs
 313         # to be an identified user
 314         Koha::Exceptions::Authentication::Required->throw(
 315             error => 'Authentication failure.' )
 316           unless $user;
 317     }
 318
 319
 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) ) {
 325
 326         validate_query_parameters( $c, $spec );
 327
 328         # Everything is ok
 329         return 1;
 330     }
 331
 332     Koha::Exceptions::Authorization::Unauthorized->throw(
 333         error => "Authorization failure. Missing required permission(s).",
 334         required_permissions => $permissions,
 335     );
 336 }
 337
 338 =head3 validate_query_parameters
 339
 340 Validates the query parameters against the spec.
 341
 342 =cut
 343
 344 sub validate_query_parameters {
 345     my ( $c, $action_spec ) = @_;
 346
 347     # Check for malformed query parameters
 348     my @errors;
 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};
 353     }
 354
 355     Koha::Exceptions::BadParameter->throw(
 356         error => \@errors
 357     ) if @errors;
 358 }
 359
 360 =head3 allow_owner
 361
 362 Allows access to object for its owner.
 363
 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:
 367
 368 "/holds/{reserve_id}": {
 369     "get": {
 370         ...,
 371         "x-koha-authorization": {
 372             "allow-owner": true,
 373             "permissions": {
 374                 "borrowers": "1"
 375             }
 376         }
 377     }
 378 }
 379
 380 =cut
 381
 382 sub allow_owner {
 383     my ($c, $authorization, $user) = @_;
 384
 385     return unless $authorization->{'allow-owner'};
 386
 387     return check_object_ownership($c, $user) if $user and $c;
 388 }
 389
 390 =head3 allow_guarantor
 391
 392 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 393 guarantees.
 394
 395 =cut
 396
 397 sub allow_guarantor {
 398     my ($c, $authorization, $user) = @_;
 399
 400     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 401         return;
 402     }
 403
 404     my $guarantees = $user->guarantee_relationships->guarantees->as_list;
 405     foreach my $guarantee (@{$guarantees}) {
 406         return 1 if check_object_ownership($c, $guarantee);
 407     }
 408 }
 409
 410 =head3 check_object_ownership
 411
 412 Determines ownership of an object from request parameters.
 413
 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.
 419
 420 =cut
 421
 422 sub check_object_ownership {
 423     my ($c, $user) = @_;
 424
 425     return if not $c or not $user;
 426
 427     my $parameters = {
 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,
 433     };
 434
 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));
 439         }
 440         elsif ($c->param($param)) {
 441             return &$check_ownership($c, $user, $c->param($param));
 442         }
 443         elsif ($c->match->stack->[-1]->{$param}) {
 444             return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
 445         }
 446         elsif ($c->req->json && $c->req->json->{$param}) {
 447             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 448         }
 449     }
 450 }
 451
 452 =head3 _object_ownership_by_accountlines_id
 453
 454 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 455 belongs to C<$user>.
 456
 457 =cut
 458
 459 sub _object_ownership_by_accountlines_id {
 460     my ($c, $user, $accountlines_id) = @_;
 461
 462     my $accountline = Koha::Account::Lines->find($accountlines_id);
 463     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 464 }
 465
 466 =head3 _object_ownership_by_borrowernumber
 467
 468 Compares C<$borrowernumber> to currently logged in C<$user>.
 469
 470 =cut
 471
 472 sub _object_ownership_by_patron_id {
 473     my ($c, $user, $patron_id) = @_;
 474
 475     return $user->borrowernumber == $patron_id;
 476 }
 477
 478 =head3 _object_ownership_by_checkout_id
 479
 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>.
 484
 485 =cut
 486
 487 sub _object_ownership_by_checkout_id {
 488     my ($c, $user, $issue_id) = @_;
 489
 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;
 494 }
 495
 496 =head3 _object_ownership_by_reserve_id
 497
 498 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 499 belongs to C<$user>.
 500
 501 TODO: Also compare against old_reserves
 502
 503 =cut
 504
 505 sub _object_ownership_by_reserve_id {
 506     my ($c, $user, $reserve_id) = @_;
 507
 508     my $reserve = Koha::Holds->find($reserve_id);
 509     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 510 }
 511
 512 =head3 _basic_auth
 513
 514 Internal method that performs Basic authentication.
 515
 516 =cut
 517
 518 sub _basic_auth {
 519     my ( $c, $authorization_header ) = @_;
 520
 521     my ( $type, $credentials ) = split / /, $authorization_header;
 522
 523     unless ($credentials) {
 524         Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
 525     }
 526
 527     my $decoded_credentials = decode_base64( $credentials );
 528     my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
 529
 530     unless ( checkpw_internal($user_id, $password ) ) {
 531         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
 532     }
 533
 534     my $patron = Koha::Patrons->find({ userid => $user_id });
 535     if ( $patron->password_expired ) {
 536         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Password has expired' );
 537     }
 538
 539     return $patron;
 540 }
 541
 542 =head3 _set_userenv
 543
 544     $c->_set_userenv( $patron );
 545
 546 Internal method that sets C4::Context->userenv
 547
 548 =cut
 549
 550 sub _set_userenv {
 551     my ( $c, $patron ) = @_;
 552
 553     my $passed_library_id = $c->req->headers->header('x-koha-library');
 554     my $THE_library;
 555
 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);
 561     }
 562     else {
 563         $THE_library = $patron->library;
 564     }
 565
 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
 577     );
 578
 579     return $c;
 580 }
 581
 582 1;