EBL Authentication Ebooks Corporation

EBL Authentication Ebooks Corporation Ebooks Corporation Limited Washington D.C. 7406 Brookville Road Chevy Chase, MD 20815 USA Tel: +1 (301) 951-8108 Fax: +1 (240) 235-7017 Perth 62 Bay View Terrace Claremont WA 6010 Australia Tel: +61 (0)8 9385 5851 Fax: +61 (0)8 9385 5755 Melbourne 2/3 Robe Street St Kilda VIC 3182 Australia Tel +61 (0)4 3993 9943 Fax +61 (0)3 9534 7017

Table of Contents 1 INTRODUCTION...3 Overview...4 2 AUTHENTICATION INTEGRATION...6 IP-Address Configuration...6 Unique Identifier...6 EZProxy...7 EZProxy Versions...7 Configuration forezproxy 3.0 and 3.1...7 Configuration for EZProxy 3.2...8 Athens Authentication... 10 Setting up Athens...10 Shared Secret... 11 Outline...11 Detailed Design...12 Token Based Authentication... 14 Token...14 Validation...14 Log-in Authentication... 15 Creating patron upload file...15 Uploading patron file...15 Customised permissions based on patron type...16 Download Permission Configuration- internal vs. external access...16 Global On/OFF...16 IP Based...17 Token Based...17 Copyright 2005, Ebooks Corporation Limited

1 Introduction In setting up authentication to your library s EBL portal, our aim is to protect patron privacy while ensuring secure Digital Rights Management (DRM) and comprehensive usage statistics. Seamless authentication also ensures that use of your ebook collection is reserved only for access by recognized patrons of your library. Wherever possible, we will work with you to integrate with your library s existing authentication procedures. To that end, EBL has designed its authentication processes to be broadly compatible with existing library authentication and can work with your library directly to find a streamlined way to use your existing authentication systems. Access to EBL is generally managed using a combination of IP recognition and some form of user ID. If your library is able to refer patrons to the EBL portal from a common IP range, then we will restrict access to the IP range you specify. This can be facilitated through a proxy server, VPN access or other process. IP restriction guarantees that use of your ebook collection is limited to patrons coming from your network. In order to properly manage circulation of ebook and copyright permissions per use, EBL requires that each patron accessing Ebook Library is authenticated and passed through with some form of unique identifier. EBL offers a variety of user authentication methods, customized to the existing technology and processes of each of our library customers. This document highlights some of the more commonly deployed authentication methods, including: Integrated EZProxy encrypted authentication Athens Authentication Token based Authentication Shared Key Direct Patron login These processes are explained in this document. Please peruse all and choose the best one for your set up. In each case, we have provided a few examples of how we have integrated with libraries existing authentication protocols. This document deals only with authentication processes for the patron portal. Access to LibCentral, our library management portal, uses direct log-in. Copyright 2005, Ebooks Corporation Limited 3

Overview To verify a patron s identification and access permissions, EBL controls DRM settings at the individual patron level. The EBL system utilizes a combined method of IP recognition plus individual identification, via a unique, consistent, and privacy-sensitive identifier. The authentication system works as follows: The patron s IP range is checked against the registered IP address of the library. 1. If the IP address is within the range, or none has been specified, then they pass to the authentication strategy check. 2. If the IP address is incorrect, then the system checks whether they have an authentication URL entered into the system settings (this would generally be the local library log-in screen) and they are sent to that URL for authentication and rechecked for the IP-address range. 3. If they don t have an authentication strategy, they are denied access. 4. After the IP check is passed, the authentication strategy is checked. Copyright 2005, Ebooks Corporation Limited 4

5. In the event that the library has not elected to set up an integrated authentication process, the system will default to EBL s Direct Patron Login, which asks the patron to enter an individual user name and password for access to the EBL Patron site. However, more commonly, libraries elect a more streamlined and seamless process of integrated authentication. Using integrated authentication, EBL communicates behind the scenes with the library s own systems to obtain unique log in details and/or patron authentication. For example: If the library has an OPAC or LDAP system that the patron logs into, the log in details can be passed to EBL as a parameter in the URL string or via other methods. If the library uses EZProxy, this identifier will be one-way encrypted during the referral process to ensure that the patron s identify is completely anonymous and untraceable once it reaches the EBL system. If the library uses Athens or another user system for example, the EBL server will contact the Athens server to verify the user s identification. Once the user ID is authenticated via one of these routes, the patron is considered approved and is taken directly into the to the requested ebook record or to the EBL welcome page. Copyright 2005, Ebooks Corporation Limited 5

2 Authentication Integration The following section outlines several different methods of connecting to EBL depending on your current library authentication or login system. We are developing new methods continually and understand that each library system is unique. We are willing to work with libraries, listening to their individual requirements, in order to customize an authorization procedure that best fits their needs. If you have EZProxy or Athens authentication, please refer to these sections, below. If you use another authentication system, EBL s token-based system may be your best starting point. Or, if none of these scenarios applies, you may want to consider EBL s Direct Patron Login or discuss with your account manager a customized solution to suit your requirements. In addition to providing you with this authentication reference document, it is customary to plan an initial-stage conference call between your systems staff and our technicians to discuss your requirements and issues and plan a best-way forward together. Some basics: IP-Address Configuration It is recommended that this additional security check is used if possible. If your library is able to supply a limited list of IP addresses from which your patrons will be accessing EBL, we will restrict access to only allow requests coming from those IP addresses. Libraries can have one or more ranges of IP addresses, as well as one or more specific IP addresses. There is no limit to the number of ranges or specific IP addresses that can be used. If available, please provide your account manager with the required IP Addresses. Unique Identifier A unique identifier is required for each patron who accesses the EBL system. This is used to control DRM rights for that user and to differentiate between patrons using the same inhouse library computers. If the authentication is conducted on the library s own system, a unique, encrypted identifier will be passed through to EBL at the time of requested access. This identifier can be a student number or any other consistent, unique ID. It can be encrypted to assure the patron s anonymity, provided that the information passed through is the same for that user on subsequent visits to the EBL system. Copyright 2005, Ebooks Corporation Limited

EZProxy If your library is using EZProxy as an intermediary server between your library s patrons and licensed content providers, the process generally occurs as follows: 1. Your patrons connect to EZProxy 2. The EZProxy system communicates with your licensed content provider or database system 3. The requested content (userid) is sent to EBL via EZProxy for patron access Since EZProxy runs on a machine located on your network, EBL sees the requests as coming from an IP address on your network and permits access. This is what EBL calls Web Authentication. EZProxy Versions Any version of EZProxy will work, but there are a few options depending on which version you have. The difference are summarised as: 3.0a or previous The standard version of EZProxy (previous to 3.0a GA) will send the information to EBL unencrypted. 3.0a GA (Encryption) To encrypt this information, EZProxy versions 3.0a GA and later contain the functionality to allow userid to be encrypted before being passed to EBL. To use the encrypted method, download the updated version of EZProxy: http://www.usefulutilities.com/download/?version=20040618 In the encrypted version, the EZProxy admin menu displays a new "Decrypt User Variable" option whenever EncryptVar appears in ezproxy.cfg. This option allows the EZProxy administrator to enter an encrypted value and see what the original plain-text value was. 3.2 (Security) Version 3.2 has added security for a library which adds a key to the authentication message sent to EBL. This key is also stored by EBL to verify that the user has come from the library authentication system which matches the URL that they re accessing. http://www.usefulutilities.com/download/?version=20050403 Configuration for EZProxy 3.0 and 3.1 These are the configuration changes needed for Ebook Library to be recognized as a database by EZproxy. 1. The file ezproxy.cfg will require an addition entry, as follows. Title Ebook Library URL http://library.eblib.com/eblweb/patron.html?userid=^u Domain eblib.com Copyright 2005, Ebooks Corporation Limited 7

2. Modifications in ezpauth.pl, StartSession: Make sure the variable loguser is included in the $query variable. The value for loguser is used to pass the userid onto Ebook Library. Case Study Curtin University has successfully integrated their EZProxy 3.0 with EBL s system. The following is an explanation of their set up. -----------------XX----------------- To pass the userid in the first place we needed to modify our login scripts to collect the userid and then pass it to EZproxy in the loguser variable. EZproxy then encrypts the value and places it wherever the ^u is located in the URL. The ezproxy.cfg file needed to have the option turned on to deal with userid being passed. The entry to added was OPTION LOGUSER The configuration for EBL: Title EBL EncryptVar u astringwechose URL http://curtin.eblib.com/eblweb/patron.html?userid=^u DJ eblib.com HJ 203.188.156.93 HJ 203.188.156.94 HJ 203.188.156.80 HJ 203.188.156.80:8080 -----------------XX----------------- Configuration for EZProxy 3.2 These are the configuration changes needed for Ebook Library to be recognized as a database by EZproxy. 1. The file ezproxy.cfg will require an addition entry, as follows. Title ebook Library EBLSecret asecretstring URL http://www.une.eblib.com.au/eblweb/patron/?userid=^u DomainJavascript eblib.com 2. Modifications in ezpauth.pl, StartSession: Make sure the variable loguser is included in the $query variable. The value for loguser is used to pass the userid onto Ebook Library. Case Study University or New England has successfully integrated their EZProxy 3.2 with EBL s system. The following is an explanation of their set up. -----------------XX----------------- Copyright 2005, Ebooks Corporation Limited 8

To pass the userid in the first place we needed to modify our login scripts to collect the userid and then pass it to EZproxy in the loguser variable. EZproxy then encrypts the value and places it wherever the ^u is located in the URL. The ezproxy.cfg file needed to have the option turned on to deal with userid being passed. The entry to added was OPTION LOGUSER The configuration for EBL: Title ebook Library EBLSecret asecretstring URL http://www.une.eblib.com.au/eblweb/patron/?userid=^u DomainJavascript eblib.com DomainJavascript eblib.com.au DomainJavascript 203.188.156.* -----------------XX----------------- Copyright 2005, Ebooks Corporation Limited 9

Athens Authentication Athens is a central repository of organizations, usernames and passwords with associated rights. It has extensive account management facilities for organizations to create and manage usernames and passwords, and to allocate rights to individual usernames. The following diagram provides a detail on how a user is authenticated in Athens. (Ebook Library is the DSP service). 1. A library subscribes to the DSP (EBL), and is allocated a customer reference with associated rights. 2. EBL informs Athens that this library now has access to EBL. 3. When a patron tries to view a page on EBL, we send the patron to the Athens Authentication Point (AAP). The AAP is managed by Athens, and provides a central login form for the patron to enter their Athens credentials. 4. The patron enters their username and password at the AAP, and is sent back to EBL. 5. EBL then decides if the user has the correct permissions to access. Setting up Athens Please provide your account manager with your Athens name and organizational identifier. If you aren t registered with Athens and would like to join, the Athens website contains all the information needed. To register for Athens see their web page http://www.athensams.net/sitereg.html Copyright 2005, Ebooks Corporation Limited 10

Shared Key When a library student or staff user searches for a book in their online catalogue they will be presented with a link to EBL if that book is also available in ebook format. When they click this link, a server process, to be developed and run on Library s servers, will check to see if the current user is authenticated within their OPAC System. If they do not have a current active session, a login will be required, after which their request will be forwarded to EBL for processing. Attached to that request by the CGI process will be a series of required parameters that together as a whole will ensure the integrity of the access request. EBL will be able to process these parameters and know with a surety that the request originated from an authenticated library user. This process will be encapsulated within a single request that will be able to both Authenticate and Authorise access to requested resource. The key to the single request Authentication and Authorisation procedure shall be known as a Shared Secret. This will be an agreed value/token/string between the library and EBL that will be used as a Seed value to the encryption process to provide a hash value parameter on each request. Without knowledge of this shared key it is impossible to generate an identical request and gain access to EBL. Outline The following diagram outlines the steps involved in performing the seamless login into EBL for both internal and external library staff and students. User clicks Proxified URL link in their Catalogue search results to view the ebook in EBL Internal Library Users Library Catalogue External Library Users CGI Authentication Server Adds the following Parameters to the Request if the user is successfully Authenticated: 1. Unique User Id 2. UNIX Timestamp 3. Hash value of previous three (3) parameters plus the shared secret key. Shared Secret eg: F942E4C8A76EE0A1 Ebook Library Processes request with Authentication Parameters: 1. Regenerates Hash value with Shared Key 2. Compare result with the received hash 3. If All values match the user is Authorised to access EBL and a new session is created. Access is granted. Otherwise, the user is returned to a known Authentication URL where they must establish their credentials. Library / EBL Patron Authentication Process Copyright 2005, Ebooks Corporation Limited 11

Detailed Design The following authentication protocol is dependant on both EBL and the Library holding the Shared encryption seed key. 1. A Library user (either staff or student) searches for a book within the online catalogue. 2. They click the search result to view the full details of that book. 3. If the selected book is one that the library has purchased for their EBL catalogue, then when the page is rendered, there will be an additional link on the page to access the ebook version of the title within EBL. 4. This link will be a Proxified Link meaning that it contains the URL of the Library s CGI Authentication Server, along with enough information to determine where to send the user once their credentials have been established. A proxified link could look something like this: http://auth.libname.edu.au/cgibin/secure?url=http://www.libraryid.eblib.com.au/eblweb/patron/?target=pat ron&extendedid=p_204038_0 where: http://auth.libname.edu.au/cgi-bin/secure? is the URL of the CGI Authentication server process. The parameter url is the target URL to forward the request to once the users credentials have been verified. 5. When the CGI Authentication Server receives the request it authenticates the user. This can be by either redirecting them to a login page or verifying with the library login system that the user has a current active session. This is a process specific to the library and will need to be coded accordingly by the library s IT department. 6. If the user is authenticated, the CGI Server will append to the forwarding url listed above these parameters a unique user Id, the current timestamp, and a hash value of all of these parameters. The following details the constraints for each of these parameters: Unique User Id: this can be a string value up to 255 characters in length. This can be either an encrypted/hashed value or clear text. The only requirement is that it be traced back to the correct user. It can either be unique to the same user every time they visit EBL, or else can be traced according to the date/time of the session. Current Timestamp: this is a UNIX Timestamp (the current time in seconds since the epoch). This will be used to check to ensure that it does not fall outside a specific window of time, eg: 5 mins in the past or the future Hash Value: this is a combined value (a string for example) of each of the previous 3 values concatenated together, then one way hashed using an MD5 or SHA-1 Algorithm and the Shared Key as a seed to this process. The forwarding URL could look something like this (using MD5): Copyright 2005, Ebooks Corporation Limited 12

www.libraryid.eblib.com.au/eblweb/patron/?target=patron&extendedid=p_204038_0&useri d=43849867&tstamp=1106320584&id=4c4cfe5961e5c56610b821d071737e8d Where the id parameter is generated as follows: User Id + Timestamp + Shared Secret "43849867" + "1106320584" + "F942E4C8A76EE0A1" Results in: "438498671106320584F942E4C8A76EE0A1" - this is the value that actually gets hashed. Note: the order of the above Hash input string concatenation is essential. Each value must be concatenated without any delimiter The resulting concatenated string is then hashed to produce: MD5: SHA-1: 4C4CFE5961E5C56610B821D071737E8D 8553724CB8757665650E837493777C56276A1ABB 1. Once generated, the request is then forwarded to the new URL. (eg: sending a redirect back to the user s browser this could use a self submitting form which POSTs the parameters or as a simple http redirect directive.) 2. Once EBL receives the request it extracts the authorisation parameters from the query string, generates the same concatenated string as shown above, and then hashes the string to generate the hash value. 3. Check the Hash value sent in the request matches the one generated by EBL using its copy of the shared key. 4. The received timestamp is then checked to make sure that it is no more than a maximum (eg: 5 mins) number of minutes in the past or the future. 5. If everything matches, the user is logged into EBL and a session is established. 6. The target URL is then stripped of all of the unnecessary tokens that were used for authentication, and the request is then forwarded to the target URL where the user will be presented with the requested page. This ensures that if someone bookmarks the target page cannot return later without completing the correct authentication procedure etc 7. They are then presented with the requested page. 8. If any one of these steps fails to produce an identical result, login is denied and the user is returned to a known Authentication URL to establish their credentials. Copyright 2005, Ebooks Corporation Limited 13

Token Based Authentication For libraries which would like to use their library authentication system, this token based method can be used if you can send through the token as part of the URL. For the libraries security, you should also configure your system to send a request object with authentication information for validation. Token The userid is an essential token needed by EBL. This needs to be a unique number or string which is only used by one patron. A good ID to use could be the patron s library card number. For example: http://www.<yourlibrary>.eblib.com/eblweb/patron/?userid=<cardnumber> Within EBL LibCentral (library portal) you can set up one or several patron types which have different access privileges. For example, you might have a patrol type called 'student' and one called 'librarian' where the librarian patron is allowed to view all ebooks (owned and non-owned) where a student can only view owned books. In this case, you would need to send through the patron type (External Type Name) as well. For example: http://www.<yourlibrary>.eblib.com/eblweb/patron/?userid=<cardnumber>&type=stu http://www.<yourlibrary>.eblib.com/eblweb/patron/?userid=<cardnumber>&type=lib Please see section 7.3 Managing Patron Types, in the librarian Help Guide, for more information on patron types. You can download this guide by logging into your librarian portal http://www.icfl.eblib.com/eblweb/library.html and clicking on the help link in the top right corner. If you are setting downloads according to the patron location, then this information will need to be added to the URL also. For an internal patron: For example: http://www.<yourlibrary>.eblib.com/eblweb/patron/?userid=<cardnumber>&type=stu& loc=int Validation Authentication information needs to be added to the request object which tells EBL that the user is valid and ensures that the URL hasn t been created without authentication. Example in java: request.setattribute("valid", "true"); or: request.setattribute("ncsu_validation", "ACCESS_GRANTED"); Copyright 2005, Ebooks Corporation Limited

Log-in Authentication The EBL Patron management system can be used by libraries that don t use an internal authentication strategy. Patrons from these libraries will be directed to the EBL Patron log in page where they will enter their username and password to gain entry to EBL. The username and password database is administered by the library through the LibCentral Librarian portal. Patrons and patron types can be added, modified and deleted one-by-one or by using the upload function. Creating patron upload file Create a csv or tab delimited file following these rules: One user per line Each line contains username, password, patron type Separated by either a comma or tab depending on file type Notes: Username is the only required field Missing password or patron type will use default For reference, see Section 7.4 of the Library Help Guide Uploading patron file ----------------------------------------------------------------- These controls are found in Administration -> Import Patrons 1. Browse to the location of the saved patron upload file 2. Select whether it s a csv or tab delimited file 3. Choose how to deal with existing patrons and click the Import Patrons button ----------------------------------------------------------------- Notes: Ignore existing patrons will not upload a patron if the patron already exists in the system. Update existing patrons will over write a patron if the same username exists as well as uploading new patrons. Copyright 2005, Ebooks Corporation Limited 15

Customised permissions based on patron type EBL controls specific access permissions at the PATRON TYPE level. If your library is also able to pass a token identifying which type of patron is accessing the system along with the patron ID in the URL, you can take advantage of these more advanced custom settings. Some of these custom settings include: Whether or not a patron can see non-owned ebooks in the portal Length of loan for downloaded ebooks Access to pay-per-view or title request or auto-purchase for non-owned titles Ability to download ebooks on public computers If the patron was being authenticated by your library system and you were also sending the Unique user id and patron type as tokens, the URL would look like similar to this: http://[yourlibrary].eblib.com/eblweb/patron.html/?userid=[uniqueid]&type=guest&loc=int Identifying the patron type is NOT a requirement for EBL authentication. Rather, this process is available to libraries wishing to add a deeper level of granularity in access permissions. Those libraries that cannot or wish not to identify patron type in the authentication process will use default patron permissions that will be consistent for all users. Download Permission Configuration- internal vs. external access Depending on your library s computer or network set-up, you may wish to restrict downloading ebooks to public computers. Restricting download still enables patrons on the library s public computers to read online in the browser-based reader. Depending on your Authentication set up, the download permissions can be set by identifying PATRON TYPE or location of access (internal or external) at the time of authentication. We can determine download permission in a number of ways: Global On/OFF This method is used where internal ip addresses cannot be specified so the download permissions cannot be set according to whether the patron is internal or external. The library can set this to be on or off for all patrons. Global ON means that patrons will be able to read online and also download the ebook to their PC. Global OFF means that the patron Copyright 2005, Ebooks Corporation Limited 16

will only be able to read online, and not download to their PC. Global On/OFF permissions can be set in the SYSTEM SETTINGS in LibCentral. IP Based IP Based means you can set whether a patron type can download ebooks according to whether they're internal or external. You need to be able to define ip addresses which are internal only and register these with EBL. Download permissions IP-based identifier will be set at the PATRON TYPE level. Token Based For token based you must be able to send a token in the URL which the patron uses to access EBL. For example: http://[yourlibrary].eblib.com/eblweb/patron.html/?loc=int Where loc = parameter name int = value is internal ext = value is external Your account manager will provide you with further information on customizing these settings and will assist you in setting these patron permissions in LibCentral before your account is activated. Copyright 2005, Ebooks Corporation Limited 17