View | Details | Raw Unified | Return to bug 37025
Collapse All | Expand All

(-)a/debian/docs/koha-api-keys.xml (-25 / +41 lines)
Lines 29-39 Link Here
29
29
30
        <refsynopsisdiv>
30
        <refsynopsisdiv>
31
            <cmdsynopsis>
31
            <cmdsynopsis>
32
                <command>koha-api-keys</command>
32
                <command>sudo koha-shell</command>
33
                <arg choice="req">generate | delete</arg>
33
                <arg choice="req"><option>-c</option> "koha-api-keys <option>--generate</option> <option>--description</option> <replaceable>description</replaceable> <option>--borrowernumber</option> <replaceable>borrowernumber</replaceable>"</arg>
34
                <arg choice="opt"><replaceable>description</replaceable></arg>
34
                <arg choice="req"><replaceable>instancename</replaceable></arg>
35
                <arg choice="opt"><replaceable>borrowernumber</replaceable></arg>
35
            </cmdsynopsis>
36
                <arg choice="opt"><replaceable>instancename</replaceable></arg>
36
            <cmdsynopsis>
37
                <command>sudo koha-shell</command>
38
                <arg choice="req"><option>-c</option> "koha-api-keys <option>--delete</option> [<option>--client-id</option> <replaceable>client_id</replaceable>]"</arg>
39
                <arg choice="req"><replaceable>instancename</replaceable></arg>
40
            </cmdsynopsis>
41
            <cmdsynopsis>
42
                <command>sudo koha-shell</command>
43
                <arg choice="req"><option>-c</option> "koha-api-keys <option>--help</option>"</arg>
44
                <arg choice="req"><replaceable>instancename</replaceable></arg>
37
            </cmdsynopsis>
45
            </cmdsynopsis>
38
        </refsynopsisdiv>
46
        </refsynopsisdiv>
39
47
Lines 42-87 Link Here
42
            <para>
50
            <para>
43
                The <command>koha-api-keys</command> script allows administrators to generate or delete API keys associated with specific Koha patrons. These API keys can be used for authorized programmatic access to the Koha system.
51
                The <command>koha-api-keys</command> script allows administrators to generate or delete API keys associated with specific Koha patrons. These API keys can be used for authorized programmatic access to the Koha system.
44
            </para>
52
            </para>
45
        </refsect1>
46
47
<refsect1>
48
            <title>Description</title>
49
            <para>
53
            <para>
50
                The <command>koha-api-keys</command> script allows administrators to generate or delete API keys associated with specific Koha patrons. These API keys can be used for authorized programmatic access to the Koha system.
54
                As this tool requires administrative privileges and access to the Koha environment, it must be run using <command>sudo</command> and the <command>koha-shell</command> wrapper as shown in the synopsis.
51
            </para>
55
            </para>
52
        </refsect1>
56
        </refsect1>
53
57
54
        <refsect1>
58
        <refsect1>
55
            <title>Arguments</title>
59
            <title>Options</title>
56
            <variablelist>
60
            <variablelist>
57
                <varlistentry>
61
                <varlistentry>
58
                    <term><replaceable>generate</replaceable></term>
62
                    <term><option>--generate</option></term>
59
                    <listitem>
63
                    <listitem>
60
                        <para>Generates a new API key for the specified patron.</para>
64
                        <para>Generate a new API key for the specified patron.</para>
61
                    </listitem>
65
                    </listitem>
62
                </varlistentry>
66
                </varlistentry>
63
                <varlistentry>
67
                <varlistentry>
64
                    <term><replaceable>delete</replaceable></term>
68
                    <term><option>--delete</option></term>
65
                    <listitem>
69
                    <listitem>
66
                        <para>Deletes an existing API key based on its Client ID.</para>
70
                        <para>Delete an existing API key (client ID will be prompted if not provided via --client-id).</para>
67
                    </listitem>
71
                    </listitem>
68
                </varlistentry>
72
                </varlistentry>
69
                <varlistentry>
73
                <varlistentry>
70
                    <term><replaceable>description</replaceable></term>
74
                    <term><option>--description</option></term>
71
                    <listitem>
75
                    <listitem>
72
                        <para>A description for the API key.</para>
76
                        <para>Description for the API key (required for --generate).</para>
73
                    </listitem>
77
                    </listitem>
74
                </varlistentry>
78
                </varlistentry>
75
                <varlistentry>
79
                <varlistentry>
76
                    <term><replaceable>borrowernumber</replaceable></term>
80
                    <term><option>--borrowernumber</option></term>
77
                    <listitem>
81
                    <listitem>
78
                        <para>The borrower number of the patron to associate the API key with.</para>
82
                        <para>Patron's borrower number (required for --generate).</para>
79
                    </listitem>
83
                    </listitem>
80
                </varlistentry>
84
                </varlistentry>
81
                <varlistentry>
85
                <varlistentry>
82
                    <term><replaceable>instancename</replaceable></term>
86
                    <term><option>--client-id</option></term>
83
                    <listitem>
87
                    <listitem>
84
                        <para>The name of the Koha instance to operate on.</para>
88
                        <para>Client ID to delete (optional for --delete, will be prompted if not provided).</para>
89
                    </listitem>
90
                </varlistentry>
91
                <varlistentry>
92
                    <term><option>--help</option></term>
93
                    <listitem>
94
                        <para>Display help message.</para>
85
                    </listitem>
95
                    </listitem>
86
                </varlistentry>
96
                </varlistentry>
87
            </variablelist>
97
            </variablelist>
Lines 89-99 Link Here
89
99
90
        <refsect1>
100
        <refsect1>
91
            <title>Examples</title>
101
            <title>Examples</title>
92
            <para>Generate a new API key for patron '12345' with the description 'Patron Access':</para>
102
            <para>Generate a new API key for patron '123' with the description 'Test API access':</para>
93
            <screen>$ koha-api-keys generate 'Patron Access' 12345 kohadev</screen>
103
            <screen>$ sudo koha-shell -c "koha-api-keys --generate --description 'Test API access' --borrowernumber 123" instancename</screen>
104
105
            <para>Delete an existing API key (interactive):</para>
106
            <screen>$ echo "CLIENT_ID" | sudo koha-shell -c "koha-api-keys --delete" instancename</screen>
107
108
            <para>Delete an existing API key (scripted):</para>
109
            <screen>$ sudo koha-shell -c "koha-api-keys --delete --client-id a1b2c3d4-e5f6-7890-abcd-ef1234567890" instancename</screen>
94
110
95
            <para>Delete an existing API key with Client ID 'abc123def456':</para>
111
            <para>Display help information:</para>
96
            <screen>$ koha-api-keys delete abc123def456 kohadev</screen>
112
            <screen>$ sudo koha-shell -c "koha-api-keys --help" instancename</screen>
97
        </refsect1>
113
        </refsect1>
98
    </refentry>
114
    </refentry>
99
</article>
115
</article>
(-)a/debian/scripts/koha-api-keys (-75 / +205 lines)
Lines 1-5 Link Here
1
#!/bin/bash
1
#!/usr/bin/perl
2
#
2
3
# koha-api-keys: generate or delete api keys for a given patron and
3
# koha-api-keys: generate or delete api keys for a given patron and
4
#   koha instance.
4
#   koha instance.
5
# Copyright 2024 LMSCloud GmbH
5
# Copyright 2024 LMSCloud GmbH
Lines 17-97 Link Here
17
# You should have received a copy of the GNU General Public License
17
# You should have received a copy of the GNU General Public License
18
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
18
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
19
19
20
set -e
20
use Modern::Perl;
21
umask 0077
21
use Getopt::Long qw( GetOptions );
22
use Pod::Usage   qw( pod2usage );
23
24
use Koha::Script;
25
use Koha::ApiKeys;
26
use Koha::Patrons;
27
use C4::Log qw( logaction );
28
29
my $generate;
30
my $delete;
31
my $help;
32
my $description;
33
my $borrowernumber;
34
my $client_id;
35
36
GetOptions(
37
    'generate'         => \$generate,
38
    'delete'           => \$delete,
39
    'help|h'           => \$help,
40
    'description=s'    => \$description,
41
    'borrowernumber=i' => \$borrowernumber,
42
    'client-id=s'      => \$client_id,
43
) or pod2usage(2);
44
45
if ($help) {
46
    pod2usage(1);
47
}
22
48
23
# include helper functions
49
if ( !$generate && !$delete ) {
24
if [ -f "/usr/share/koha/bin/koha-functions.sh" ]; then
50
    pod2usage(
25
    . "/usr/share/koha/bin/koha-functions.sh"
51
        {
26
else
52
            -message => "Error: No operation specified. Use --generate or --delete.",
27
    echo "Error: /usr/share/koha/bin/koha-functions.sh not present." 1>&2
53
            -exitval => 1
28
    exit 1
54
        }
29
fi
55
    );
56
}
30
57
31
usage() {
58
if ( $generate && $delete ) {
32
    local scriptname=$0
59
    pod2usage(
33
    cat <<EOF
60
        {
34
Generate, or delete api keys for specified patron.
61
            -message => "Error: Cannot specify both --generate and --delete.",
62
            -exitval => 1
63
        }
64
    );
65
}
66
67
if ($generate) {
68
    if ( !$description ) {
69
        pod2usage(
70
            {
71
                -message => "Error: --generate requires --description.",
72
                -exitval => 1
73
            }
74
        );
75
    }
76
    if ( !$borrowernumber ) {
77
        pod2usage(
78
            {
79
                -message => "Error: --generate requires --borrowernumber.",
80
                -exitval => 1
81
            }
82
        );
83
    }
84
85
    my $patron = Koha::Patrons->find($borrowernumber);
86
    if ( !$patron ) {
87
        die "Error: Unknown borrowernumber: '$borrowernumber'\n";
88
    }
89
90
    my $api_key = Koha::ApiKey->new(
91
        {
92
            patron_id   => $borrowernumber,
93
            description => $description,
94
        }
95
    )->store;
96
97
    # Log the API key generation for audit purposes
98
    logaction(
99
        'APIKEY', 'GENERATE', $borrowernumber,
100
        "Generated API key for patron $borrowernumber with description '$description'"
101
    );
102
103
    printf "Client ID:\t%s\nClient Secret:\t%s\n", $api_key->client_id, $api_key->plain_text_secret;
104
    exit 0;
105
}
35
106
36
Usage: $scriptname generate|delete [ description ] [ borrowernumber ] [ instancename ]
107
if ($delete) {
108
    if ( !$client_id ) {
109
        print "Client ID to delete: ";
110
        $client_id = <STDIN>;
111
        chomp $client_id;
112
    }
37
113
38
EOF
114
    if ( !$client_id ) {
115
        die "Error: No client ID provided.\n";
116
    }
117
118
    my $api_key = Koha::ApiKeys->find($client_id);
119
    if ( !$api_key ) {
120
        die "Error: Unknown client ID: '$client_id'\n";
121
    }
122
123
    # Store patron_id for logging before deletion
124
    my $patron_id = $api_key->patron_id;
125
126
    $api_key->delete;
127
128
    # Log the API key deletion for audit purposes
129
    logaction(
130
        'APIKEY', 'DELETE', $patron_id,
131
        "Deleted API key $client_id for patron $patron_id"
132
    );
133
134
    print "API key deleted successfully.\n";
135
    exit 0;
39
}
136
}
40
137
41
op="$1"
138
__END__
42
139
43
[ "$#" -ge 2 ] || (
140
=head1 NAME
44
    usage
141
45
    die 'Missing required arguments.'
142
koha-api-keys - Generate or delete API keys for specified patrons
46
)
143
47
144
=head1 SYNOPSIS
48
if [ "$op" == 'generate' ]; then
145
49
    if [ "$#" -eq 3 ]; then
146
sudo koha-shell -c "koha-api-keys --generate --description DESCRIPTION --borrowernumber BORROWERNUMBER" instancename
50
        description=$(openssl rand -hex 16)
147
51
        borrowernumber="$2"
148
sudo koha-shell -c "koha-api-keys --delete [--client-id CLIENT_ID]" instancename
52
        instance="$3"
149
53
    fi
150
sudo koha-shell -c "koha-api-keys --help" instancename
54
151
55
    if [ "$#" -eq 4 ]; then
152
=head1 OPTIONS
56
        description="$2"
153
57
        borrowernumber="$3"
154
=over 8
58
        instance="$4"
155
59
    fi
156
=item B<--generate>
60
157
61
    is_instance "$instance" || (
158
Generate a new API key for the specified patron.
62
        usage
159
63
        die "Unknown instance '$instance'"
160
=item B<--delete>
64
    )
161
65
    if ! koha-shell -c "perl -MKoha::Patrons -e \"Koha::Patrons->find($borrowernumber) or die;\"" "$instance" 2>/dev/null; then
162
Delete an API key (client ID will be prompted if not provided via --client-id).
66
        die "Unknown borrowernumber: '$borrowernumber'"
163
67
    fi
164
=item B<--description DESCRIPTION>
68
165
69
    {
166
Description for the API key (required for --generate).
70
        read -r client_id
167
71
        read -r secret
168
=item B<--borrowernumber BORROWERNUMBER>
72
    } < <(
169
73
        koha-shell -c "perl -MKoha::ApiKeys -e \"my \\\$key = Koha::ApiKey->new( { patron_id => $borrowernumber, description => '$description' } )->store; printf \\\"%s\\n%s\\n\\\", \\\$key->client_id, \\\$key->plain_text_secret;\"" "$instance"
170
Patron's borrower number (required for --generate).
74
    )
171
75
172
=item B<--client-id CLIENT_ID>
76
    printf "Client ID:\t%s\nClient Secret:\t%s\n" "$client_id" "$secret"
173
77
174
Client ID to delete (optional for --delete, will be prompted if not provided).
78
    exit 0
175
79
fi
176
=item B<--help>
80
177
81
if [ "$op" == 'delete' ]; then
178
Display this help message.
82
    instance="$2"
179
83
    is_instance "$instance" || (
180
=back
84
        usage
181
85
        die "Unknown instance '$instance'"
182
=head1 DESCRIPTION
86
    )
183
87
184
This script lets you generate or delete API keys for specified patrons in Koha.
88
    read -rp "Client ID to delete: " client_id
185
89
    if ! koha-shell -c "perl -MKoha::ApiKeys -e \"Koha::ApiKeys->find(\\\"$client_id\\\")->delete or die;\"" "$instance" 2>/dev/null; then
186
As this tool requires administrative privileges and access to the Koha environment,
90
        die "Unknown client id: '$client_id'"
187
it must be run using sudo and koha-shell wrapper as shown in the synopsis.
91
    fi
188
92
189
For generating keys, you must provide both a description and a borrower number.
93
    exit 0
190
For deleting keys, you can provide the client ID via --client-id or be prompted interactively.
94
fi
191
95
192
=head1 EXAMPLES
96
usage
193
97
die "Invalid operation: '$op'"
194
Generate an API key:
195
    sudo koha-shell -c "koha-api-keys --generate --description 'Test API access' --borrowernumber 123" instancename
196
197
Delete an API key (interactive):
198
    echo "CLIENT_ID" | sudo koha-shell -c "koha-api-keys --delete" instancename
199
200
Delete an API key (scripted):
201
    sudo koha-shell -c "koha-api-keys --delete --client-id a1b2c3d4-e5f6-7890-abcd-ef1234567890" instancename
202
203
=head1 AUTHOR
204
205
Koha Development Team
206
207
=head1 COPYRIGHT
208
209
Copyright LMSCloud GmbH
210
211
=head1 LICENSE
212
213
This file is part of Koha.
214
215
Koha is free software; you can redistribute it and/or modify it
216
under the terms of the GNU General Public License as published by
217
the Free Software Foundation; either version 3 of the License, or
218
(at your option) any later version.
219
220
Koha is distributed in the hope that it will be useful, but
221
WITHOUT ANY WARRANTY; without even the implied warranty of
222
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
223
GNU General Public License for more details.
224
225
You should have received a copy of the GNU General Public License
226
along with Koha; if not, see <http://www.gnu.org/licenses>.
227
228
=cut
98
- 

Return to bug 37025