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         C4::Context->_new_userenv( $user->borrowernumber );
 253         C4::Context->set_userenv( $user->borrowernumber );
 254     }
 255
 256     if ( !$authorization and
 257          ( $params->{is_public} and
 258           ( C4::Context->preference('RESTPublicAnonymousRequests') or
 259             $user) ) or $params->{is_plugin} ) {
 260         # We do not need any authorization
 261         # Check the parameters
 262         validate_query_parameters( $c, $spec );
 263         return 1;
 264     }
 265     else {
 266         # We are required authorizarion, there needs
 267         # to be an identified user
 268         Koha::Exceptions::Authentication::Required->throw(
 269             error => 'Authentication failure.' )
 270           unless $user;
 271     }
 272
 273
 274     my $permissions = $authorization->{'permissions'};
 275     # Check if the user is authorized
 276     if ( ( defined($permissions) and haspermission($user->userid, $permissions) )
 277         or allow_owner($c, $authorization, $user)
 278         or allow_guarantor($c, $authorization, $user) ) {
 279
 280         validate_query_parameters( $c, $spec );
 281
 282         # Everything is ok
 283         return 1;
 284     }
 285
 286     Koha::Exceptions::Authorization::Unauthorized->throw(
 287         error => "Authorization failure. Missing required permission(s).",
 288         required_permissions => $permissions,
 289     );
 290 }
 291
 292 =head3 validate_query_parameters
 293
 294 Validates the query parameters against the spec.
 295
 296 =cut
 297
 298 sub validate_query_parameters {
 299     my ( $c, $action_spec ) = @_;
 300
 301     # Check for malformed query parameters
 302     my @errors;
 303     my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
 304     my $existing_params = $c->req->query_params->to_hash;
 305     for my $param ( keys %{$existing_params} ) {
 306         push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
 307     }
 308
 309     Koha::Exceptions::BadParameter->throw(
 310         error => \@errors
 311     ) if @errors;
 312 }
 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 1;