1 package Koha::REST::V1;
3 # This file is part of Koha.
5 # Koha is free software; you can redistribute it and/or modify it under the
6 # terms of the GNU General Public License as published by the Free Software
7 # Foundation; either version 3 of the License, or (at your option) any later
10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12 # A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14 # You should have received a copy of the GNU General Public License along
15 # with Koha; if not, write to the Free Software Foundation, Inc.,
16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 use Mojo::Base 'Mojolicious';
21 use C4::Auth qw( check_cookie_auth get_session haspermission );
23 use Koha::Account::Lines;
32 # Force charset=utf8 in Content-Type header for JSON responses
33 $self->types->type(json => 'application/json; charset=utf8');
35 my $secret_passphrase = C4::Context->config('api_secret_passphrase');
36 if ($secret_passphrase) {
37 $self->secrets([$secret_passphrase]);
40 $self->plugin(Swagger2 => {
41 url => $self->home->rel_file("api/v1/swagger/swagger.min.json"),
45 =head3 authenticate_api_request
47 Validates authentication and allows access if authorization is not required or
48 if authorization is required and user has required permissions to access.
50 This subroutine is called before every request to API.
54 sub authenticate_api_request {
55 my ($next, $c, $action_spec) = @_;
58 my $cookie = $c->cookie('CGISESSID');
59 # Mojo doesn't use %ENV the way CGI apps do
60 # Manually pass the remote_address to check_auth_cookie
61 my $remote_addr = $c->tx->remote_address;
62 my ($status, $sessionID) = check_cookie_auth(
64 { remote_addr => $remote_addr });
65 if ($status eq "ok") {
66 $session = get_session($sessionID);
67 $user = Koha::Patrons->find($session->param('number'));
68 $c->stash('koha.user' => $user);
71 return $c->render_swagger(
72 { error => "Authentication failure." },
75 ) if $cookie and $action_spec->{'x-koha-authorization'};
78 return $next->($c) unless $action_spec->{'x-koha-authorization'};
80 return $c->render_swagger({ error => "Authentication required." },{},401);
83 my $authorization = $action_spec->{'x-koha-authorization'};
84 return $next->($c) if allow_owner($c, $authorization, $user);
85 return $next->($c) if allow_guarantor($c, $authorization, $user);
87 my $permissions = $authorization->{'permissions'};
88 return $next->($c) if C4::Auth::haspermission($user->userid, $permissions);
89 return $c->render_swagger(
90 { error => "Authorization failure. Missing required permission(s).",
91 required_permissions => $permissions },
99 Allows access to object for its owner.
101 There are endpoints that should allow access for the object owner even if they
102 do not have the required permission, e.g. access an own reserve. This can be
103 achieved by defining the operation as follows:
105 "/holds/{reserve_id}": {
108 "x-koha-authorization": {
120 my ($c, $authorization, $user) = @_;
122 return unless $authorization->{'allow-owner'};
124 return check_object_ownership($c, $user) if $user and $c;
127 =head3 allow_guarantor
129 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
134 sub allow_guarantor {
135 my ($c, $authorization, $user) = @_;
137 if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
141 my $guarantees = $user->guarantees->as_list;
142 foreach my $guarantee (@{$guarantees}) {
143 return 1 if check_object_ownership($c, $guarantee);
147 =head3 check_object_ownership
149 Determines ownership of an object from request parameters.
151 As introducing an endpoint that allows access for object's owner; if the
152 parameter that will be used to determine ownership is not already inside
153 $parameters, add a new subroutine that checks the ownership and extend
154 $parameters to contain a key with parameter_name and a value of a subref to
155 the subroutine that you created.
159 sub check_object_ownership {
162 return if not $c or not $user;
165 accountlines_id => \&_object_ownership_by_accountlines_id,
166 borrowernumber => \&_object_ownership_by_borrowernumber,
167 checkout_id => \&_object_ownership_by_checkout_id,
168 reserve_id => \&_object_ownership_by_reserve_id,
171 foreach my $param (keys $parameters) {
172 my $check_ownership = $parameters->{$param};
173 if ($c->stash($param)) {
174 return &$check_ownership($c, $user, $c->stash($param));
176 elsif ($c->param($param)) {
177 return &$check_ownership($c, $user, $c->param($param));
179 elsif ($c->req->json && $c->req->json->{$param}) {
180 return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
185 =head3 _object_ownership_by_accountlines_id
187 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
192 sub _object_ownership_by_accountlines_id {
193 my ($c, $user, $accountlines_id) = @_;
195 my $accountline = Koha::Account::Lines->find($accountlines_id);
196 return $accountline && $user->borrowernumber == $accountline->borrowernumber;
199 =head3 _object_ownership_by_borrowernumber
201 Compares C<$borrowernumber> to currently logged in C<$user>.
205 sub _object_ownership_by_borrowernumber {
206 my ($c, $user, $borrowernumber) = @_;
208 return $user->borrowernumber == $borrowernumber;
211 =head3 _object_ownership_by_checkout_id
213 First, attempts to find a Koha::Issue-object by C<$issue_id>. If we find one,
214 compare its borrowernumber to currently logged in C<$user>. However, if an issue
215 is not found, attempt to find a Koha::OldIssue-object instead and compare its
216 borrowernumber to currently logged in C<$user>.
220 sub _object_ownership_by_checkout_id {
221 my ($c, $user, $issue_id) = @_;
223 my $issue = Koha::Issues->find($issue_id);
224 $issue = Koha::OldIssues->find($issue_id) unless $issue;
225 return $issue && $issue->borrowernumber
226 && $user->borrowernumber == $issue->borrowernumber;
229 =head3 _object_ownership_by_reserve_id
231 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
234 TODO: Also compare against old_reserves
238 sub _object_ownership_by_reserve_id {
239 my ($c, $user, $reserve_id) = @_;
241 my $reserve = Koha::Holds->find($reserve_id);
242 return $reserve && $user->borrowernumber == $reserve->borrowernumber;