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();
 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         } else {
 240             if ($status eq "ok") {
 241                 $user = Koha::Patrons->find( $session->param('number') );
 242                 $cookie_auth = 1;
 243             }
 244             elsif ($status eq "anon") {
 245                 $cookie_auth = 1;
 246             }
 247             elsif ($status eq "additional-auth-needed") {
 248             }
 249             elsif ($status eq "maintenance") {
 250                 Koha::Exceptions::UnderMaintenance->throw(
 251                     error => 'System is under maintenance.'
 252                 );
 253             }
 254             elsif ($status eq "expired" and $authorization) {
 255                 Koha::Exceptions::Authentication::SessionExpired->throw(
 256                     error => 'Session has been expired.'
 257                 );
 258             }
 259             elsif ($status eq "failed" and $authorization) {
 260                 Koha::Exceptions::Authentication::Required->throw(
 261                     error => 'Authentication failure.'
 262                 );
 263             }
 264             elsif ($authorization) {
 265                 Koha::Exceptions::Authentication->throw(
 266                     error => 'Unexpected authentication status.'
 267                 );
 268             }
 269         }
 270     }
 271
 272     $c->stash('koha.user' => $user);
 273     C4::Context->interface('api');
 274
 275     if ( $user and !$cookie_auth ) { # cookie-auth sets this and more, don't mess with that
 276         $c->_set_userenv( $user );
 277     }
 278
 279     if ( !$authorization and
 280          ( $params->{is_public} and
 281           ( C4::Context->preference('RESTPublicAnonymousRequests') or
 282             $user) or $params->{is_plugin} )
 283     ) {
 284         # We do not need any authorization
 285         # Check the parameters
 286         validate_query_parameters( $c, $spec );
 287         return 1;
 288     }
 289     else {
 290         # We are required authorization, there needs
 291         # to be an identified user
 292         Koha::Exceptions::Authentication::Required->throw(
 293             error => 'Authentication failure.' )
 294           unless $user;
 295     }
 296
 297
 298     my $permissions = $authorization->{'permissions'};
 299     # Check if the user is authorized
 300     if ( ( defined($permissions) and haspermission($user->userid, $permissions) )
 301         or allow_owner($c, $authorization, $user)
 302         or allow_guarantor($c, $authorization, $user) ) {
 303
 304         validate_query_parameters( $c, $spec );
 305
 306         # Everything is ok
 307         return 1;
 308     }
 309
 310     Koha::Exceptions::Authorization::Unauthorized->throw(
 311         error => "Authorization failure. Missing required permission(s).",
 312         required_permissions => $permissions,
 313     );
 314 }
 315
 316 =head3 validate_query_parameters
 317
 318 Validates the query parameters against the spec.
 319
 320 =cut
 321
 322 sub validate_query_parameters {
 323     my ( $c, $action_spec ) = @_;
 324
 325     # Check for malformed query parameters
 326     my @errors;
 327     my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
 328     my $existing_params = $c->req->query_params->to_hash;
 329     for my $param ( keys %{$existing_params} ) {
 330         push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
 331     }
 332
 333     Koha::Exceptions::BadParameter->throw(
 334         error => \@errors
 335     ) if @errors;
 336 }
 337
 338 =head3 allow_owner
 339
 340 Allows access to object for its owner.
 341
 342 There are endpoints that should allow access for the object owner even if they
 343 do not have the required permission, e.g. access an own reserve. This can be
 344 achieved by defining the operation as follows:
 345
 346 "/holds/{reserve_id}": {
 347     "get": {
 348         ...,
 349         "x-koha-authorization": {
 350             "allow-owner": true,
 351             "permissions": {
 352                 "borrowers": "1"
 353             }
 354         }
 355     }
 356 }
 357
 358 =cut
 359
 360 sub allow_owner {
 361     my ($c, $authorization, $user) = @_;
 362
 363     return unless $authorization->{'allow-owner'};
 364
 365     return check_object_ownership($c, $user) if $user and $c;
 366 }
 367
 368 =head3 allow_guarantor
 369
 370 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 371 guarantees.
 372
 373 =cut
 374
 375 sub allow_guarantor {
 376     my ($c, $authorization, $user) = @_;
 377
 378     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 379         return;
 380     }
 381
 382     my $guarantees = $user->guarantee_relationships->guarantees->as_list;
 383     foreach my $guarantee (@{$guarantees}) {
 384         return 1 if check_object_ownership($c, $guarantee);
 385     }
 386 }
 387
 388 =head3 check_object_ownership
 389
 390 Determines ownership of an object from request parameters.
 391
 392 As introducing an endpoint that allows access for object's owner; if the
 393 parameter that will be used to determine ownership is not already inside
 394 $parameters, add a new subroutine that checks the ownership and extend
 395 $parameters to contain a key with parameter_name and a value of a subref to
 396 the subroutine that you created.
 397
 398 =cut
 399
 400 sub check_object_ownership {
 401     my ($c, $user) = @_;
 402
 403     return if not $c or not $user;
 404
 405     my $parameters = {
 406         accountlines_id => \&_object_ownership_by_accountlines_id,
 407         borrowernumber  => \&_object_ownership_by_patron_id,
 408         patron_id       => \&_object_ownership_by_patron_id,
 409         checkout_id     => \&_object_ownership_by_checkout_id,
 410         reserve_id      => \&_object_ownership_by_reserve_id,
 411     };
 412
 413     foreach my $param ( keys %{ $parameters } ) {
 414         my $check_ownership = $parameters->{$param};
 415         if ($c->stash($param)) {
 416             return &$check_ownership($c, $user, $c->stash($param));
 417         }
 418         elsif ($c->param($param)) {
 419             return &$check_ownership($c, $user, $c->param($param));
 420         }
 421         elsif ($c->match->stack->[-1]->{$param}) {
 422             return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
 423         }
 424         elsif ($c->req->json && $c->req->json->{$param}) {
 425             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 426         }
 427     }
 428 }
 429
 430 =head3 _object_ownership_by_accountlines_id
 431
 432 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 433 belongs to C<$user>.
 434
 435 =cut
 436
 437 sub _object_ownership_by_accountlines_id {
 438     my ($c, $user, $accountlines_id) = @_;
 439
 440     my $accountline = Koha::Account::Lines->find($accountlines_id);
 441     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 442 }
 443
 444 =head3 _object_ownership_by_borrowernumber
 445
 446 Compares C<$borrowernumber> to currently logged in C<$user>.
 447
 448 =cut
 449
 450 sub _object_ownership_by_patron_id {
 451     my ($c, $user, $patron_id) = @_;
 452
 453     return $user->borrowernumber == $patron_id;
 454 }
 455
 456 =head3 _object_ownership_by_checkout_id
 457
 458 First, attempts to find a Koha::Checkout-object by C<$issue_id>. If we find one,
 459 compare its borrowernumber to currently logged in C<$user>. However, if an issue
 460 is not found, attempt to find a Koha::Old::Checkout-object instead and compare its
 461 borrowernumber to currently logged in C<$user>.
 462
 463 =cut
 464
 465 sub _object_ownership_by_checkout_id {
 466     my ($c, $user, $issue_id) = @_;
 467
 468     my $issue = Koha::Checkouts->find($issue_id);
 469     $issue = Koha::Old::Checkouts->find($issue_id) unless $issue;
 470     return $issue && $issue->borrowernumber
 471             && $user->borrowernumber == $issue->borrowernumber;
 472 }
 473
 474 =head3 _object_ownership_by_reserve_id
 475
 476 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 477 belongs to C<$user>.
 478
 479 TODO: Also compare against old_reserves
 480
 481 =cut
 482
 483 sub _object_ownership_by_reserve_id {
 484     my ($c, $user, $reserve_id) = @_;
 485
 486     my $reserve = Koha::Holds->find($reserve_id);
 487     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 488 }
 489
 490 =head3 _basic_auth
 491
 492 Internal method that performs Basic authentication.
 493
 494 =cut
 495
 496 sub _basic_auth {
 497     my ( $c, $authorization_header ) = @_;
 498
 499     my ( $type, $credentials ) = split / /, $authorization_header;
 500
 501     unless ($credentials) {
 502         Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
 503     }
 504
 505     my $decoded_credentials = decode_base64( $credentials );
 506     my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
 507
 508     my $dbh = C4::Context->dbh;
 509     unless ( checkpw_internal($dbh, $user_id, $password ) ) {
 510         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
 511     }
 512
 513     my $patron = Koha::Patrons->find({ userid => $user_id });
 514     if ( $patron->password_expired ) {
 515         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Password has expired' );
 516     }
 517
 518     return $patron;
 519 }
 520
 521 =head3 _set_userenv
 522
 523     $c->_set_userenv( $patron );
 524
 525 Internal method that sets C4::Context->userenv
 526
 527 =cut
 528
 529 sub _set_userenv {
 530     my ( $c, $patron ) = @_;
 531
 532     my $passed_library_id = $c->req->headers->header('x-koha-library');
 533     my $THE_library;
 534
 535     if ( $passed_library_id ) {
 536         $THE_library = Koha::Libraries->find( $passed_library_id );
 537         Koha::Exceptions::Authorization::Unauthorized->throw(
 538             "Unauthorized attempt to set library to $passed_library_id"
 539         ) unless $THE_library and $patron->can_log_into($THE_library);
 540     }
 541     else {
 542         $THE_library = $patron->library;
 543     }
 544
 545     C4::Context->_new_userenv( $patron->borrowernumber );
 546     C4::Context->set_userenv(
 547         $patron->borrowernumber,  # number,
 548         $patron->userid,          # userid,
 549         $patron->cardnumber,      # cardnumber
 550         $patron->firstname,       # firstname
 551         $patron->surname,         # surname
 552         $THE_library->branchcode, # branch
 553         $THE_library->branchname, # branchname
 554         $patron->flags,           # flags,
 555         $patron->email,           # emailaddress
 556     );
 557
 558     return $c;
 559 }
 560
 561 1;