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 support@oclc.org:
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 (support@oclc.org) 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 ezproxy@oclc.org 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 ezproxy@olc.org 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