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