Overview of Voyager External Patron Authentication End User

Overview of Voyager External Patron Authentication End. User Session #20 – Thursday 4: 15 -5: 15 pm Michael Doran, Systems Librarian University of Texas at Arlington doran@uta. edu April 28, 2005 - Endeavor Users Group Meeting - Chicago, IL

Standard Patron Authentication - User Perspective The user clicks the “Login” (or “Patron”, etc. ) button. . . gets a login form. . . enters credentials and submits. . . 2

Standard Patron Authentication - User Perspective - Once logged in, the user has access to their patron information, requests, My. OPAC functionality, etc. 3

External Patron Authentication - User Perspective The user clicks the “Login” (or “Patron”, etc. ) button. . . gets a login form. . . enters credentials and submits. . . 4

External Patron Authentication - User Perspective - Once logged in, the user has access to their patron information, requests, My. OPAC functionality, etc. 5

What’s the Difference? From a user perspective the login experience is pretty much the same, regardless of whether he/she uses standard Voyager patron authentication or an external authentication system. A sharp-eyed user might notice that another web application comes into play during external authentication. . 6

Standard Patron Authentication Everything is handled by Web. Voyáge (i. e. Pwebrecon. cgi) 7

Standard Patron Authentication 8

External Patron Authentication Web. Voyáge hands over control. . . to an “adaptor”. . . query string 9

External Patron Authentication . . . the adaptor does the authentication. . . and then returns control to Web. Voyáge 10

Web. Voyáge to Adaptor Hand Off PAGE=pb. Logon. Patron&PID=2063&SEQ=20040921144400 “query string” Web. Voyáge [Pwebrecon. cgi] Authentication Adaptor [customer-adaptor. cgi] What determines whether this hand off occurs? . . . 11

Ext. Authentication. System stanza The opac. ini configuration file contains a stanza called Ext. Authentication. System. The parameters in this stanza control the initial hand-off to a patron authentication adaptor. [Ext. Authentication. System] Ext. Auth. System. Enabled=Y Ext. Auth. Bypass. Login. Screen=Y Ext. Auth. Submit. Text=Login with Net. ID Ext. Auth. System. URL=/cgi-bin/customer-adaptor. cgi Ext. Auth. Button. Method=GET 12

Ext. Authentication. System stanza To totally bypass the Web. Voyáge login screen: [Ext. Authentication. System] Ext. Auth. System. Enabled=Y Ext. Auth. Bypass. Login. Screen=Y Ext. Auth. Submit. Text=Login with Net. ID Ext. Auth. System. URL=/cgi-bin/customer-adaptor. cgi Ext. Auth. Button. Method=GET Takes user directly to external authentication login screen. 13

Ext. Authentication. System stanza To give users the option of logging in using the standard Web. Voyáge or the external authentication: [Ext. Authentication. System] Ext. Auth. System. Enabled=Y Ext. Auth. Bypass. Login. Screen=N Ext. Auth. Submit. Text=Login with Net. ID Ext. Auth. System. URL=/cgi-bin/customer-adaptor. cgi Ext. Auth. Button. Method=GET Takes user to standard Web. Voyáge login screen. . . which includes a button linking to the adaptor login screen. 14

Now where did I put that adaptor? • Patron authentication adaptor feature “functionality that allows Web. Voyáge to communicate with an external authentication program, via a customer-developed authentication adaptor” • Patron authentication adaptor “the customer-developed adaptor which provides the communications bridge between Web. Voyáge and the external authentication program” The patron authentication adaptor referred to is a computer program. Customer-developed means you get to write it. 15

Authentication Adaptor Tasks When first called: • Parse and store Web. Voyáge query string The query string contains the data such as the PID (“process ID”) which identifies the session and is necessary for maintaining session state. • Generate HTML code for a patron login form in order to gather desired user credentials Authentication Adaptor [customer-adaptor. cgi] 16

Authentication Adaptor Tasks After user credentials are submitted: Authentication Adaptor [customer-adaptor. cgi] • Query external authentication system § Get “yea” or “nay” on user § Retrieve “Institution ID” • If yea, insert a record into the WOPAC_PID_PATRON_KEYS table: § PID (saved from query string) § Institution ID • Return control to Web. Voyáge via a redirect to Pwebrecon. cgi URL appended with: § Original (saved) query string, plus § Authentication key-value pair 17

Authentication Adaptor Tasks After user credentials are submitted: Authentication Adaptor [customer-adaptor. cgi] • Query external authentication system § Get “yea” or “nay” on user § Retrieve “Institution ID” • If yea, insert a record into the WOPAC_PID_PATRON_KEYS table: § PID (saved from query string) § Institution ID • Return control to Web. Voyáge via a redirect to Pwebrecon. cgi URL appended with: § Original (saved) query string, plus § Authentication key-value pair 18

Authentication Systems Time out! There are many authentication systems. . . • • LDAP (Lightweight Directory Access Protocol) Kerberos NIS/NIS+ (Network Information Service) SMB (Windows) Shibboleth RADIUS (Remote Authentication Dial In User Service) etc. . . ü In addition, authentication systems such as LDAP will differ in internal data structure from one organization to another. 19

Which means. . . The multitude of authentication systems, as well as the fact that the systems can vary in internal data structure, are the principle reasons why Voyager comes with a Web. Voyáge patron authentication adaptor feature, but not an actual patron authentication adaptor. Systems Librarian And which are also why the feature is entirely authentication-system neutral, but the adaptor itself is by necessity, authentication-system specific. 20

Authentication Adaptor Tasks After user credentials are submitted: Authentication Adaptor [customer-adaptor. cgi] • Query external authentication system § Get “yea” or “nay” on user § Retrieve “Institution ID” • If yea, insert a record into the WOPAC_PID_PATRON_KEYS table: § PID (saved from query string) § Institution ID • Return control to Web. Voyáge via a redirect to Pwebrecon. cgi URL appended with: § Original (saved) query string, plus § Authentication key-value pair 21

Query External Authentication System 1. Adaptor sends formatted query containing username and password 2. Authentication system replies with success/failure response plus user information if success Authentication Adaptor [customer-adaptor. cgi] Authentication System [e. g. LDAP] 22

Plus user information? dn: cedarid=10856915705, cn=people, dc=uta, dc=edu object. Class: top person om r f e pons erver inet. Org. Person s e r Ps ple A m uta. Person D a Ex en. L record) p O cedarid: 10856915705 UTA people” uta. SSN: 123456789 (a “ mail: doran@uta. edu uta. Disclose. Info: email uta. Middle. Name: d cn: michael d doran sn: doran given. Name: michael display. Name: doran, michael d uta. Prev. Account. Name: doran uta. Account. Name: doran uid: doranmd

Needed: Institution ID dn: cedarid=10856915705, cn=people, dc=uta, dc=edu object. Class: top person inet. Org. Person uta. Person cedarid: 10856915705 uta. SSN: 123456789 mail: doran@uta. edu uta. Disclose. Info: email uta. Middle. Name: d cn: michael d doran The authenticator response sn: doran needs to be parsed for a given. Name: michael value (preferably the display. Name: doran, michael d Institution ID) that can be uta. Prev. Account. Name: doran used to identify that user’s uta. Account. Name: doran Voyager patron record. uid: doranmd 24

Standard Patron Authentication confirms an identity. The standard Web. Voyáge login process authenticates a user by matching the user input (last name and identifier) against patron records to identify a unique patron record. Voyager Tables XXXDB. PATRON_ID SSAN NORMAL_LAST_NAME NORMAL_INSTITUTION_ID XXXDB. PATRON_BARCODE PATRON_ID PATRON_BARCODE 25

Authentication Adaptor Tasks After user credentials are submitted: Authentication Adaptor [customer-adaptor. cgi] • Query external authentication system § Get “yea” or “nay” on user § Retrieve “Institution ID” • If yea, insert a record into the WOPAC_PID_PATRON_KEYS table: § PID (saved from query string) § Institution ID • Return control to Web. Voyáge via a redirect to Pwebrecon. cgi URL appended with: § Original (saved) query string, plus § Authentication key-value pair 26

Provide a Unique Patron Identifier Although you’ve confirmed the user’s identity within the external system, Web. Voyáge needs to be able to identify a unique patron record internal to the Voyager database. The Patron Authentication Adaptor feature is designed to use the Institution ID to match on the Voyager patron record for that user. The customer adaptor must insert that value as well as the PID value into a Voyager database table (via an SQL DML statement). insert into XXXDB. WOPAC_PID_PATRON_KEYS (PID, PATRON_KEY) values (‘ 2063', '123456789') cedarid: 10856915705 uta. SSN: 123456789 mail: doran@uta. edu PID value from saved query string Institution ID value from authenticator response 27

Authentication Adaptor Tasks After user credentials are submitted: Authentication Adaptor [customer-adaptor. cgi] • Query external authentication system § Get “yea” or “nay” on user § Retrieve “Institution ID” • If yea, insert a record into the WOPAC_PID_PATRON_KEYS table: § PID (saved from query string) § Institution ID • Return control to Web. Voyáge via a redirect to Pwebrecon. cgi URL appended with: § Original (saved) query string, plus § Authentication key-value pair 28

Adaptor to Web. Voyáge Hand Off PAGE=pb. Logon. Patron&PID=2063&SEQ=20040921144400&authenticate=Y “query string” Authentication Adaptor [customer-adaptor. cgi] Web. Voyáge [Pwebrecon. cgi] 29

Web. Voyáge Back on the Job PAGE=pb. Logon. Patron&PID=2063&SEQ=20040921144400&authenticate=Y A successful external authentication (“Y”) results in Web. Voyáge retrieving the record inserted into the WOPAC_PID_PATRON_KEYS table by the adaptor. authenticate=N Web. Voyáge [Pwebrecon. cgi] An authentication failure (“N”) results in Web. Voyáge displaying an error message, and returning the user to a login screen. 30

Retrieving Unique Identifier PAGE=pb. Logon. Patron&PID=2063&SEQ=20040921144400&authenticate=Y The query string PID value lets Voyager know which WOPAC record to retrieve. XXXDB. WOPAC_PID_PATRON_KEYS Web. Voyáge [Pwebrecon. cgi] PID ------2049 2063 2068. . . PATRON_KEY -----555339876 123456789 333221234 Voyager grabs the PATRON_KEY value for that PID and then deletes that record in the WOPAC table. 31

Looking Up Patron Record Web. Voyáge compares the PATRON_KEY value with normalized Institution ID values in the patron table. XXXDB. PATRON 123456789 PATRON_ID NORMAL_INSTITUTION_ID A successful match means that Voyager has identified the user, and the user can then be logged in and the requested page provided. Web. Voyáge [Pwebrecon. cgi] If no match is found, Web. Voyáge displays an error message and returns the user to the login screen. 32

The “Institution ID” Blues The PATRON_KEY value inserted into the Voyager “WOPAC” table has to be the Institution ID since that is the field in the patron record that it will be matched against. Barcodes and social security numbers (that aren’t also Institution IDs) will not work. This can be a problem if: Systems Librarian 1) Your organization doesn’t use Institution IDs and/or your library doesn’t populate that field in the Voyager PATRON table, or. . . 2) You have Institution IDs in the Voyager PATRON table, but the external authorization system doesn’t return an attribute containing a user’s Institution ID. 33

Work-Arounds The bottom line is that the Institution ID field of the patron record has to be populated with unique identifiers in order to use the Web. Voyáge external patron authentication feature. If your organization uses social security numbers as the de facto institution IDs, then patron update SIF files must include social security numbers in the Institution ID field in addition to the SSAN field. Systems Librarian If the external authentication system doesn’t return the Institution ID values that you have in your Voyager patron records, but returns another unique identifier included in your patron records, it may be possible to have the authentication adaptor query Voyager for the appropriate Institution ID prior to inserting a record into the WOPAC table. 34

Constructing an adaptor There are no real restrictions on the programming language used. . . • • • Perl Java/JSP C/C++ Shell script whatever However. . . it saves a lot of work to have prebuilt components/modules for: 1) parsing CGI form data, 2) interfacing with an Oracle database, and 3) interfacing with the desired authentication system. 35

Perl is a good choice • CGI. pm module or cgi-lib. pl library for processing CGI forms • DBI and DBD: : Oracle modules for interfacing with the Voyager database • Net: : LDAP or Net: : LDAPS modules for interfacing with an LDAP server • Plus many other authentication modules available on CPAN 36

Authentication adaptors for LDAP written in Perl Flatten out the learning curve by adapting these two Perl scripts created by other Voyager customers. “Authentication Adaptor” Proof-of-concept Voyager third-party patron authentication using Perl to query an LDAP server [includes source code] by Michael Doran, University of Texas at Arlington http: //rocky. uta. edu/doran/adaptor/ “login” An authentication script used to authenticate access to Voyager's My. OPAC [This is a production script] by Steve Thomas, University of Adelaide http: //staff. library. adelaide. edu. au/~sthomas/scripts/voyager/login. html 37

An authentication adaptor for Kerberos written in Java Or if Java is more your cup of tea, take a look at this End. User presentation: “External Patron Authentication” End. User 2004, Session 35 by Jeff Barnett, Gail Barnett, and Kalee Sprague, Yale University http: //support. endinfosys. com/cust/community/vgroup/eu 2004/tech. html Yale University Library developed an external patron authentication adaptor written in Java. It authenticates against a Kerberos server. For more info see: http: //www. library. yale. edu/~jbarnett/End. User 2004/ 38

Some Voyager sites using external patron authentication • • • Columbia University Tarrant County College Monash University of Adelaide University of British Columbia University of Texas at Arlington Washington Research Library Consortium Worcester Polytechnic Institute Yale University 39

Endeavor Documentation Always the best place to start. . . The Voyager Technical User’s Guide contains “Web. Voyáge Patron Authentication Adaptor feature” in § Appendix D - Voyager 2001. 2 § Appendix C - Voyager with Unicode Note: Endeavor has substantially revised the Web. Voyáge Patron Authentication Adaptor documentation since the initial release and I highly recommend you get the latest version. 40

Any questions? 41

The End Don’t forget to fill out the session evaluation. Thanks for attending! 42