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