Project Plan EZProxy

Transcription

1 Page 1 of 11: projectplan ezproxy.docx Project Plan EZProxy Contents Description... 1 Notes... 2 Installation... 3 Adding Resources To Access After Authentication... 6 Authentication Types: Restricting... 7 Authentication Types: multiple types example... 8 EZProxy URLs... 9 Resources... 9 Subject Matter Experts... 9 Definitions Modifications Description This document describes the installation of EZProxy, including configuration for using local, LDAP and Shibboleth authentication types, as well as restricting which IPs use which type. This document was produced using Version 6 (V6). See the 'Resources' section for a Visio visual of the parts.

2 Page 2 of 11: projectplan ezproxy.docx Notes Your purchase includes: A license key (WSKey) that you request from our website subscription for one year for the right to download new versions of EZproxy as they are released the right to transfer your WSKey between different platforms at any time permission to install your WSkey on non-production servers owned by your institution to test new configurations To run EZProxy, will need OCLC Web Service Key (WSKEY). WSKey will take effect immediately with no need to restart EZproxy. OCLC recommends following the outline below when implementing a new EZproxy instance Step Task Owner Notes / Other Info 1. Request WSKEY Systems Librarian / Main Contact Documentation and links to request WSKEY can be found here. 2. Process WSKEY request OCLC Orders Services Site will be notified once WSKEY is available. 3. Download executable to your server Systems Librarian / Server Admin Available here. Task assumes admin access to machine that will run EZproxy. 4. Provide the EZproxy server external IP address to all content providers Electronic Resources Librarian This is an additional IP address and should NOT replace any existing IP addresses you have on file with the provider. 5. DNS and Firewall Configuration IT/Network Team Internal and External DNS entries must be assigned to EZproxy server IP. Additionally, any ports it will use need to be open for external inbound and outbound traffic. Documentation can be found here under Initial Setup. You can test external DNS here. 6. Install and configure EZproxy Systems Librarian / Server Admin A walkthrough for each operating system is available at the download page. If not successful, confirm correct DNS and Firewall configurations are in place.

3 Page 3 of 11: projectplan ezproxy.docx 7. Configure resources Electronic Resources Librarian / Systems Librarian / Server Admin Database stanzas for resources that will be need to be added to the config.txt can be found here. If stanza is not available, first check the listserv and contact the content provider. If you still cannot locate a stanza, please contact OCLC. 8. Configure user authentication Systems Librarian / your Identity Management Team Depending on authentication method, you may need to consult and gather information from technical staff at your institution as well as adjust firewall/authentication settings to successfully configure the authentication method. 9. SSL certificate Systems Librarian / IT / Server Admin Not required for all resources but strongly recommended. Please review all related documentation before acquiring a cert and contact OCLC if you still have questions. 10. Testing Electronic Resources Librarian / misc. staff During this time you, change all links to e-resources on your institution s webpages to starting point URLs. These pages could include but are not limited to: A-to- Z lists, LibGuides, 856 links, course management systems, etc. 11. Managing EZproxy System Librarian / Electronic Resources Librarian / Server Admin This includes but is not limited to: security, login page customizations, log files, updates, server migrations, and SSL cert renewal. Installation Note: in adding lines to the config.txt and user.txt, it does not seem to matter the location where you put the lines. In our case, we placed the lines in sections near other similar information, like SSL near other SSL settings, and in user.txt, we placed settings at the end. Note: it is assumed you want to use SSL connections only and so these installation steps end up disabling port 80/non-SSL connections. Request WSKey o Create OCLC account o

4 Page 4 of 11: projectplan ezproxy.docx o Instructions for requesting WSKey o [website] click tab: Develop o [develop] click: Manage your API Keys o [manage API keys] click: Request a WSKey o [request a WSKey][Environment] change to: Production o [request a WSKey][Services] check: EZProxy o [request a WSKey][WSKey Name] enter name, ex: lccezproxywskey o [request a WSKey][What is the reason...] enter Institution Name, ex: o [request a WSKey][Registry ID] enter value (provided by OCLC ?) o [request a WSKey][Symbol] enter value (provided by OCLC ?) o [request a WSKey][Redirect URI] [skip] o [request a WSKey][Usage] [skip] o [request a WSKey][Terms and Conditions] click: I agree... o [request a WSKey] click: Create Request (should receive 'Successfully submitted...') o OCLC doc says it will take 1-2 days to process o Once you receive, you only need to copy/paste the key, not the Secret Download installation program o o ex: exproxy-windows.exe Configure internal/external DNS to EZProxy IP create folder on drive 'ezproxy' copy installation exe (ezproxy-windows.exe) into that folder rename ezproxy-windows.exe to ezproxy.exe from command prompt, run: ezproxy.exe -m Allow windows firewall exception for Ezproxy Edit config.txt and add line after "# Name My.ezproxy.server" o Name [your URL], ex: ezproxy.ourcollege.edu Edit config.txt and remove remark character '#' from line "# LoginPortSSL 443" o LoginPortSSL 443 Test connection works, use command: ezproxy -c Edit user.txt and add line for testing Install WSKey by supplying the WSKey value provided in the command, replacing "[...]" with your key value: ezproxy -k [...] run: ezproxy.exe

5 Page 5 of 11: projectplan ezproxy.docx Test using non-https, ex: Turning on SSL with a CA certificate o Click: Manage SSL (https) certificates o Click: Import Existing SSL Certificate o Paste public (CER) text from your CA certificate in first box (Certificate) o Paste private key (Key) text from your CA certificate in second box (Key) To export private key/public certificate from PFX (using OpenSSL): openssl pkcs12 -in certname.pfx -nocerts -out key.pem -nodes openssl pkcs12 -in certname.pfx -nokeys -out cert.pem openssl rsa -in key.pem -out server.key o Type ACTIVE in the ACTIVE box and click 'activate' To install as Service, run Command Prompt As Administrator, run: ezproxy.exe -si o Note: we found it handy to just run EZProxy from command line with 'ezproxy.exe' to look for any errors/etc, then add it as server once it was running smooth. Then start the service: NET START EZProxy To remove the service, run: ezproxy.exe -sr To set LDAP authentication, use link Test LDAP o Bind user: full account for connecting to AD, ex: ouruser@ourcollege.edu o Bind password:... o LDAP Version check: 3 o Host: we used the IP of a DC o Search Base: DC=ourcollege,DC=edu o Search Attribute: samaccountname o Test user: jdoe (do not include domain portion, 'jdoe' is just an example) o Test password:... o Click: search (should see AD attributes for that user) o Copy the lines at the bottom use the "To use this LDAP search with EZProxy..." that start with "::LDAP", until /LDAP o In user.txt Paste the ::LDAP to /LDAP lines Example: ::LDAP BindUser [user for querying AD]@ourcollege.edu BindPassword -Obscure [...] URL ldap://[your DC]/DC=ourcollege,DC=edu?sAMAccountName?sub?(objectClass=person)

6 Page 6 of 11: projectplan ezproxy.docx IfUnauthenticated; Stop /LDAP Note: to allow IT to still use the EZProxy admin console, we recommend using the steps detailed in the 'Restricting Authentication Types' section. To set Shibboleth authentication o Copy your Shibboleth Metadata file into the same folder as the ezproxy.exe o In config.txt Create this section ShibbolethMetadata \ -EntityID= idp url]/idp/shibboleth \ -File=idp1MetaData.xml \ [-Cert=1 \] [-URL= idp url]/idp/shibboleth \] o In user.txt Create this section ::Shibboleth IDP13 /Shibboleth Note: to allow IT to still use the EZProxy admin console, we recommend using the steps detailed in the 'Restricting Authentication Types' section. o Restart EZproxy o Click on Manage Shibboleth Click EZproxy Metadata Copy file to your IdP Shibboleth server in the folder C:\Program Files (x86)\shibboleth\idp\metadata o On your IdP Shibboleth server In metadata-provider.xml, add this section: <MetadataProvider id="ezproxy" xsi:type="filesystemmetadataprovider" metadatafile="%{idp.home}/metadata/ezproxy-sp-metadata.xml" /> Provide EZProxy external IP to all content providers Adding Resources To Access After Authentication

7 Page 7 of 11: projectplan ezproxy.docx There are many attributes that can be used to define a resource (see the Resources section for the EZProxy Manual link). These are the basic ones that should be used: Title: Name of the resource to show on the../menu page after authentication, if no resource URL originally provided by the request URL: what URL serves the resource, is proxied DomainJavaScript: what JavaScript references to replace EZProxy rewrites links, including JavaScript resources/etc. when proxying a resource. Just add as many resources as desired inside the config.txt file, within the 'Database Definitions' section. Example: Title Alma URL DomainJavaScript ourcollege.alma.somegroup.com Once you have resources (aka databases) defined, you can create links directly to the EZProxy login for that resource, so that after authentication, the user is routed to that resource. This URL is an example of logging into the Example resource above. If you want users to get a 'list' of resources after log-in that they can choose from, provide a link in the following syntax: Authentication Types: Restricting To restrict certain authentication types, you can include either 'IfIP' or "Not IfIP' to allow or block an authentication type from being used. IfIP Syntax: IfIP [first IP],[other IPs]; Stop Not IfIP Syntax: Not IfIP [first IP],[other IPs]; Stop

8 Page 8 of 11: projectplan ezproxy.docx The above lines tell EZProxy, if IP matches condition, then 'stop' evaluating this section. Example: avoiding Shibboleth authentication on computers you want to be able to log into the 'admin' EZProxy portal using the 'user.txt' credentials. This would prevent IP and from using Shibboleth: ::Shibboleth IfIP , ; Stop IDP13 /Shibboleth Authentication Types: multiple types example This configuration shows how to have multiple authentication types, i.e. local, LDAP and Shibboleth, restricting what IPs can use what type, and who is/is not an admin after authentication. In this example, the following conditions will happen: local o a local account (in the config.txt) is defined o it only becomes an admin when used through specific IPs LDAP o only available to a single IP o if authenticated, becomes an admin Shibboleth o disabled for three IPs, but, allowed on all others In this example, the IPs listed are as follows: : local to the EZProxy server : public IP to the EZProxy server : a remote IT Admin workstation Not IfIP , ; Stop ourlocaluser:ourlocalpassword:ip= ; ,admin ::LDAP Not IfIP ; Stop BindUser ouruser@ourcollege.edu

9 Page 9 of 11: projectplan ezproxy.docx BindPassword -Obscure... URL ldap://ourdc/dc=ourcollege,dc=edu?samaccountname?sub?(objectclass=person) IfUnauthenticated; Stop admin /LDAP ::Shibboleth IfIP , , ; Stop IDP13 /Shibboleth EZProxy URLs Some common URLs within EZProxy. Admin Console Login List Of Link Resources After Logged In Resources Subject Matter Experts David Mielcarek dmielcarek@lowercolumbia.edu

10 Page 10 of 11: projectplan ezproxy.docx projectplan ezproxy-flow.pdf Details a visual flow of the parts. EZProxy Product Site EZProxy Reference Manual EZProxy Download/Install EZProxy LDAP Configuration EZProxy config.txt URL correction Default config.txt has this URL: the correct URL is: EZProxy [ur]/menu URL correction Default [url]/menu has this URL: the correct URL is: Shibboleth IdP/SP Installation Definitions CA - Certificate Authority EZProxy - Proxy resources for end users

11 Page 11 of 11: projectplan ezproxy.docx SSL - Secure Socket Layer WSKEY - OCLC Web Service Key Modifications NAME DATE MODIFICATION David Mielcarek 5/24/2017 Created David Mielcarek 6/6/2017 Removed disabling non-ssl port, as EZProxy uses non- SSL on redirection after authentication David Mielcarek 6/7/2017 Added corrected config.txt URL from oclc.org support staff End of document