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 =~ 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
  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     # FIXME: Remove once CGI is not used
 164     my $accept_language = $c->req->headers->accept_language;
 165     $ENV{HTTP_ACCEPT_LANGUAGE} = $accept_language
 166         if $accept_language;
 167
 168     my $cookie_auth = 0;
 169
 170     my $authorization = $spec->{'x-koha-authorization'};
 171
 172     my $authorization_header = $c->req->headers->authorization;
 173
 174     if ($authorization_header and $authorization_header =~ /^Bearer /) {
 175         # attempt to use OAuth2 authentication
 176         if ( ! Module::Load::Conditional::can_load(
 177                     modules => {'Net::OAuth2::AuthorizationServer' => undef} )) {
 178             Koha::Exceptions::Authorization::Unauthorized->throw(
 179                 error => 'Authentication failure.'
 180             );
 181         }
 182         else {
 183             require Net::OAuth2::AuthorizationServer;
 184         }
 185
 186         my $server = Net::OAuth2::AuthorizationServer->new;
 187         my $grant = $server->client_credentials_grant(Koha::OAuth::config);
 188         my ($type, $token) = split / /, $authorization_header;
 189         my ($valid_token, $error) = $grant->verify_access_token(
 190             access_token => $token,
 191         );
 192
 193         if ($valid_token) {
 194             my $patron_id = Koha::ApiKeys->find( $valid_token->{client_id} )->patron_id;
 195             $user         = Koha::Patrons->find($patron_id);
 196         }
 197         else {
 198             # If we have "Authorization: Bearer" header and oauth authentication
 199             # failed, do not try other authentication means
 200             Koha::Exceptions::Authentication::Required->throw(
 201                 error => 'Authentication failure.'
 202             );
 203         }
 204     }
 205     elsif ( $authorization_header and $authorization_header =~ /^Basic / ) {
 206         unless ( C4::Context->preference('RESTBasicAuth') ) {
 207             Koha::Exceptions::Authentication::Required->throw(
 208                 error => 'Basic authentication disabled'
 209             );
 210         }
 211         $user = $c->_basic_auth( $authorization_header );
 212         unless ( $user ) {
 213             # If we have "Authorization: Basic" header and authentication
 214             # failed, do not try other authentication means
 215             Koha::Exceptions::Authentication::Required->throw(
 216                 error => 'Authentication failure.'
 217             );
 218         }
 219     }
 220     else {
 221
 222         my $cookie = $c->cookie('CGISESSID');
 223
 224         # Mojo doesn't use %ENV the way CGI apps do
 225         # Manually pass the remote_address to check_auth_cookie
 226         my $remote_addr = $c->tx->remote_address;
 227         my ($status, $session) = check_cookie_auth(
 228                                                 $cookie, undef,
 229                                                 { remote_addr => $remote_addr });
 230
 231         if ( $c->req->url->to_abs->path eq '/api/v1/auth/otp/token_delivery' ) {
 232             if ( $status eq 'additional-auth-needed' ) {
 233                 $user        = Koha::Patrons->find( $session->param('number') );
 234                 $cookie_auth = 1;
 235             }
 236             elsif ( $status eq 'ok' ) {
 237                 Koha::Exceptions::Authentication->throw(
 238                     error => 'Cannot request a new token.' );
 239             }
 240             else {
 241                 Koha::Exceptions::Authentication::Required->throw(
 242                     error => 'Authentication failure.' );
 243             }
 244         }
 245         elsif (  $c->req->url->to_abs->path eq '/api/v1/auth/two-factor/registration'
 246               || $c->req->url->to_abs->path eq '/api/v1/auth/two-factor/registration/verification' ) {
 247
 248             if ( $status eq 'setup-additional-auth-needed' ) {
 249                 $user        = Koha::Patrons->find( $session->param('number') );
 250                 $cookie_auth = 1;
 251             }
 252             elsif ( $status eq 'ok' ) {
 253                 $user = Koha::Patrons->find( $session->param('number') );
 254                 if ( $user->auth_method ne 'password' ) {
 255                     # If the user already enabled 2FA they don't need to register again
 256                     Koha::Exceptions::Authentication->throw(
 257                         error => 'Cannot request this route.' );
 258                 }
 259                 $cookie_auth = 1;
 260             }
 261             else {
 262                 Koha::Exceptions::Authentication::Required->throw(
 263                     error => 'Authentication failure.' );
 264             }
 265
 266         } else {
 267             if ($status eq "ok") {
 268                 $user = Koha::Patrons->find( $session->param('number') );
 269                 $cookie_auth = 1;
 270             }
 271             elsif ($status eq "anon") {
 272                 $cookie_auth = 1;
 273             }
 274             elsif ($status eq "additional-auth-needed") {
 275             }
 276             elsif ($status eq "maintenance") {
 277                 Koha::Exceptions::UnderMaintenance->throw(
 278                     error => 'System is under maintenance.'
 279                 );
 280             }
 281             elsif ($status eq "expired" and $authorization) {
 282                 Koha::Exceptions::Authentication::SessionExpired->throw(
 283                     error => 'Session has been expired.'
 284                 );
 285             }
 286             elsif ($status eq "failed" and $authorization) {
 287                 Koha::Exceptions::Authentication::Required->throw(
 288                     error => 'Authentication failure.'
 289                 );
 290             }
 291             elsif ($authorization) {
 292                 Koha::Exceptions::Authentication->throw(
 293                     error => 'Unexpected authentication status.'
 294                 );
 295             }
 296         }
 297     }
 298
 299     $c->stash('koha.user' => $user);
 300     C4::Context->interface('api');
 301
 302     if ( $user and !$cookie_auth ) { # cookie-auth sets this and more, don't mess with that
 303         $c->_set_userenv( $user );
 304     }
 305
 306     if ( !$authorization and
 307          ( $params->{is_public} and
 308           ( C4::Context->preference('RESTPublicAnonymousRequests') or
 309             $user) or $params->{is_plugin} )
 310     ) {
 311         # We do not need any authorization
 312         # Check the parameters
 313         validate_query_parameters( $c, $spec );
 314         return 1;
 315     }
 316     else {
 317         # We are required authorization, there needs
 318         # to be an identified user
 319         Koha::Exceptions::Authentication::Required->throw(
 320             error => 'Authentication failure.' )
 321           unless $user;
 322     }
 323
 324
 325     my $permissions = $authorization->{'permissions'};
 326     # Check if the user is authorized
 327     if ( ( defined($permissions) and haspermission($user->userid, $permissions) )
 328         or allow_owner($c, $authorization, $user)
 329         or allow_guarantor($c, $authorization, $user) ) {
 330
 331         validate_query_parameters( $c, $spec );
 332
 333         # Everything is ok
 334         return 1;
 335     }
 336
 337     Koha::Exceptions::Authorization::Unauthorized->throw(
 338         error => "Authorization failure. Missing required permission(s).",
 339         required_permissions => $permissions,
 340     );
 341 }
 342
 343 =head3 validate_query_parameters
 344
 345 Validates the query parameters against the spec.
 346
 347 =cut
 348
 349 sub validate_query_parameters {
 350     my ( $c, $action_spec ) = @_;
 351
 352     # Check for malformed query parameters
 353     my @errors;
 354     my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
 355     my $existing_params = $c->req->query_params->to_hash;
 356     for my $param ( keys %{$existing_params} ) {
 357         push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
 358     }
 359
 360     Koha::Exceptions::BadParameter->throw(
 361         error => \@errors
 362     ) if @errors;
 363 }
 364
 365 =head3 allow_owner
 366
 367 Allows access to object for its owner.
 368
 369 There are endpoints that should allow access for the object owner even if they
 370 do not have the required permission, e.g. access an own reserve. This can be
 371 achieved by defining the operation as follows:
 372
 373 "/holds/{reserve_id}": {
 374     "get": {
 375         ...,
 376         "x-koha-authorization": {
 377             "allow-owner": true,
 378             "permissions": {
 379                 "borrowers": "1"
 380             }
 381         }
 382     }
 383 }
 384
 385 =cut
 386
 387 sub allow_owner {
 388     my ($c, $authorization, $user) = @_;
 389
 390     return unless $authorization->{'allow-owner'};
 391
 392     return check_object_ownership($c, $user) if $user and $c;
 393 }
 394
 395 =head3 allow_guarantor
 396
 397 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 398 guarantees.
 399
 400 =cut
 401
 402 sub allow_guarantor {
 403     my ($c, $authorization, $user) = @_;
 404
 405     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 406         return;
 407     }
 408
 409     my $guarantees = $user->guarantee_relationships->guarantees->as_list;
 410     foreach my $guarantee (@{$guarantees}) {
 411         return 1 if check_object_ownership($c, $guarantee);
 412     }
 413 }
 414
 415 =head3 check_object_ownership
 416
 417 Determines ownership of an object from request parameters.
 418
 419 As introducing an endpoint that allows access for object's owner; if the
 420 parameter that will be used to determine ownership is not already inside
 421 $parameters, add a new subroutine that checks the ownership and extend
 422 $parameters to contain a key with parameter_name and a value of a subref to
 423 the subroutine that you created.
 424
 425 =cut
 426
 427 sub check_object_ownership {
 428     my ($c, $user) = @_;
 429
 430     return if not $c or not $user;
 431
 432     my $parameters = {
 433         accountlines_id => \&_object_ownership_by_accountlines_id,
 434         borrowernumber  => \&_object_ownership_by_patron_id,
 435         patron_id       => \&_object_ownership_by_patron_id,
 436         checkout_id     => \&_object_ownership_by_checkout_id,
 437         reserve_id      => \&_object_ownership_by_reserve_id,
 438     };
 439
 440     foreach my $param ( keys %{ $parameters } ) {
 441         my $check_ownership = $parameters->{$param};
 442         if ($c->stash($param)) {
 443             return &$check_ownership($c, $user, $c->stash($param));
 444         }
 445         elsif ($c->param($param)) {
 446             return &$check_ownership($c, $user, $c->param($param));
 447         }
 448         elsif ($c->match->stack->[-1]->{$param}) {
 449             return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
 450         }
 451         elsif ($c->req->json && $c->req->json->{$param}) {
 452             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 453         }
 454     }
 455 }
 456
 457 =head3 _object_ownership_by_accountlines_id
 458
 459 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 460 belongs to C<$user>.
 461
 462 =cut
 463
 464 sub _object_ownership_by_accountlines_id {
 465     my ($c, $user, $accountlines_id) = @_;
 466
 467     my $accountline = Koha::Account::Lines->find($accountlines_id);
 468     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 469 }
 470
 471 =head3 _object_ownership_by_borrowernumber
 472
 473 Compares C<$borrowernumber> to currently logged in C<$user>.
 474
 475 =cut
 476
 477 sub _object_ownership_by_patron_id {
 478     my ($c, $user, $patron_id) = @_;
 479
 480     return $user->borrowernumber == $patron_id;
 481 }
 482
 483 =head3 _object_ownership_by_checkout_id
 484
 485 First, attempts to find a Koha::Checkout-object by C<$issue_id>. If we find one,
 486 compare its borrowernumber to currently logged in C<$user>. However, if an issue
 487 is not found, attempt to find a Koha::Old::Checkout-object instead and compare its
 488 borrowernumber to currently logged in C<$user>.
 489
 490 =cut
 491
 492 sub _object_ownership_by_checkout_id {
 493     my ($c, $user, $issue_id) = @_;
 494
 495     my $issue = Koha::Checkouts->find($issue_id);
 496     $issue = Koha::Old::Checkouts->find($issue_id) unless $issue;
 497     return $issue && $issue->borrowernumber
 498             && $user->borrowernumber == $issue->borrowernumber;
 499 }
 500
 501 =head3 _object_ownership_by_reserve_id
 502
 503 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 504 belongs to C<$user>.
 505
 506 TODO: Also compare against old_reserves
 507
 508 =cut
 509
 510 sub _object_ownership_by_reserve_id {
 511     my ($c, $user, $reserve_id) = @_;
 512
 513     my $reserve = Koha::Holds->find($reserve_id);
 514     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 515 }
 516
 517 =head3 _basic_auth
 518
 519 Internal method that performs Basic authentication.
 520
 521 =cut
 522
 523 sub _basic_auth {
 524     my ( $c, $authorization_header ) = @_;
 525
 526     my ( $type, $credentials ) = split / /, $authorization_header;
 527
 528     unless ($credentials) {
 529         Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
 530     }
 531
 532     my $decoded_credentials = decode_base64( $credentials );
 533     my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
 534
 535     unless ( checkpw_internal($user_id, $password ) ) {
 536         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
 537     }
 538
 539     my $patron = Koha::Patrons->find({ userid => $user_id });
 540     if ( $patron->password_expired ) {
 541         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Password has expired' );
 542     }
 543
 544     return $patron;
 545 }
 546
 547 =head3 _set_userenv
 548
 549     $c->_set_userenv( $patron );
 550
 551 Internal method that sets C4::Context->userenv
 552
 553 =cut
 554
 555 sub _set_userenv {
 556     my ( $c, $patron ) = @_;
 557
 558     my $passed_library_id = $c->req->headers->header('x-koha-library');
 559     my $THE_library;
 560
 561     if ( $passed_library_id ) {
 562         $THE_library = Koha::Libraries->find( $passed_library_id );
 563         Koha::Exceptions::Authorization::Unauthorized->throw(
 564             "Unauthorized attempt to set library to $passed_library_id"
 565         ) unless $THE_library and $patron->can_log_into($THE_library);
 566     }
 567     else {
 568         $THE_library = $patron->library;
 569     }
 570
 571     C4::Context->_new_userenv( $patron->borrowernumber );
 572     C4::Context->set_userenv(
 573         $patron->borrowernumber,  # number,
 574         $patron->userid,          # userid,
 575         $patron->cardnumber,      # cardnumber
 576         $patron->firstname,       # firstname
 577         $patron->surname,         # surname
 578         $THE_library->branchcode, # branch
 579         $THE_library->branchname, # branchname
 580         $patron->flags,           # flags,
 581         $patron->email,           # emailaddress
 582     );
 583
 584     return $c;
 585 }
 586
 587 1;