EZproxy Authentication
Authentication for WorldShare Management Services Revised March 3, 2015 Table of Contents Purpose ................................................................................................................................................................................... 2 Certificates .............................................................................................................................................................................. 2 Information you send so OCLC can install a certificate ...................................................................................................... 2 Issues that cause loss of access to WMS ............................................................................................................................ 2 Scheduling an OCLC install of a certificate .......................................................................................................................... 2 Offline Circulation client ..................................................................................................................................................... 3 User Authentication (patron & staff) ...................................................................................................................................... 4 1 CAS Authentication .......................................................................................................................................................... 4 2 LDAP Authentication ........................................................................................................................................................ 5 Shibboleth Authentication .................................................................................................................................................. 6 EZproxy Authentication .......................................................................................................................................................... 7 1 OCLC IDM and EZproxy .................................................................................................................................................... 7 2 EZproxy and WMS Third Party Authentication (LDAP, CAS, or Shibboleth) .................................................................... 7 3 Before you begin .............................................................................................................................................................. 7 4 Integration process .......................................................................................................................................................... 7 5 Testing and Support ......................................................................................................................................................... 9 Purpose This document provides instructions to the library on how to set up CAS, LDAP, Shibboleth, or EZproxy authentication. Certificates Third-party authentication services (LDAP, CAS, Shibboleth, etc.) use webserver certificates for security handshakes with other services. In this context, there are two kinds of certificates: 1. Certificates created with a commercial Certificate Authority (CA). OCLC can recognize these without further information from you. 2. "Self Signed" certificates. OCLC needs the Certificate Authority your Information Technology department used to sign the certificate. Certificates are valid for a limited time. If self-signed certificates expire or are updated without informing OCLC, you lose access to WMS. Information you send so OCLC can install a certificate Your Information Technology department must send OCLC the Certificate Authority (CA) certificates for your third-party authentication services. Using CA certificates can reduce the risk of an expiring certificate causing a service outage. Before installing a certificate at your library, send this information to [email protected]: 1. CA certificates in Private Enhanced Mail (PEM) format 2. The expiration date and predicted date of installation of the certificate at your institution a. Certificates are usually valid from 1 to 5 years b. CA certificates can be valid for up to 20 years c. If sending self-signed certificates, make them valid for as long as possible (5 years minimum) 3. Any of the situations listed in Issues that cause loss of access to WMS Issues that cause loss of access to WMS To ensure access to WorldShare Management Services (WMS), you must notify OCLC ([email protected]) prior to any changes to your library’s self-signed certificates or configuration, such as: 1. 2. 3. 4. 5. 6. 7. Certificates expire Certificates are updated Certificates are changed, which means the CA certificates/intermediate (chained) certificates are no longer valid Updates to the bind user’s name or password Port changes IP address changes In some cases, OCLC needs to adjust firewall access a. If your LDAP configuration requires a bind user for interoperation, work with your IT department to choose a suitable duration and expiration date for the bind user. If the bind user expires, authentication to OCLC services will fail Scheduling an OCLC install of a certificate OCLC must schedule an install to update a certificate. Installs can usually be scheduled no sooner than two weeks after OCLC receives your email containing the information listed above. OCLC can install certificates in advance of their installation at your library without interrupting your access to WMS. If you have lost access to WMS as a result of an expired or updated certificate, send the information listed above to OCLC Support so OCLC can restore WMS. Authentication.docx 2 March 3, 2015 Offline Circulation client Install the Offline Circulation client as a precautionary measure. The client allows you to circulate items if WMS is not accessible. More information on Offline circulation is available here: 1. Set up the Offline Circulation client: http://www.oclc.org/support/help/circulation/default.htm#Checkin_checkout/offline_client.htm (Includes requesting a WS key) a. Set-up Offline Circulation Tutorial (sign in required): https://www.oclc.org/support/worldsharemanagement-services/tutorials/setting-offline-circulation-client-tutorial (Includes requesting a WS key) b. Using Offline Circulation Tutorial (sign in required): https://www.oclc.org/support/worldsharemanagement-services/tutorials/using-offline-circulation-tutorial Authentication.docx 3 March 3, 2015 User Authentication (patron & staff) 1 CAS Authentication Follow this checklist to set up your institution’s CAS system for patron and staff authentication. CAS versions other than CAS2 may not be supported. Contact OCLC to confirm support of your version of CAS. Test and production servers OCLC strongly recommends setting up a test server and a production server for security and patron privacy reasons. 1. Confirm OCLC access for your institution’s CAS server OCLC works with your institution to access your servers from these OCLC URLs: Environment Test OCLC server URL https://authn.sd00.worldcat-ci.dev.oclc.org/wayf/metaauth-ui/cmnd/protocol/acs/saml2 https://authn.sd00.worldcat-ci.dev.oclc.org/wayf/metaauth-ui/cmnd/protocol/acs/cas2 Production https://authn.sd00.worldcat.org/wayf/metaauth-ui/cmnd/protocol/acs/cas2 2. Provide contact information, URLs, account credentials, and IP addresses Send this information for your test or production accounts to your OCLC Implementation manager: a. Contact information for your CAS server administrator b. URLs for your CAS servers c. The range of IP addresses for CAS servers and any failover and backup environments (OCLC uses these addresses to ensure continuous service) d. Username and password for your CAS servers. Note: The username and password for your production server must be retained after set up is complete so OCLC can provide ongoing support. OCLC will set up the appropriate configuration to test authentication in test and production environments. Note: If a non-standard port is used, a firewall change is required. 3. Confirm connection to the test environment and approve access to CAS production server After OCLC confirms the connection to the test URLs, you approve access to your CAS production URLs. 4. Prepare for ongoing updates for your patron data files. Using CAS authentication with WMS requires that you provide the CAS identifier in your patron data file. Use the Patron Persona XML schema for sending patron data: https://www.oclc.org/support/worldshare-management-services/documentation/data-migration/patron-personaxsd-elements Required patron XSD element idAtSource Data We need to have a persistent identifier for each patron. Provide an eduPersonTargetedId if at all possible. http://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-direduperson-200806.html sourceSystem entityId uniquely indicating the system the patron data came from. If you do not already have one, OCLC can provide a suggestion. Note: Make sure that the production test user is always included in your patron data (from note in step 2d). Authentication.docx 4 March 3, 2015 Patrons who are not in your CAS system WMS currently offers single-source authentication. If there is no CAS record available, the patron record will have to be created in the WMS system. These users will not be able to log-in to WMS, but they can still check out items. 2 LDAP Authentication Follow this checklist to use your institution’s LDAP system for patron and staff authentication. OCLC only supports secure LDAP implementations. Contact OCLC to confirm support for your implementation of LDAP. Test and production servers OCLC strongly recommends setting up a test server and a production server for security and patron privacy reasons. Checklist 1) Open ports in your institution’s firewall for OCLC IP addresses: 132.174.8.0/24 and 132.174.100.8 (Production) 198.137.189.0/24 (Hot site and Pre-production testing) 132.174.100.114 and 132.174.255.6 (Development servers for first round of testing) 2) Provide URLs, IP addresses, credentials, and SSL and LDAP information Send this information for your test and production accounts to your OCLC Implementation Manager: a. Contact information for your LDAP administrator b. URL. If the production URL starts with “ldap:” rather than “ldaps:”, then LDAP with StartTLS will be assumed. c. Range of IPs for your LDAP server(s) (include the current server and any failover or backup environments) d. Credentials (username and password). Send bind user and passwords if they are required. Send test credentials for each environment to be integrated (test and production). The username and password for your production server must be retained after set up is complete so OCLC can provide ongoing support. e. Required SSL information i. Provide the Certificate Authority (CA) certificate(s) for the SSL server certificate for your LDAP server. Updated, expired, or changed certificates break LDAP. Notify OCLC of any certificate changes before making them. f. Required LDAP information: i. cnAttributeId: The name of the attribute you will use to supply a username ii. idAttributeId: The name of the attribute you will use to supply the persistent user id, which could be the same as above, but we would much prefer an opaque identifier such as a eduPersonTargetedId. iii. baseDN: please provide two examples of the distinguished name for users in your system. 3) Prepare for ongoing updates for your patron data files. Using LDAP authentication with WMS requires that you provide the LDAP account identifier in your patron data file. Use the Personas XML schema for sending patron data: https://www.oclc.org/support/worldshare-management-services/documentation/data-migration/patron-personaxsd-elements Required patron XSD element idAtSource sourceSystem Data This is the persistent id for the user as given in the idAttribute The entityId uniquely indicating the system the patron data came from. If you do not already have one, OCLC can provide a suggestion. Note: Make sure that the production test user’s patron data record is always included in your patron data file (from step 2d). Authentication.docx 5 March 3, 2015 Patrons who are not in your LDAP system WMS currently offers single-source authentication. If there is no LDAP record available, the patron record will have to be created in the WMS system. These users will not be able to log-in to WMS, but they can still check out items. Using EZproxy Contact [email protected] to request assistance. If you manage your own EZproxy server, OCLC will provide you with a configuration file that you can install on your server. If you are a Hosted EZproxy customer, OCLC will make the configuration changes on your behalf. See section “2 EZproxy Authentication” (below) for more information. Shibboleth Authentication OCLC provides authentication support for WMS using your Shibboleth Identity Provider (IdP). This configuration provides Shibboleth compliant interaction and does not require firewall changes at your institution. OCLC’s IDM looks like a standard Shibboleth Service Provider (SP) to your Shibboleth IdP. 1) Information required from your institution OCLC configure access in both a development and production environment. Each environment requires: a. Contact information for your Shibboleth administrator b. Shibboleth-related metadata. This metadata usually defines Shibboleth endpoints and contains the relevant security certificates. Normally this data also contains the IdP’s entity ID. c. Valid credentials (username and password) for testing d. Persistent Id which will be presented from Assertion/Subject/NameID from the institution’s SAML response 2) Information OCLC will give your institution a. The entity ID for our SP. It will be the same for the test and development environments. b. Shibboleth-related metadata 3) Implementation steps a. Exchange Shibboleth-related metadata as described above b. Confirm connectivity to development environment c. Ensure your patron data is loaded into the production environment (the production install cannot be performed until this step is complete) d. Confirm connectivity to production environment e. Negotiate production install date with OCLC f. Confirm any support for single logout as implied by the institution’s metadata 4) Prepare for ongoing updates for your patron data files. Using Shibboleth authentication with WMS requires that you provide the Shibboleth identifier in your patron data file. Use the Patron Persona XML schema for sending patron data: https://www.oclc.org/support/worldshare-management-services/documentation/data-migration/patronpersona-xsd-elements Required patron XSD element idAtSource sourceSystem Data This identifies your Shibboleth user to OCLC IDM. We expect this to be an eduPersonTargetedId. The entity ID of your IdP Note: Make sure that the test user is always included in your patron data. Patrons who are not in your Shibboleth system WMS currently offers single-source authentication. If there is no Shibboleth record available, the patron record will have to be created in the WMS system. These users will not be able to log-in to WMS, but they can still check out items. Authentication.docx 6 March 3, 2015 EZproxy Authentication 1 OCLC IDM and EZproxy The OCLC Identity Management Infrastructure (IDM) provides standards-based, scalable, secure authentication, authorization, and patron data services for Worldshare Management Services and other OCLC services. This infrastructure is implemented as a Shibboleth-compliant SAML V2 service. EZproxy is configured to authenticate to WMS using the Shibboleth authentication directives. In the EZproxy configuration, EZproxy serves as a Shibboleth Service Provider and the OCLC IDM infrastructure serves as the Identity Provider (IDP) for WorldShare Management Services. Note: EZproxy cannot be used as the Authentication source for WMS. 2 EZproxy and WMS Third Party Authentication (LDAP, CAS, or Shibboleth) If you are using WMS third party authentication and you are using your institution’s LDAP, CAS, or Shibboleth server for staff and patron authentication, then you can configure EZproxy using the following options: 1. LDAP If you are using your institution’s LDAP server, you can configure EZproxy either to directly access your LDAP server via EZproxy’s LDAP:: configuration statements or to access WMS. a. If you configure EZproxy to directly access your LDAP server, then your staff and patrons will see the EZproxy login screen and will enter their LDAP credentials. b. If you configure EZproxy to authenticate against WMS, then you have the added benefit of having single sign-on between EZproxy and WMS. Since WMS is configured to authenticate against your LDAP server, your staff and patrons will use their LDAP credentials in WMS and EZproxy. In this case, your EZproxy users will see the WMS login screen and will enter their LDAP credentials. 2. Shibboleth or CAS If you are using your institution’s Shibboleth or CAS server, then you configure EZproxy to directly access your institution’s Shibboleth or CAS server using EZproxy’s Shibboleth or CAS directives. 3 Before you begin This document assumes that your EZproxy administrator understands: Basic Shibboleth vocabulary and concepts How to configure Shibboleth Service Provider facilities using EZproxy How to configure Shibboleth authentication using EZproxy Security certificates EZproxy must be installed with a web server certificate so it can provide secure login (https/SSL). This certificate should not be a self-signed certificate. If you use Option ProxyByHostname, use a wild-card certificate. Shibboleth requires a certificate be installed into EZproxy for Shibboleth signing and encryption processes. Use the EZproxy Administer Certificates facility to generate a long-lived (5-10 year) self-signed certificate for this purpose. System requirements EZproxy version 5.6 or higher 4 Integration process In order to connect your EZproxy server (a Shibboleth Service Provider) to the IDM system used by WMS (a Shibboleth Identity Provider), the information below needs to be exchanged between OCLC and your institution. Authentication.docx 7 March 3, 2015 Information you send to OCLC 1. Send your Shibboleth 2.0 Assertion Consumer Service (ACS) URL to your WMS Implementation manager. a. Login to your institution’s EZproxy system as an Administrator. The ACS URL is on the Manage Shibboleth page. Example: Configuration Information Shibboleth 1.3 Assertion Consumer Service URL Shibboleth 2.0 Assertion Consumer Service URL https://login.vcfal.idm.oclc.org/Shibboleth.sso/SAML/POST https://login.vcfal.idm.oclc.org/Shibboleth.sso/SAML/POST Information OCLC sends you: This information is handled differently, depending on your version of EZproxy: EZproxy version Licensed (installed at institution) Hosted How changes are handled OCLC sends files as below OCLC changes files for you Procedure for licensed Ezproxy users If you are a licensed EZproxy site with EZproxy running at your institution, OCLC will supply you with the following files: a. Certificate and key that you will install as your Shibboleth encryption and signing key. Since the key needs to be private and secure, OCLC will arrange a secure transfer mechanism for you (the key will not be emailed). b. A metadata.xml file that contains the IDP metadata that EZproxy needs to access the IDP. Install these files: 1. Install the certificate and key into EZproxy. a. On the EZproxy Administration page, click Manage SSL (https) certificate. b. On the Manage SSL (https) Certificates page: i. Click Import Existing SSL Certificate and copy the certificate and key into the boxes. ii. Write down the certificate number (ID) for this newly-imported certificate. 2. Copy the metadata.xml file to the EZproxy installation directory. 3. In the config.txt file, make sure: a. The parameter file= contains metadata.xml. b. The entity ID supplied by OCLC that you used to configure your EZproxy server for Shibboleth is correct. c. The certificate ID of the certificate you imported is on the Cert= parameter. Example: ShibbolethMetadata \ -EntityID=urn:mace:oclc:idm:vcfalibrary \ -file=metadata.xml \ -Cert=2 4. In the user.txt configuration file, in the stanza below, make sure the IDP20 configuration statement contains the same entity ID as in the config.txt file: ::Shibboleth IDP20 urn:mace:oclc:idm:vcfalibrary (the entity ID supplied by OCLC) /Shibboleth 5. If the institution also uses Navigator, in the shibuser.txt configuration file the session variables must be populated for the userObject (only for Navigator Institutions). Contact OCLC for more details. Authentication.docx 8 March 3, 2015 5 Testing and Support Restart EZproxy and test with a patron credential from the WMS database. For support, please contact [email protected] or your WMS implementation team member. For full, detailed information, see the Shibboleth authentication directives at http://www.oclc.org/support/documentation/ezproxy/usr/shibboleth.htm. Authentication.docx 9 March 3, 2015
© Copyright 2024