[Koha] Koha and Kanopy integration via SIP2

[Mark Alexander]

Excerpts from Steve Nickerson's message of 2020-11-04 12:16:45 -0500:
> Does anyone have experience getting Koha "connected" to Kanopy via SIP2?

I have done this, and it was not a trivial task.  Our library decided
that the use of Kanopy should be enabled or disabled for each patron,
and not globally enabled.  This complicated things a lot.  I had to
add a KANOPY_OK patron attribute, write a plugin, and patch the SIP2
server.  I wrote some notes about the process, which I've included
below and anonymized.  The notes are a bit rough, so if something
doesn't make sense, please ask for clarification.  Note also that I am
using Koha 19.11.06 and haven't tested this with later versions of
Koha.

I've put the code for the plugin here:

https://gitlab.com/bloovis/marc/-/blob/master/koha-plugins/Koha/Plugin/Com/Bloovis/Sip2patron.pm

The patch for the SIP2 server is here:

https://gitlab.com/bloovis/marc/-/blob/master/SIP-plugin.patch

The plugin and patch cause the SIP2 server to check that the KANOPY_OK
patron attribute is set for the patron being queried by Kanopy.

(In the following, replace 'lib' and 'LIB' with your actual Koha library instance name,
lower- or upper-case as appropriate.)

First, enable the ExtendedPatronAttributes preference.  Then in
Administration / Patron Attribute Types, create a new attribute type
called KANOPY_OK.  This has an authorized value category of YES_NO,
and will be used to indicate that the patron is allowed to use Kanopy.

On the Koha server, add a new user called "kanopy" using this command as root:

    adduser kanopy

Respond to the password prompt by entering a hard-to-guess password, preferably
one generated randomly.

In the following examples, replace '**password**' with the password you just
assigned to the kanopy user.

In the Koha staff client, add a patron called "kanopy" with a hard-to-guess password.
For simplicity, the password can be the same as the one you assigned to the user above.
Give this patron "circulation" permissions.

Log into the Koha server as root using ssh.  Then run:

   koha-enable-sip rpl

Edit /etc/koha/sites/rpl/SIPconfig.xml.

In the "listeners" section, remove the IP address restriction in
the port setting for the 6001/tcp service, so that it looks like this:

      port="6001/tcp"

The "accounts" section should have one entry:

    <login id="kanopy" password="**password**" delimiter="|" error-detect="enabled" institution="LIB" />

Make the password match the patron's password that was set above.

The "institutions" section should have one entry:

    <institution id="LIB" implementation="ILS" parms="">
          <policy checkin="true" renewal="true" checkout="true"
            status_update="false" offline="false"
          timeout="100"
            retries="5" />
    </institution>

Start the SIP server:

    koha-start-sip lib

To test SIP2, Use this command:

    telnet localhost 6001

Enter the login message:

    9300CNkanopy|CO**password**|CPLIB|

where '**password**' is the password of the kanopy patron.
This should return the response:

    941

Then check the kanopy patron using this message:

    6300020180906    174600Y         AOLIB|AAkanopy|AD**password**

This should return the following response (line split for clarity):

    64              00020180907    074824000000000000000000000000AOLIB|AALIBKANOPY|
    AE Kanopy|BLY|CQY|CC5|BEnone at example.com|BF555-1212|PCS|PIY|AFGreetings from Koha. |

Enter a blank line to exit.

The SIP2 protocol is not encrypted, so the client (Kanopy's server)
must set up an ssh tunnel that encrypts the SIP2 traffic.  To verify
that this will work, run this from another machine:

    ssh -f -N -L 9876:koha.example.com:6001 kanopy at koha.example.com

This sets up an ssh tunnel from port 9876 on the local (client) machine
to port 6001 on the Koha server (koha.example.com).
After you enter the password for kanopy, ssh will go into the background.
Then you can use this to test the tunnel:

    telnet localhost 9876

Then enter the SIP2 messages as described in the previous section.

Finally, you will need to submit a Kanopy Library Authentication Integration
form to Kanopy, telling it about how it can access your SIP2 server.
This information will include:

* your Koha server name, IP address, and SIP2 port (6001 in the example above)
* the name and password of a valid patron account for testing (I created
  a special patron solely for this purpose)
* the credentials for the SSH tunnel (kanopy:**password**@koha.example.com:22
  in the example above)

-- 
I am currently going through a difficult transition period
called "Life". --Ashleigh Brilliant