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 under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 3 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along
  17 # with Koha; if not, write to the Free Software Foundation, Inc.,
  18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19
  20 use Mojo::Base 'Mojolicious::Controller';
  21
  22 use C4::Auth qw( check_cookie_auth checkpw_internal get_session haspermission );
  23 use C4::Context;
  24
  25 use Koha::ApiKeys;
  26 use Koha::Account::Lines;
  27 use Koha::Checkouts;
  28 use Koha::Holds;
  29 use Koha::OAuth;
  30 use Koha::OAuthAccessTokens;
  31 use Koha::Old::Checkouts;
  32 use Koha::Patrons;
  33
  34 use Koha::Exceptions;
  35 use Koha::Exceptions::Authentication;
  36 use Koha::Exceptions::Authorization;
  37
  38 use MIME::Base64;
  39 use Module::Load::Conditional;
  40 use Scalar::Util qw( blessed );
  41 use Try::Tiny;
  42
  43 =head1 NAME
  44
  45 Koha::REST::V1::Auth
  46
  47 =head2 Operations
  48
  49 =head3 under
  50
  51 This subroutine is called before every request to API.
  52
  53 =cut
  54
  55 sub under {
  56     my $c = shift->openapi->valid_input or return;;
  57
  58     my $status = 0;
  59
  60     try {
  61
  62         # /api/v1/{namespace}
  63         my $namespace = $c->req->url->to_abs->path->[2];
  64
  65         if ( $namespace eq 'public'
  66             and !C4::Context->preference('RESTPublicAPI') )
  67         {
  68             Koha::Exceptions::Authorization->throw(
  69                 "Configuration prevents the usage of this endpoint by unprivileged users");
  70         }
  71
  72         $status = authenticate_api_request($c);
  73
  74     } catch {
  75         unless (blessed($_)) {
  76             return $c->render(
  77                 status => 500,
  78                 json => { error => 'Something went wrong, check the logs.' }
  79             );
  80         }
  81         if ($_->isa('Koha::Exceptions::UnderMaintenance')) {
  82             return $c->render(status => 503, json => { error => $_->error });
  83         }
  84         elsif ($_->isa('Koha::Exceptions::Authentication::SessionExpired')) {
  85             return $c->render(status => 401, json => { error => $_->error });
  86         }
  87         elsif ($_->isa('Koha::Exceptions::Authentication::Required')) {
  88             return $c->render(status => 401, json => { error => $_->error });
  89         }
  90         elsif ($_->isa('Koha::Exceptions::Authentication')) {
  91             return $c->render(status => 401, json => { error => $_->error });
  92         }
  93         elsif ($_->isa('Koha::Exceptions::BadParameter')) {
  94             return $c->render(status => 400, json => $_->error );
  95         }
  96         elsif ($_->isa('Koha::Exceptions::Authorization::Unauthorized')) {
  97             return $c->render(status => 403, json => {
  98                 error => $_->error,
  99                 required_permissions => $_->required_permissions,
 100             });
 101         }
 102         elsif ($_->isa('Koha::Exceptions::Authorization')) {
 103             return $c->render(status => 403, json => { error => $_->error });
 104         }
 105         elsif ($_->isa('Koha::Exceptions')) {
 106             return $c->render(status => 500, json => { error => $_->error });
 107         }
 108         else {
 109             return $c->render(
 110                 status => 500,
 111                 json => { error => 'Something went wrong, check the logs.' }
 112             );
 113         }
 114     };
 115
 116     return $status;
 117 }
 118
 119 =head3 authenticate_api_request
 120
 121 Validates authentication and allows access if authorization is not required or
 122 if authorization is required and user has required permissions to access.
 123
 124 =cut
 125
 126 sub authenticate_api_request {
 127     my ( $c ) = @_;
 128
 129     my $user;
 130
 131     my $spec = $c->match->endpoint->pattern->defaults->{'openapi.op_spec'};
 132     my $authorization = $spec->{'x-koha-authorization'};
 133
 134     my $authorization_header = $c->req->headers->authorization;
 135
 136     if ($authorization_header and $authorization_header =~ /^Bearer /) {
 137         # attempt to use OAuth2 authentication
 138         if ( ! Module::Load::Conditional::can_load(
 139                     modules => {'Net::OAuth2::AuthorizationServer' => undef} )) {
 140             Koha::Exceptions::Authorization::Unauthorized->throw(
 141                 error => 'Authentication failure.'
 142             );
 143         }
 144         else {
 145             require Net::OAuth2::AuthorizationServer;
 146         }
 147
 148         my $server = Net::OAuth2::AuthorizationServer->new;
 149         my $grant = $server->client_credentials_grant(Koha::OAuth::config);
 150         my ($type, $token) = split / /, $authorization_header;
 151         my ($valid_token, $error) = $grant->verify_access_token(
 152             access_token => $token,
 153         );
 154
 155         if ($valid_token) {
 156             my $patron_id = Koha::ApiKeys->find( $valid_token->{client_id} )->patron_id;
 157             $user         = Koha::Patrons->find($patron_id);
 158         }
 159         else {
 160             # If we have "Authorization: Bearer" header and oauth authentication
 161             # failed, do not try other authentication means
 162             Koha::Exceptions::Authentication::Required->throw(
 163                 error => 'Authentication failure.'
 164             );
 165         }
 166     }
 167     elsif ( $authorization_header and $authorization_header =~ /^Basic / ) {
 168         unless ( C4::Context->preference('RESTBasicAuth') ) {
 169             Koha::Exceptions::Authentication::Required->throw(
 170                 error => 'Basic authentication disabled'
 171             );
 172         }
 173         $user = $c->_basic_auth( $authorization_header );
 174         unless ( $user ) {
 175             # If we have "Authorization: Basic" header and authentication
 176             # failed, do not try other authentication means
 177             Koha::Exceptions::Authentication::Required->throw(
 178                 error => 'Authentication failure.'
 179             );
 180         }
 181     }
 182     else {
 183
 184         my $cookie = $c->cookie('CGISESSID');
 185
 186         # Mojo doesn't use %ENV the way CGI apps do
 187         # Manually pass the remote_address to check_auth_cookie
 188         my $remote_addr = $c->tx->remote_address;
 189         my ($status, $sessionID) = check_cookie_auth(
 190                                                 $cookie, undef,
 191                                                 { remote_addr => $remote_addr });
 192         if ($status eq "ok") {
 193             my $session = get_session($sessionID);
 194             $user = Koha::Patrons->find($session->param('number'));
 195             # $c->stash('koha.user' => $user);
 196         }
 197         elsif ($status eq "maintenance") {
 198             Koha::Exceptions::UnderMaintenance->throw(
 199                 error => 'System is under maintenance.'
 200             );
 201         }
 202         elsif ($status eq "expired" and $authorization) {
 203             Koha::Exceptions::Authentication::SessionExpired->throw(
 204                 error => 'Session has been expired.'
 205             );
 206         }
 207         elsif ($status eq "failed" and $authorization) {
 208             Koha::Exceptions::Authentication::Required->throw(
 209                 error => 'Authentication failure.'
 210             );
 211         }
 212         elsif ($authorization) {
 213             Koha::Exceptions::Authentication->throw(
 214                 error => 'Unexpected authentication status.'
 215             );
 216         }
 217     }
 218
 219     $c->stash('koha.user' => $user);
 220
 221     # We do not need any authorization
 222     unless ($authorization) {
 223         # Check the parameters
 224         validate_query_parameters( $c, $spec );
 225         return 1;
 226     }
 227
 228     my $permissions = $authorization->{'permissions'};
 229     # Check if the user is authorized
 230     if ( haspermission($user->userid, $permissions)
 231         or allow_owner($c, $authorization, $user)
 232         or allow_guarantor($c, $authorization, $user) ) {
 233
 234         validate_query_parameters( $c, $spec );
 235
 236         # Everything is ok
 237         return 1;
 238     }
 239
 240     Koha::Exceptions::Authorization::Unauthorized->throw(
 241         error => "Authorization failure. Missing required permission(s).",
 242         required_permissions => $permissions,
 243     );
 244 }
 245
 246 =head3 validate_query_parameters
 247
 248 Validates the query parameters against the spec.
 249
 250 =cut
 251
 252 sub validate_query_parameters {
 253     my ( $c, $action_spec ) = @_;
 254
 255     # Check for malformed query parameters
 256     my @errors;
 257     my %valid_parameters = map { ( $_->{in} eq 'query' ) ? ( $_->{name} => 1 ) : () } @{ $action_spec->{parameters} };
 258     my $existing_params = $c->req->query_params->to_hash;
 259     for my $param ( keys %{$existing_params} ) {
 260         push @errors, { path => "/query/" . $param, message => 'Malformed query string' } unless exists $valid_parameters{$param};
 261     }
 262
 263     Koha::Exceptions::BadParameter->throw(
 264         error => \@errors
 265     ) if @errors;
 266 }
 267
 268
 269 =head3 allow_owner
 270
 271 Allows access to object for its owner.
 272
 273 There are endpoints that should allow access for the object owner even if they
 274 do not have the required permission, e.g. access an own reserve. This can be
 275 achieved by defining the operation as follows:
 276
 277 "/holds/{reserve_id}": {
 278     "get": {
 279         ...,
 280         "x-koha-authorization": {
 281             "allow-owner": true,
 282             "permissions": {
 283                 "borrowers": "1"
 284             }
 285         }
 286     }
 287 }
 288
 289 =cut
 290
 291 sub allow_owner {
 292     my ($c, $authorization, $user) = @_;
 293
 294     return unless $authorization->{'allow-owner'};
 295
 296     return check_object_ownership($c, $user) if $user and $c;
 297 }
 298
 299 =head3 allow_guarantor
 300
 301 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 302 guarantees.
 303
 304 =cut
 305
 306 sub allow_guarantor {
 307     my ($c, $authorization, $user) = @_;
 308
 309     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 310         return;
 311     }
 312
 313     my $guarantees = $user->guarantees->as_list;
 314     foreach my $guarantee (@{$guarantees}) {
 315         return 1 if check_object_ownership($c, $guarantee);
 316     }
 317 }
 318
 319 =head3 check_object_ownership
 320
 321 Determines ownership of an object from request parameters.
 322
 323 As introducing an endpoint that allows access for object's owner; if the
 324 parameter that will be used to determine ownership is not already inside
 325 $parameters, add a new subroutine that checks the ownership and extend
 326 $parameters to contain a key with parameter_name and a value of a subref to
 327 the subroutine that you created.
 328
 329 =cut
 330
 331 sub check_object_ownership {
 332     my ($c, $user) = @_;
 333
 334     return if not $c or not $user;
 335
 336     my $parameters = {
 337         accountlines_id => \&_object_ownership_by_accountlines_id,
 338         borrowernumber  => \&_object_ownership_by_patron_id,
 339         patron_id       => \&_object_ownership_by_patron_id,
 340         checkout_id     => \&_object_ownership_by_checkout_id,
 341         reserve_id      => \&_object_ownership_by_reserve_id,
 342     };
 343
 344     foreach my $param ( keys %{ $parameters } ) {
 345         my $check_ownership = $parameters->{$param};
 346         if ($c->stash($param)) {
 347             return &$check_ownership($c, $user, $c->stash($param));
 348         }
 349         elsif ($c->param($param)) {
 350             return &$check_ownership($c, $user, $c->param($param));
 351         }
 352         elsif ($c->match->stack->[-1]->{$param}) {
 353             return &$check_ownership($c, $user, $c->match->stack->[-1]->{$param});
 354         }
 355         elsif ($c->req->json && $c->req->json->{$param}) {
 356             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 357         }
 358     }
 359 }
 360
 361 =head3 _object_ownership_by_accountlines_id
 362
 363 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 364 belongs to C<$user>.
 365
 366 =cut
 367
 368 sub _object_ownership_by_accountlines_id {
 369     my ($c, $user, $accountlines_id) = @_;
 370
 371     my $accountline = Koha::Account::Lines->find($accountlines_id);
 372     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 373 }
 374
 375 =head3 _object_ownership_by_borrowernumber
 376
 377 Compares C<$borrowernumber> to currently logged in C<$user>.
 378
 379 =cut
 380
 381 sub _object_ownership_by_patron_id {
 382     my ($c, $user, $patron_id) = @_;
 383
 384     return $user->borrowernumber == $patron_id;
 385 }
 386
 387 =head3 _object_ownership_by_checkout_id
 388
 389 First, attempts to find a Koha::Checkout-object by C<$issue_id>. If we find one,
 390 compare its borrowernumber to currently logged in C<$user>. However, if an issue
 391 is not found, attempt to find a Koha::Old::Checkout-object instead and compare its
 392 borrowernumber to currently logged in C<$user>.
 393
 394 =cut
 395
 396 sub _object_ownership_by_checkout_id {
 397     my ($c, $user, $issue_id) = @_;
 398
 399     my $issue = Koha::Checkouts->find($issue_id);
 400     $issue = Koha::Old::Checkouts->find($issue_id) unless $issue;
 401     return $issue && $issue->borrowernumber
 402             && $user->borrowernumber == $issue->borrowernumber;
 403 }
 404
 405 =head3 _object_ownership_by_reserve_id
 406
 407 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 408 belongs to C<$user>.
 409
 410 TODO: Also compare against old_reserves
 411
 412 =cut
 413
 414 sub _object_ownership_by_reserve_id {
 415     my ($c, $user, $reserve_id) = @_;
 416
 417     my $reserve = Koha::Holds->find($reserve_id);
 418     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 419 }
 420
 421 =head3 _basic_auth
 422
 423 Internal method that performs Basic authentication.
 424
 425 =cut
 426
 427 sub _basic_auth {
 428     my ( $c, $authorization_header ) = @_;
 429
 430     my ( $type, $credentials ) = split / /, $authorization_header;
 431
 432     unless ($credentials) {
 433         Koha::Exceptions::Authentication::Required->throw( error => 'Authentication failure.' );
 434     }
 435
 436     my $decoded_credentials = decode_base64( $credentials );
 437     my ( $user_id, $password ) = split( /:/, $decoded_credentials, 2 );
 438
 439     my $dbh = C4::Context->dbh;
 440     unless ( checkpw_internal($dbh, $user_id, $password ) ) {
 441         Koha::Exceptions::Authorization::Unauthorized->throw( error => 'Invalid password' );
 442     }
 443
 444     return Koha::Patrons->find({ userid => $user_id });
 445 }
 446
 447 1;