When setting up your institution's Kanopy website, we must ensure that access is allowed only to your approved users.
For public libraries, we can establish security through one of the following API methods of authentication: SIP/SIP2, Patron API, and SirsiDynix REST Web Services.In the rare circumstances where these are not available, we are also compatible with EZProxy and barcode pattern authentication. API is preferred over these methods for a number of reasons:
- Increased security: With the ability to do API checks on users in the background, we can more regularly run checks on users to ensure the security of access to your website
- Block Rules: API methods allow us to set restrictions on any card types that you might want to block from accessing Kanopy, i.e. cards with excessive fines, or expired cards. Barcode authentication and EZProxy do not allow us to set these blocks. (More information on block rules can be found below)
- More usage data: When using EZProxy, patron data is passed through your proxy as opposed to Kanopy, so we are not able to collect enough information to provide statistics like the average number of play credits used per patron, or average number of Kanopy Kids plays per charge
If you have updated authentication details for an existing Kanopy platform, please reach out to us at email@example.com and we will send a new form to add these details.
How to Fill out your Authentication Form:
When setting up patron authentication for your new platform or providing us with updated authentication for an active account, Kanopy will provide you with an "Authentication Form" for you to complete with your API details. The form will ask you for all of the information we need to verify your patrons as valid library card holders. When filling out this form, please provide as much detail as possible.
Whitelisting our IPs:
When Kanopy is communicating with a server to verify your cardholders, we first need to be allowed to exchange calls and receive the patron data we need to confirm that the cards are valid. This means that traffic from Kanopy’s IPs must be allowed through your firewall before we can verify a successful connection. Before sending in your authentication form, please have your IT contact or ILS vendor whitelist the following IPs addresses:
In order to test and therefore ensure a working connection, we will need at least one test card for your library, which you can add to this section of the authentication form:
Even if your authentication does not require PINs, please add the PIN to this part of the form, as they may be required for testing. Test cards must also be in good standing (i.e. not expired, blocked, etc.) in order for us to test our connection.
Providing Authentication Details:
If we will be validating your patrons using Patron API or SIP2 (our most common and preferred methods), please provide a domain URL host in addition to the IP address. We can connect to your host using an IP address, but URL is preferred because it is not subject to change. Having your ILS Provider and Product will help us with troubleshooting and/or formatting our calls to your server. Here is an example of how to fill out the Authentication form with Patron API information:
If you would like to restrict access to a certain patron type, we will need the required information:
- Test card with PIN that you would like to be blocked
- Indicator of how your library signifies the information to be blocked. For example, if you would like us to block cards with fines exceeding $20, please let us know what field signifies this, i.e. cards where “BV” is greater than or equal to “20”. If you would like us to block all cards of a different home library, this could be cards where “HOMELIBR” does not equal “MYLIBRARY”, or cards with a “PTYPE” is outside of “1, 2 or 3”. We are also able to limit by prefix, if this is how your ILS provider designates libraries connected to the same server.
Barcode Pattern Authentication:
When a server connection is not available, we may be able to verify your patrons by checking that their library card follows the correct pattern for your library. Because we are not connecting with an ILS that verifies whether the card is valid, barcode pattern authentication does not present the same level of security. Without the ability to do API checks on users, Kanopy cannot run checks on library cards to ensure the security of access to your website, nor access the information needed to set block rules (i.e. block expired cards or cards with excessive fines).
Barcode Pattern Authentication is only an option if all of your library cards follow the same pattern. For example, all cards might contain the same prefix and number of digits (i.e. 14 digit cards beginning with 54321), or end with the same suffix.
It is important to note that whatever authentication protocol you use will always work on all links, including individual film links, links that are shared on social media, embedded or otherwise.
If you have any questions on this at all, please contact us at firstname.lastname@example.org.