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::OAuth;
  32 use Koha::OAuthAccessTokens;
  33 use Koha::Old::Checkouts;
  34 use Koha::Patrons;
  35
  36 use Koha::Exceptions;
  37 use Koha::Exceptions::Authentication;
  38 use Koha::Exceptions::Authorization;
  39
  40 use MIME::Base64;
  41 use Module::Load::Conditional;
  42 use Scalar::Util qw( blessed );
  43 use Try::Tiny;
  44
  45 =head1 NAME
  46
  47 Koha::REST::V1::Auth
  48
  49 =head2 Operations
  50
  51 =head3 under
  52
  53 This subroutine is called before every request to API.
  54
  55 =cut
  56
  57 sub under {
  58     my ( $c ) = @_;
  59
  60     my $status = 0;
  61
  62     try {
  63
  64         # /api/v1/{namespace}
  65         my $namespace = $c->req->url->to_abs->path->[2] // '';
  66
  67         my $is_public = 0; # By default routes are not public
  68         my $is_plugin = 0;
  69
  70         if ( $namespace eq 'public' ) {
  71             $is_public = 1;
  72         } elsif ( $namespace eq 'contrib' ) {
  73             $is_plugin = 1;
  74         }
  75
  76         if ( $is_public
  77             and !C4::Context->preference('RESTPublicAPI') )
  78         {
  79             Koha::Exceptions::Authorization->throw(
  80                 "Configuration prevents the usage of this endpoint by unprivileged users");
  81         }
  82
  83         if ( $c->req->url->to_abs->path eq '/api/v1/oauth/token' ) {
  84             # Requesting a token shouldn't go through the API authenticaction chain
  85             $status = 1;
  86         }
  87         elsif ( $namespace eq '' or $namespace eq '.html' ) {
  88             $status = 1;
  89         }
  90         else {
  91             $status = authenticate_api_request($c, { is_public => $is_public, is_plugin => $is_plugin });
  92         }
  93
  94     } catch {
  95         unless (blessed($_)) {
  96             return $c->render(
  97                 status => 500,
  98                 json => { error => 'Something went wrong, check the logs.' }
  99             );
 100         }
 101         if ($_->isa('Koha::Exceptions::UnderMaintenance')) {
 102             return $c->render(status => 503, json => { error => $_->error });
 103         }
 104         elsif ($_->isa('Koha::Exceptions::Authentication::SessionExpired')) {
 105             return $c->render(status => 401, json => { error => $_->error });
 106         }
 107         elsif ($_->isa('Koha::Exceptions::Authentication::Required')) {
 108             return $c->render(status => 401, json => { error => $_->error });
 109         }
 110         elsif ($_->isa('Koha::Exceptions::Authentication')) {
 111             return $c->render(status => 401, json => { error => $_->error });
 112         }
 113         elsif ($_->isa('Koha::Exceptions::BadParameter')) {
 114             return $c->render(status => 400, json => $_->error );
 115         }
 116         elsif ($_->isa('Koha::Exceptions::Authorization::Unauthorized')) {
 117             return $c->render(status => 403, json => {
 118                 error => $_->error,
 119                 required_permissions => $_->required_permissions,
 120             });
 121         }
 122         elsif ($_->isa('Koha::Exceptions::Authorization')) {
 123             return $c->render(status => 403, json => { error => $_->error });
 124         }
 125         elsif ($_->isa('Koha::Exceptions')) {
 126             return $c->render(status => 500, json => { error => $_->error });
 127         }
 128         else {
 129             return $c->render(
 130                 status => 500,
 131                 json => { error => 'Something went wrong, check the logs.' }
 132             );
 133         }
 134     };
 135
 136     return $status;
 137 }
 138
 139 =head3 authenticate_api_request
 140
 141 Validates authentication and allows access if authorization is not required or
 142 if authorization is required and user has required permissions to access.
 143
 144 =cut
 145
 146 sub authenticate_api_request {
 147     my ( $c, $params ) = @_;
 148
 149     my $user;
 150
 151     # The following supports retrieval of spec with Mojolicious::Plugin::OpenAPI@1.17 and later (first one)
 152     # and older versions (second one).
 153     # TODO: remove the latter 'openapi.op_spec' if minimum version is bumped to at least 1.17.
 154     my $spec = $c->openapi->spec || $c->match->endpoint->pattern->defaults->{'openapi.op_spec'};
 155
 156     $c->stash_embed({ spec => $spec });
 157     my $cookie_auth = 0;
 158
 159     my $authorization = $spec->{'x-koha-authorization'};
 160
 161     my $authorization_header = $c->req->headers->authorization;
 162
 163     if ($authorization_header and $authorization_header =~ /^Bearer /) {
 164         # attempt to use OAuth2 authentication
 165         if ( ! Module::Load::Conditional::can_load(
 166                     modules => {'Net::OAuth2::AuthorizationServer' => undef} )) {
 167             Koha::Exceptions::Authorization::Unauthorized->throw(
 168                 error => 'Authentication failure.'
 169             );
 170         }
 171         else {
 172             require Net::OAuth2::AuthorizationServer;
 173         }
 174
 175         my $server = Net::OAuth2::AuthorizationServer->new;
 176         my $grant = $server->client_credentials_grant(Koha::OAuth::config);
 177         my ($type, $token) = split / /, $authorization_header;
 178         my ($valid_token, $error) = $grant->verify_access_token(
 179             access_token => $token,
 180         );
 181
 182         if ($valid_token) {
 183             my $patron_id = Koha::ApiKeys->find( $valid_token->{client_id} )->patron_id;
 184             $user         = Koha::Patrons->find($patron_id);
 185         }
 186         else {
 187             # If we have "Authorization: Bearer" header and oauth authentication
 188             # failed, do not try other authentication means
 189             Koha::Exceptions::Authentication::Required->throw(
 190                 error => 'Authentication failure.'
 191             );
 192         }
 193     }
 194     elsif ( $authorization_header and $authorization_header =~ /^Basic / ) {
 195         unless ( C4::Context->preference('RESTBasicAuth') ) {
 196             Koha::Exceptions::Authentication::Required->throw(
 197                 error => 'Basic authentication disabled'
 198             );
 199         }
 200         $user = $c->_basic_auth( $authorization_header );
 201         unless ( $user ) {
 202             # If we have "Authorization: Basic" header and authentication
 203             # failed, do not try other authentication means
 204             Koha::Exceptions::Authentication::Required->throw(
 205                 error => 'Authentication failure.'
 206             );
 207         }
 208     }
 209     else {
 210
 211         my $cookie = $c->cookie('CGISESSID');
 212
 213         # Mojo doesn't use %ENV the way CGI apps do
 214         # Manually pass the remote_address to check_auth_cookie
 215         my $remote_addr = $c->tx->remote_address;
 216         my ($status, $sessionID) = check_cookie_auth(
 217                                                 $cookie, undef,
 218                                                 { remote_addr => $remote_addr });
 219         if ($status eq "ok") {
 220             my $session = get_session($sessionID);
 221             $user = Koha::Patrons->find( $session->param('number') )
 222               unless $session->param('sessiontype')
 223                  and $session->param('sessiontype') eq 'anon';
 224             $cookie_auth = 1;
 225         }
 226         elsif ($status eq "maintenance") {
 227             Koha::Exceptions::UnderMaintenance->throw(
 228                 error => 'System is under maintenance.'
 229             );
 230         }
 231         elsif ($status eq "expired" and $authorization) {
 232             Koha::Exceptions::Authentication::SessionExpired->throw(
 233                 error => 'Session has been expired.'
 234             );
 235         }
 236         elsif ($status eq "failed" and $authorization) {
 237             Koha::Exceptions::Authentication::Required->throw(
 238                 error => 'Authentication failure.'
 239             );
 240         }
 241         elsif ($authorization) {
 242             Koha::Exceptions::Authentication->throw(
 243                 error => 'Unexpected authentication status.'
 244             );
 245         }
 246     }
 247
 248     $c->stash('koha.user' => $user);
 249     C4::Context->interface('api');
 250
 251     if ( $user and !$cookie_auth ) { # cookie-auth sets this and more, don't mess with that
 252         $c->_set_userenv( $user );
 253     }
 254
 255     if ( !$authorization and
 256          ( $params->{is_public} and
 257           ( C4::Context->preference('RESTPublicAnonymousRequests') or
 258             $user) or $params->{is_plugin} ) ) {
 259         # We do not need any authorization
 260         # Check the parameters
 261         validate_query_parameters( $c, $spec );
 262         return 1;
 263     }
 264     else {
 265         # We are required authorizarion, there needs
 266         # to be an identified user
 267         Koha::Exceptions::Authentication::Required->throw(
 268             error => 'Authentication failure.' )
 269           unless $user;
 270     }
 271
 272
 273     my $permissions = $authorization->{'permissions'};
 274     # Check if the user is authorized
 275     if ( ( defined($permissions) and haspermission($user->userid, $permissions) )
 276         or allow_owner($c, $authorization, $user)
 277         or allow_guarantor($c, $authorization, $user) ) {
 278
 279         validate_query_parameters( $c, $spec );
 280
 281         # Everything is ok
 282         return 1;
 283     }
 284
 285     Koha::Exceptions::Authorization::Unauthorized->throw(
 286         error => "Authorization failure. Missing required permission(s).",
 287         required_permissions => $permissions,
 288     );
 289 }
 290
 291 =head3 validate_query_parameters
 292
 293 Validates the query parameters against the spec.
 294
 295 =cut
 296
 297 sub validate_query_parameters {
 298     my ( $c, $action_spec ) = @_;
 299
 300     # Check for malformed query parameters
 301     my @errors;
 302     my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
 303     my $existing_params = $c->req->query_params->to_hash;
 304     for my $param ( keys %{$existing_params} ) {
 305         push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
 306     }
 307
 308     Koha::Exceptions::BadParameter->throw(
 309         error => \@errors
 310     ) if @errors;
 311 }
 312
 313
 314 =head3 allow_owner
 315
 316 Allows access to object for its owner.
 317
 318 There are endpoints that should allow access for the object owner even if they
 319 do not have the required permission, e.g. access an own reserve. This can be
 320 achieved by defining the operation as follows:
 321
 322 "/holds/{reserve_id}": {
 323     "get": {
 324         ...,
 325         "x-koha-authorization": {
 326             "allow-owner": true,
 327             "permissions": {
 328                 "borrowers": "1"
 329             }
 330         }
 331     }
 332 }
 333
 334 =cut
 335
 336 sub allow_owner {
 337     my ($c, $authorization, $user) = @_;
 338
 339     return unless $authorization->{'allow-owner'};
 340
 341     return check_object_ownership($c, $user) if $user and $c;
 342 }
 343
 344 =head3 allow_guarantor
 345
 346 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 347 guarantees.
 348
 349 =cut
 350
 351 sub allow_guarantor {
 352     my ($c, $authorization, $user) = @_;
 353
 354     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 355         return;
 356     }
 357
 358     my $guarantees = $user->guarantee_relationships->guarantees->as_list;
 359     foreach my $guarantee (@{$guarantees}) {
 360         return 1 if check_object_ownership($c, $guarantee);
 361     }
 362 }
 363
 364 =head3 check_object_ownership
 365
 366 Determines ownership of an object from request parameters.
 367
 368 As introducing an endpoint that allows access for object's owner; if the
 369 parameter that will be used to determine ownership is not already inside
 370 $parameters, add a new subroutine that checks the ownership and extend
 371 $parameters to contain a key with parameter_name and a value of a subref to
 372 the subroutine that you created.
 373
 374 =cut
 375
 376 sub check_object_ownership {
 377     my ($c, $user) = @_;
 378
 379     return if not $c or not $user;
 380
 381     my $parameters = {
 382         accountlines_id => \&_object_ownership_by_accountlines_id,
 383         borrowernumber  => \&_object_ownership_by_patron_id,
 384         patron_id       => \&_object_ownership_by_patron_id,
 385         checkout_id     => \&_object_ownership_by_checkout_id,
 386         reserve_id      => \&_object_ownership_by_reserve_id,
 387     };
 388
 389     foreach my $param ( keys %{ $parameters } ) {
 390         my $check_ownership = $parameters->{$param};
 391         if ($c->stash($param)) {
 392             return &$check_ownership($c, $user, $c->stash($param));
 393         }
 394         elsif ($c->param($param)) {
 395             return &$check_ownership($c, $user, $c->param($param));
 396         }
 397         elsif ($c->match->stack->[-1]->{$param}) {
 398             return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
 399         }
 400         elsif ($c->req->json && $c->req->json->{$param}) {
 401             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 402         }
 403     }
 404 }
 405
 406 =head3 _object_ownership_by_accountlines_id
 407
 408 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 409 belongs to C<$user>.
 410
 411 =cut
 412
 413 sub _object_ownership_by_accountlines_id {
 414     my ($c, $user, $accountlines_id) = @_;
 415
 416     my $accountline = Koha::Account::Lines->find($accountlines_id);
 417     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 418 }
 419
 420 =head3 _object_ownership_by_borrowernumber
 421
 422 Compares C<$borrowernumber> to currently logged in C<$user>.
 423
 424 =cut
 425
 426 sub _object_ownership_by_patron_id {
 427     my ($c, $user, $patron_id) = @_;
 428
 429     return $user->borrowernumber == $patron_id;
 430 }
 431
 432 =head3 _object_ownership_by_checkout_id
 433
 434 First, attempts to find a Koha::Checkout-object by C<$issue_id>. If we find one,
 435 compare its borrowernumber to currently logged in C<$user>. However, if an issue
 436 is not found, attempt to find a Koha::Old::Checkout-object instead and compare its
 437 borrowernumber to currently logged in C<$user>.
 438
 439 =cut
 440
 441 sub _object_ownership_by_checkout_id {
 442     my ($c, $user, $issue_id) = @_;
 443
 444     my $issue = Koha::Checkouts->find($issue_id);
 445     $issue = Koha::Old::Checkouts->find($issue_id) unless $issue;
 446     return $issue && $issue->borrowernumber
 447             && $user->borrowernumber == $issue->borrowernumber;
 448 }
 449
 450 =head3 _object_ownership_by_reserve_id
 451
 452 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 453 belongs to C<$user>.
 454
 455 TODO: Also compare against old_reserves
 456
 457 =cut
 458
 459 sub _object_ownership_by_reserve_id {
 460     my ($c, $user, $reserve_id) = @_;
 461
 462     my $reserve = Koha::Holds->find($reserve_id);
 463     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 464 }
 465
 466 =head3 _basic_auth
 467
 468 Internal method that performs Basic authentication.
 469
 470 =cut
 471
 472 sub _basic_auth {
 473     my ( $c, $authorization_header ) = @_;
 474
 475     my ( $type, $credentials ) = split / /, $authorization_header;
 476
 477     unless ($credentials) {
 478         Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
 479     }
 480
 481     my $decoded_credentials = decode_base64( $credentials );
 482     my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
 483
 484     my $dbh = C4::Context->dbh;
 485     unless ( checkpw_internal($dbh, $user_id, $password ) ) {
 486         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
 487     }
 488
 489     return Koha::Patrons->find({ userid => $user_id });
 490 }
 491
 492 =head3 _set_userenv
 493
 494     $c->_set_userenv( $patron );
 495
 496 Internal method that sets C4::Context->userenv
 497
 498 =cut
 499
 500 sub _set_userenv {
 501     my ( $c, $patron ) = @_;
 502
 503     my $library = $patron->library;
 504
 505     C4::Context->_new_userenv( $patron->borrowernumber );
 506     C4::Context->set_userenv(
 507         $patron->borrowernumber, # number,
 508         $patron->userid,         # userid,
 509         $patron->cardnumber,     # cardnumber
 510         $patron->firstname,      # firstname
 511         $patron->surname,        # surname
 512         $library->branchcode,    # branch
 513         $library->branchname,    # branchname
 514         $patron->flags,          # flags,
 515         $patron->email,          # emailaddress
 516     );
 517
 518     return $c;
 519 }
 520
 521 1;