Setting Up SSL / HTTPS for Local Primo Customers

Setting Up SSL / HTTPS for Local Primo Customers

CONFIDENTIAL INFORMATION The information herein is the property of Ex Libris Ltd. or its affiliates and any misuse or abuse will result in economic loss. DO NOT COPY UNLESS YOU HAVE BEEN GIVEN SPECIFIC WRITTEN AUTHORIZATION FROM EX LIBRIS LTD. This document is provided for limited and restricted purposes in accordance with a binding contract with Ex Libris Ltd. or an affiliate. The information herein includes trade secrets and is confidential DISCLAIMER The information in this document will be subject to periodic change and updating. Please confirm that you have the most current documentation. There are no warranties of any kind, express or implied, provided in this documentation, other than those expressly agreed upon in the applicable Ex Libris contract. This information is provided AS IS. Unless otherwise agreed, Ex Libris shall not be liable for any damages for use of this document, including, without limitation, consequential, punitive, indirect or direct damages. Any references in this document to third-party material (including third-party Web sites) are provided for convenience only and do not in any manner serve as an endorsement of that third-party material or those Web sites. The third-party materials are not part of the materials for this Ex Libris product and Ex Libris has no liability for such materials. TRADEMARKS "Ex Libris," the Ex Libris Bridge to Knowledge, Primo, Aleph, Voyager, SFX, MetaLib, Verde, DigiTool, Rosetta, bx, URM, Alma, and other marks are trademarks or registered trademarks of Ex Libris Ltd. or its affiliates. The absence of a name or logo in this list does not constitute a waiver of any and all intellectual property rights that Ex Libris Ltd. or its affiliates have established in any of its products, features, or service names or logos. Trademarks of various third-party products, which may include the following, are referenced in this documentation. Ex Libris does not claim any rights in these trademarks. Use of these marks does not imply endorsement by Ex Libris of these third-party products, or endorsement by these third parties of Ex Libris products. Oracle is a registered trademark of Oracle Corporation. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd. Microsoft, the Microsoft logo, MS, MS-DOS, Microsoft PowerPoint, Visual Basic, Visual C++, Win32, Microsoft Windows, the Windows logo, Microsoft Notepad, Microsoft Windows Explorer, Microsoft Internet Explorer, and Windows NT are registered trademarks and ActiveX is a trademark of the Microsoft Corporation in the United States and/or other countries. Unicode and the Unicode logo are registered trademarks of Unicode, Inc. Google is a registered trademark of Google, Inc. Copyright Ex Libris Limited, 2015. All rights reserved. Document released: May 2015 Web address: http://www.exlibrisgroup.com 2

Table of Contents 1 Purpose of This Document 4 2 Introduction 4 3 Prerequisites 4 4 High Level Solution 4 5 Naming Convention 5 6 Ports and Communication 5 7 General Configuration for Primo 6 Back Office Configuration 6 Apache Configuration (PDS) 8 8 Test Cases for Verification 8 9 Known Issues 9 10 Additional Changes 9 11 Troubleshooting 9 12 General DNS and LB Configuration 9 3

Purpose of This Document This document describes the instructions to set up and configure SSL/HTTPS in local Primo installations. The instructions provide a guideline for setting up SSL and depend on your specific network topology. The network configuration instructions are based on the common network elements that are used in Ex Libris cloud. You may need to modify the instructions to fit your specific network elements and topology. Note: These instructions are relevant to customers who are running the Primo April 2015 release. Introduction Secure Sockets Layer (SSL) is a cryptographic protocol that is designed to provide communication security over the Internet using X.509 certificates. Once the SSL certificates are approved, all communication between the browser and the server are encrypted. In addition, the browser verifies that the certificates are compatible with the domain site with which they are communicating. HTTPS is a secure communication protocol that is layered over SSL. This document refers to both as SSL. Prerequisites To implement SSL, it is recommended that Primo use a load balancer (LB) that supports HTTPS offloading and hostname switching. For customers who integrate Primo and SFX (or any other integration that does not support SSL), it is not recommended to configure SSL with your Primo FE to prevent interoperability issues. High Level Solution Although Primo partially supports SSL configuration at the application level, it is highly recommended to configure SSL at the load balancer level. This has a number of advantages, such as the following: Offloads the SSL processing from the Primo server Easier to configure Provides a single point to position the SSL certificate You can configure SSL on any of the HTTP communication channels (FE, BE, and PDS). The solution is based on LB hostname switching. To configure SSL to access Primo, you should define two separate DNS names: one for FE and BE and another for PDS. The LB will 4

identify the URL and forward requests to the correct server and port according to the hostname in the URL. After you configure SSL: FE and PDS communication between the customer and Primo will use HTTPS on port 443. Any incoming requests on port 80 will be redirected to port 443 (using SSL). BE communication between the customer and Primo will use HTTPS on port 1443. Any incoming requests on port 1601 will be redirected to port 1443 (using SSL) Port 8991 will not respond. Naming Convention As mentioned previously, you should create two separate DNS names: one for the FE and BE and another for PDS: FE and BE: primo-<custid> PDS: pds-primo-<custid> The following table contains examples and descriptions: Server Format Example Type DNS Points to (Example) FE/ BE <Selected by customer> primo.myinst.edu DNS A-Record VIP (virtual IP) PDS pds- <Selected by customer> pds-primo.myinst.edu CNAME to the A- Record primo.myinst.edu Ports and Communication The following table describes the ports used by each type of server: Server Primo Front End Port You can use port 80 or 443. The LB will forward the messages to server port 1701. Primo Back Office Use port 1443. The LB will forward messages to server port 1601. (Any requests to HTTP/1601 will be redirected to HTTPS/1443). PDS/ Shibboleth Use port 443. The LB will forward messages to server port 8991. Note: Prior to SSL configuration, you must decide whether access to the FE should be from both ports 80 and 443, or only from port 443. If access if give to port 443 only, you do not need to configure an auto-redirect from port 80 to port 443. 5

General Configuration for Primo Back Office Configuration Before starting the Back Office configuration: You must be running the Primo April 2015 release or a later release. You should have defined two DNS names: one for the FE and BE and another for the PDS. For each server listed in the table above, you must specify the external DNS name prefixed with https (instead of http), such as the following: https://pds-primo.myinst.edu https://primo.myinst.edu To configure SSL in the BE: 1 Open the General Configuration Wizard (Primo Home > Advanced Configuration > General Configuration Wizard) and select Installation from the Sub System dropdown list. 2 Refer to the following table to update the necessary parameters under the Installation subsystem: Parameter Registration URL Description Change the prefix of the URL to https. For example: https://registration.service.exlibrisgroup.com PDS_URL name for PDS. For example: https://pds-primo.myinst.edu/pds PDS_INTERNAL_URL name for PDS. For example: https://pds-primo.myinst.edu/pds PDS_CONFIGURATION_URL names. For example: https:// pds-primo.myinst.edu/pdsadmin/general_configuration. cgi?backlink=https://primo.myinst.edu/{backlinkurl}& backlinktext=authentication Configuration Reporting Base URL name. For example: https://primo.myinst.edu:1443/birt/frameset? report=report/ 6

Help Base URL reporting_base Deprecated. No change is needed. name. For example: https://primo.myinst.edu:1443/birt/ primo_admin_base name. For example: https://primo.myinst.edu:1443/primo_publishing/admin/ primo_base Search Statistics Report URL MFE_MASTER MFE_FRONTENDS Console Status URL Used internally. Do not update this URL. Not used. Do not update this URL. Used for internal calls (internal server names). Do not update this URL. Used for internal calls (internal server names). Do not update this URL. Used for internal calls in MaxThreadsFilter. Do not update this URL. 3 Click Save & Continue. 4 On the All Mapping Tables page (Primo Home > Advanced Configuration > All Mapping Tables), select Back Office from the Sub System drop-down list and edit the PDS Configuration mapping table. 5 Change the value of the production PDS URL parameter to the new CNAME and also change the prefix to https. 6 Click Save. 7 On the All Mapping Tables page (Primo Home > Advanced Configuration > All Mapping Tables), select Delivery from the Sub System drop-down list and edit the Templates mapping table. 8 Disable the amazon_thumb and PCamazon_thumb codes. 9 For the PCgoogle_thumb and google_thumb codes, change the prefix in the URL to https. 10 Click Save. 11 On the All Mapping Tables page (Primo Home > Advanced Configuration > All Mapping Tables), select Adaptors from the Sub System drop-down list and edit the Pushto Adaptors Configuration mapping table. 12 For the RefWorks adaptor, change the prefix in the URL to https. 13 Click Save. 7

14 On the Institution Wizard page (Primo Home > Ongoing Configuration Wizards > Institution Wizard), edit each institution that requires SSL. 15 In the Delivery Base URLs section, change the prefix for each URL to https. 16 On the Deploy All page (Primo Home > Deploy All), select all options and then click Deploy. Apache Configuration (PDS) To verify that PDS Apache is not configured to listen on port 443 and is listening on port 8991, enter the following command on the server: ps ef grep httpd The output should return the user that is running the httpd (apache). If it is the root, then you are probably running Apache on port 443 or 80 and no change is needed to modify the LB to redirect requests on port 443 to port 8991. In the Apache configuration file $primoe_root/apache/conf/httpd.conf, set the ServerName parameter to be the external DNS name used for PDS and prefix the URL with https. For example: https://pds-primo.myinst.edu For the following parameters in the PDSDefinitions file $primo_dev/pds/program/, update the PDS DNS and prefix the URL with https: server_httpsd server_pds pds_icon should use server_httpsd The PDS should listen on port 8991 since the LB will redirect requests from port 443 to port 8991. Test Cases for Verification 1 Access the Primo Front End by specifying its https link in a browser. For example: https://primo.myinst.edu 2 Perform searches and verify that Primo continues to display https in the browser s address after the results are returned. 3 Log on to the PDS by specifying its https link in a browser: For example: https://pds-primo.myinst.edu 4 After logging on to PDS, make sure that you are correctly redirected back to Primo using https. 5 In the Primo Front End, perform a Search, verify that all tabs of an item open, and verify that the Action > citation option displays citations. 8

6 Access the Primo Back Office by specifying its https link in a browser. For example: https://primo.myinst.edu:1443 7 Verify that you can run BIRT reports from the Primo Reports page (Primo Home > Primo Reports). 8 Verify that you can access the PDS Wizard (Primo Home > Ongoing Configuration Wizards > PDS Configuration Wizard). Known Issues The following issues are currently open: Access to PDS admin should be made directly through the PDS instead of the Primo Back Office. This issue is being addressed and should be fixed in an upcoming Primo release. If the Primo Front is configured with SSL, you will receive mixed content errors if you use external URLs (such as for Facebook, Amazon, and so forth). Additional Changes You should also make the following changes if they apply to your configuration: If you are running the monitoring on Primo, update the URLs and prefix each URL with https. Open a SalesForce case to inform Ex Libris of your new URLs and that you are using HTTPS. Troubleshooting If you are not able to access your servers: Try to telnet to port 443 and 1443 with each of your URLs. If you are not able to connect, this might be firewall issue. Verify that ports 443 and 1443 are open on the firewall. Verify that the server definitions on Primo using the Primo user (primourl). If it indicates HTTPS, then the environment is configured to use HTTPS. Verify that the BE and PDS configurations are configured as described in this document. General DNS and LB Configuration The section summarizes the configuration of the load balancer to support SSL. These instructions have been certified on an A10 load balancer, but except for the command syntax they should be similar for any modern LB (such as Cisco, F5, and so forth). Before making 9

any changes, make sure that your networking team has the knowledge to perform the configuration and that your network topology supports this type of configuration. 1 Use the naming convention described previously to create two DNS names: one for the BE and FE and another for the PDS. The DNS for the FE and BE should be the A record that points to the LB. The pds- record should be a CNAME that points to the A record. FE/BE: primo-<custid> PDS: pds-primo-<custid> 2 Create all relevant service groups for Primo (if they do not already exist). All should be Cookie persistent. Port 80: If the FE should be on port 443 then: Port 80 should redirect to port 443 (with aflex as below). If the FE should be on port 80 then: Port 80 should go to the 1701 service group. Port 443: If the FE should be on port 443, then port 443 should do hostname switching (see below) to the 8991 service group for the PDS and the 1701 service group for the FE. If the FE should be on port 80, then port 443 should go to the 8991 service group. Port 1443 should go to the 1601 service group (BO). Port 1601 should redirect to port 1443 (only if backward compatibility to the old BO URL is required). 3 Create one HTTP template with hostname switching: a In the Switching section, create two Hostname switching instances: The FE should go to the 1701 service group. The PDS should go to the 8991 service group. The match by should start with pds. b c d e Define the relevant service groups for the two instances in the HTTP template for port 443. Client IP Header Insert:: X-Forwarded-For Client IP Header Insert:: X-Forwarded-Proto:HTTPS Compression should be disabled. f Redirect Rewrite enabled on port 443. 4 Add aflex to the port 80 service group (HTTP redirect to SSL) port 80 - redirect-http-to-https # Redirect http to https request when HTTP_REQUEST { HTTP::redirect https://[http::host][http::uri] } 10

5 Add aflex to the port 1601 service group (BE HTTP/1601 redirect to HTTPS/1443) port 80 - redirect-http-to-https # Redirect http to https request when HTTP_REQUEST { HTTP::redirect https://[http::host][http::uri] } 6 View a sample configuration example for the following client-ssl template: slb template client-ssl c1 cert default.cert key default.key server-name www.site1.com cert site1.cert key site1.key server-name www.site2.com cert site2.cert key site2.key 11