• Created by Unknown User (robertwilliams), last modified on Dec 16, 2019

From its early days, Biblionix has used only encrypted communications in providing access to its SIP2 service for patron authentication. Encrypted connections protect patron information that is passed back and forth between systems, which formerly was passed "in the clear" over the Internet. Their preferred connection is established over a TLS (formerly SSL) session using a private certificate Biblionix signs and provides to organizations needing to communicate with their SIP service. A certificate is assigned to the organization hosting a service (such as the Library Simplified Circulation Manager) that needs to communicate via SIP. Therefore, for an organization hosting SimplyE for multiple libraries, only one certificate is required.

Obtain an SSL Certificate from Biblionix for Your Organization

The certificate needed to communicate with Biblionix's SIP2 service is a private certificate created in communication with Biblionix. It is not a public certificate like those obtained for a fee through a third-party registrar like GoDaddy or Network Solutions. Therefore, there is no fee for the certificate, and the process is very easy. You will create a certificate signing request and send its file to Biblionix. The staff will engage with you by email to make sure any questions you have are answered and that your Circulation Manager is able to connect appropriately. Here is the process.

Step 1. Create a certificate signing request (csr)

Using a client utility such as OpenSSL, issue a command with some custom parameters associated with your organization. The parameters identify your organization's physical location (potentially a main office–this is up to you). I'll use my physical Dallas, Texas location as an example. You also need a service identifier that is unique to your organization. That identifier will go in the CN field. We'll use <your_org> as a placeholder for your organization's name, or a short form of it, with a '-SIP' suffix. For this certificate, the content of the identifier is not super important, but it should be unique, so using a tag identifying your organization name is a good bet. Again, this is a private certificate between your organization and Biblionix, so no one else will see any of these values.

openssl req -new -newkey rsa:2048 -nodes -out Biblionix-<your_org>.csr -keyout Biblionix-<your_org>.key -subj "/C=US/ST=Texas/L=Dallas/O=<your_org>/CN=<your_org>SIP"

Step 2. Send the certificate signing request to Biblionix

The command above will create two files: a certificate signing request file (Biblionix-<your_org>.csr), and a private key file (Biblionix-<your_org>.key). Submit only the resulting certificate request file by email to Biblionix so they can create the signed certificate. Do not send the private key file. Keep the private key in a secure location on your own servers pending receipt of the signed certificate file from Biblionix. Send the request, and any questions about the SIP service configuration, to sip@biblionix.com. In the email, you can also indicate how you want your organization's connection to appear in the Apollo SIP Connectivity settings area (see Have library enable SimplyE service access in Apollo below). In the example below, the connection is listed with a service name. It could also be listed as your organization name or something similar, as well. The choice is up to you.

Once Biblionix has created the signed certificate file (.crt extension), they will return it to you by email. You will use the content of this certificate file, along with the content of the key file created in Step 1, when configuring a library patron authentication integration (shown below).

Obtain Library-Specific Data

Step 1. Determine the SIP2 service login data for a particular library

For each Biblionix library you will host on a Circulation Manager, you must create a separate patron authentication integration. You will use the same certificate and key content for each library. However, you need to provide library-specific connectivity and login information that varies by library.

Host/domain name: The library's domain name for its Biblionix SIP2 service is very similar to its base Apollo website domain. The Apollo website domain has the following form: <library_name>.biblionix.com. The SIP2 domain/hostname will be: <library_name>-sip.biblionix.com.

The <library_name> tag is actually the Apollo account/login name. It is usually a keyword in the library name, most commonly the city name. If a library uses its own domain name to front the Apollo catalog, staff won't see the biblionix.com domain until they log in to their Apollo staff page. On their Staff page, the account name will show up in the URL bar. If for any reason the library has difficulty determining the Apollo account name, send a message to sip@biblionix.com and request the library's SIP2 service host name.

Port number: All certificate-based connections use the same port number: 9500.
SIP Login user name: the Apollo account name, <library_name>
SIP Login password: when using certificate access, no password is required for login; however, if you wish to pass one, it does not cause an error or prevent login success.

Step 2. Determine the library's prompts for user logins

Apollo provides a customizable set of login prompts (username/identifier and password) in its Settings area. While the default settings are most commonly used, a library may change these. The Circulation Manager allows customization of these prompts as well. Check with the library and determine if either prompt has been customized:

Username/Identifier prompt: Card Number (default)
Password prompt: Phone Number or Password (default)

Step 3. Obtain a test barcode and password/phone number from library staff to test the SIP2 connection

This data must be obtained from the library itself. In our experience, we've sometimes received actual test user credentials; however, sometimes you'll receive real user credentials of a library staff member. If you receive test user credentials, double-check with library staff to be certain the user is configured in the ILS. Be aware that Biblionix works with small libraries, some of which employ very simple barcode numbering. Therefore, it is not unusual to receive barcode numbers that are simple four- or five-digit numbers.

Test user barcode: 98765 (whatever provided by the library)
Test user password: 972-555-1212 (whatever provided by the library)


NOTE: When configuring multiple Apollo libraries

If your organization is configuring many Apollo libraries at once, for example an entire state with a large Apollo presence, Biblionix can work with you to streamline the process of gathering data for the libraries (other than barcodes). Mention your plans to them when you email them.

Have library enable SimplyE service access in Apollo

Another step required of library staff is enabling access to their site using the Biblionix SIP2 service from the Circulation Manager. Have library staff:

  1. Log into the Settings area (named Setup or Settings) of their Apollo catalog
  2. Click the SIP Connectivity tab
  3. Check the correct service checkbox (shown below as "E-Read Texas" for a Texas implementation). The organizational phrase you discuss with Biblionix staff above will be the item that appears here for your implementation.

The setting is saved as soon as the library sets it.

Configure a Biblionix Patron Authentication Integration

Once you have the required data, you can create the patron authentication integration for a library in the Circulation Manager Admin interface. You will need to open both the SSL certificate and the key files and be prepared to copy their contents into the integration form.

Step-by-step instructions are shown below. Screenshots are forthcoming.

  1. Login in to your CM as normal
  2. Click the System Configuration item in the top right menu
  3. Click Patron Authentication in the left sidebar
  4. Click the Create new patron authentication service button
  5. Give the integration a Name; if you are hosting multiple libraries, adding the name is a good idea; e.g., Biblionix - Smithville
  6. Select the SIP2 option from the Protocol drop-down
  7. Enter the Server domain or hostname as determined above; e.g., smithville-sip.biblionix.com
  8. Enter the Biblionix SIP Port: 9500
  9. Select the Connect to the SIP2 server over SSL option from the Connect over SSL? drop-down
  10. (For v3.0.2+: Leave the ILS option at Generic ILS)
  11. Enter the test patron barcode into the Test Identifier field; e.g., 98765
  12. Enter the test patron password/PIN/phone number into the Test Password field; e.g., 972-555-1212
  13. Click the Optional Fields section header to open the list of its fields
  14. Enter the Apollo account/username in the Login User ID field; e.g., smithville
  15. Either leave the Login Password field blank or enter a throw-away password
  16. Copy the full text of your certificate file; be sure to include the BEGIN line and END lines in their entirety (including hyphens).
  17. Enter the copied certificate text into the SSL Certificate field; be sure no end-of-line character is included (cursor ends up on a blank line; it should appear to the right of the last hyphen)
  18. Copy the full text of your key file; again, be sure to include the BEGIN and END lines in their entirety
  19. Enter the copied key text into the SSL Key field; be sure no end-of-line character is included
  20. Enter the library's username prompt text into the Label for identifier entry field; e.g., Card Number
  21. Enter the library's password prompt text into the Label for password entry field; e.g., Phone Number or Password
  22. Click the Libraries section header
  23. Select the library name from the Add Library drop-down
  24. (No other data entry is required for this integration)
  25. Click the Add Library button
  26. Review the data you have entered into the full integration form
  27. Click the Submit button to save the patron authentication integration

Test the Patron Authentication Connection

  1. Click the Patron Authentication sidebar item to go to the list of existing patron authentication integrations
  2. Click the troubleshooting page link
  3. Click the particular integration you wish to test, which opens the testing results display
  4. Click the Run tests button
  5. You will see entries showing:
    1. whether the SIP connection succeeded
    2. whether the SIP login succeeded
    3. whether retrieving patron information for the test patron succeeded

Result boxes for each aspect of the test will be green when successful, red when there is an issue. There are two fairly common problems (in my experience):

  • The library may not actually have checked the option to enable SIP2 access from the CM. If so, you may receive an error message in the results with a SIP message number like '940' (indicating a problem with SIP login); the error may show up in logs like "Failure contacting external service".
  • The library may have made up a test patron barcode/password that is not in the ILS. If so, you will see a patron authentication error.

When successful, you can click the Results bar in the Raw test patron information box to see the data passed back from Apollo from the patron information request.


All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.