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