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