overview of voyager external patron authentication michael doran, systems librarian ex libris...
TRANSCRIPT
Overview of VoyagerOverview of VoyagerExternal Patron AuthenticationExternal Patron Authentication
Michael Doran, Systems Librarian
Ex Libris Southwest Users GroupFebruary 6, 2008 – Santa Ana College
Michael Doran, Systems Librarian [email protected]
Standard Patron Authentication- User Perspective -
The user clicks the “Login” (or “Patron”, etc.) button...
... gets a login form...
... enters credentials and submits...
Michael Doran, Systems Librarian [email protected]
Once logged in, the user has access to their patron information, requests, MyOPAC functionality, etc.
Standard Patron Authentication- User Perspective -
Michael Doran, Systems Librarian [email protected]
The user clicks the “Login” (or “Patron”, etc.) button...
... gets a login form...
... enters credentials and submits...
External Patron Authentication- User Perspective -
Michael Doran, Systems Librarian [email protected]
Once logged in, the user has access to their patron information, requests, MyOPAC functionality, etc.
External Patron Authentication- User Perspective -
Michael Doran, Systems Librarian [email protected]
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....
Michael Doran, Systems Librarian [email protected]
Standard Patron Authentication
Everything is handled by WebVoyáge (i.e. Pwebrecon.cgi)
Michael Doran, Systems Librarian [email protected]
Standard Patron Authentication
Michael Doran, Systems Librarian [email protected]
External Patron Authentication
query string
WebVoyáge hands over control... ... to an “adaptor”...
Michael Doran, Systems Librarian [email protected]
External Patron Authentication
... and then returns control to WebVoyáge
... the adaptor does the authentication...
Michael Doran, Systems Librarian [email protected]
WebVoyáge to Adaptor Hand Off
WebVoyáge[Pwebrecon.cgi]
Authentication Adaptor[customer-adaptor.cgi]
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400
“query string”
What determines whether this hand off occurs? ...
Michael Doran, Systems Librarian [email protected]
ExtAuthenticationSystem stanza
[ExtAuthenticationSystem]ExtAuthSystemEnabled=YExtAuthBypassLoginScreen=YExtAuthSubmitText=Login with NetIDExtAuthSystemURL=/cgi-bin/customer-adaptor.cgiExtAuthButtonMethod=GET
The opac.ini configuration file contains a stanza called ExtAuthenticationSystem. The parameters in this stanza control the initial hand-off to a patron authentication adaptor.
Michael Doran, Systems Librarian [email protected]
ExtAuthenticationSystem stanza
To totally bypass the WebVoyáge login screen:
[ExtAuthenticationSystem]ExtAuthSystemEnabled=YExtAuthBypassLoginScreen=YExtAuthSubmitText=Login with NetIDExtAuthSystemURL=/cgi-bin/customer-adaptor.cgiExtAuthButtonMethod=GET
Takes userdirectly to external
authenticationlogin screen.
Michael Doran, Systems Librarian [email protected]
ExtAuthenticationSystem stanza
To give users the option of logging in using the standard WebVoyáge or the external authentication:
[ExtAuthenticationSystem]ExtAuthSystemEnabled=YExtAuthBypassLoginScreen=NExtAuthSubmitText=Login with NetIDExtAuthSystemURL=/cgi-bin/customer-adaptor.cgiExtAuthButtonMethod=GET
Takes user tostandard
WebVoyágelogin screen...
...which includesa button linking to the adaptor login
screen.
Michael Doran, Systems Librarian [email protected]
Now where did I put that adaptor?
Patron authentication adaptor feature“functionality that allows WebVoyá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 WebVoyáge and the external authentication program”
The patron authentication adaptor referred to is a computer program. Customer-developed means you get to write it.
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
Authentication Adaptor[customer-adaptor.cgi]
When first called:
• Parse and store WebVoyáge query stringThe 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
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
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 WebVoyáge via a redirect to Pwebrecon.cgi URL appended with:
Original (saved) query string, plus Authentication key-value pair
After user credentials are submitted:
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
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 WebVoyáge via a redirect to Pwebrecon.cgi URL appended with:
Original (saved) query string, plus Authentication key-value pair
After user credentials are submitted:
Michael Doran, Systems Librarian [email protected]
Authentication Systems
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.
Time out!
Michael Doran, Systems Librarian [email protected]
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 WebVoyáge patron authentication adaptor feature, but not an actual patron authentication adaptor.
And which are also why the feature is entirely authentication-system neutral, but the adaptor itself is by necessity, authentication-system specific.
Systems Librarian
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
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 WebVoyáge via a redirect to Pwebrecon.cgi URL appended with:
Original (saved) query string, plus Authentication key-value pair
After user credentials are submitted:
Michael Doran, Systems Librarian [email protected]
Query External Authentication System
Authentication Adaptor[customer-adaptor.cgi]
1. Adaptor sends formatted query containing username and password
2. Authentication system replies with success/failure response plus user information if success
Authentication System[e.g. LDAP]
Michael Doran, Systems Librarian [email protected]
Plus user information?
dn:cedarid=10856915705,cn=people,dc=uta,dc=edu
objectClass: top person inetOrgPerson utaPerson cedarid: 10856915705 utaSSN: 123456789 mail: [email protected] utaDiscloseInfo: email utaMiddleName: d cn: michael d doran sn: doran givenName: michael displayName: doran, michael dutaPrevAccountName: doran utaAccountName: doran uid: doranmd
Example response from
UTA OpenLDAP server
(a “people” record)
Michael Doran, Systems Librarian [email protected]
Needed: Institution ID
dn:cedarid=10856915705,cn=people,dc=uta,dc=edu
objectClass: top person inetOrgPerson utaPerson cedarid: 10856915705 utaSSN: 123456789 mail: [email protected] utaDiscloseInfo: email utaMiddleName: d cn: michael d doran sn: doran givenName: michael displayName: doran, michael dutaPrevAccountName: doran utaAccountName: doran uid: doranmd
The authenticator response needs to be parsed for a value (preferably the Institution ID) that can be used to identify that user’s Voyager patron record.
Michael Doran, Systems Librarian [email protected]
Standard Patron Authentication
XXXDB.PATRON
PATRON_ID SSAN NORMAL_LAST_NAME NORMAL_INSTITUTION_ID
XXXDB.PATRON_BARCODE
PATRON_ID PATRON_BARCODE
Voyager Tables
Authentication confirms an identity. The standard WebVoyáge login process authenticates a user by matching the user input (last name and identifier) against patron records to identify a unique patron record.
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
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 WebVoyáge via a redirect to Pwebrecon.cgi URL appended with:
Original (saved) query string, plus Authentication key-value pair
After user credentials are submitted:
Michael Doran, Systems Librarian [email protected]
Provide a Unique Patron Identifier
Although you’ve confirmed the user’s identity within the external system, WebVoyá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).
cedarid: 10856915705 utaSSN: 123456789 mail: [email protected]
PID value fromsaved query string
Institution ID value fromauthenticator response
insert into XXXDB.WOPAC_PID_PATRON_KEYS (PID, PATRON_KEY) values (‘2063','123456789')
Michael Doran, Systems Librarian [email protected]
Authentication Adaptor Tasks
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 WebVoyáge via a redirect to Pwebrecon.cgi URL appended with:
Original (saved) query string, plus Authentication key-value pair
After user credentials are submitted:
Michael Doran, Systems Librarian [email protected]
Adaptor to WebVoyáge Hand Off
WebVoyáge[Pwebrecon.cgi]
Authentication Adaptor[customer-adaptor.cgi]
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400&authenticate=Y
“query string”
Michael Doran, Systems Librarian [email protected]
WebVoyáge Back on the Job
WebVoyáge[Pwebrecon.cgi]
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400&authenticate=Y
authenticate=Y
A successful external authentication (“Y”) results in WebVoyáge retrieving the record inserted into the WOPAC_PID_PATRON_KEYS table by the adaptor.
authenticate=N
An authentication failure (“N”) results in WebVoyáge displaying an error message, and returning the user to a login screen.
Michael Doran, Systems Librarian [email protected]
Retrieving Unique Identifier
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400&authenticate=Y
The query string PID value lets Voyager know which WOPAC record to retrieve.
XXXDB.WOPAC_PID_PATRON_KEYS
PID PATRON_KEY ------- ----------- 2049 555339876 2063 123456789 2068 333221234 ...
Voyager grabs the PATRON_KEY value for that PID and then deletes that record in the WOPAC table.
WebVoyáge[Pwebrecon.cgi]
Michael Doran, Systems Librarian [email protected]
Looking Up Patron Record
WebVoyáge[Pwebrecon.cgi]
WebVoyáge compares the PATRON_KEY value with normalized Institution ID values in the patron table.
XXXDB.PATRON
PATRON_ID 123456789 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.
If no match is found, WebVoyáge displays an error message and returns the user to the login screen.
Michael Doran, Systems Librarian [email protected]
The “Institution ID” Blues
This can be a problem if:
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.
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.
Systems Librarian
Michael Doran, Systems Librarian [email protected]
Work-Arounds
Systems Librarian
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 WebVoyá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.
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.
Michael Doran, Systems Librarian [email protected]
Ex Libris Documentation
The Voyager Technical User’s Guide, Appendix C contains “WebVoyáge Patron Authentication Adaptor feature”.
Note: Ex Libris has substantially revised the WebVoyáge Patron Authentication Adaptor documentation since the initial release.
Always the best place to start...
Michael Doran, Systems Librarian [email protected]
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 pre-built components/modules for: 1) parsing CGI form data, 2) interfacing with an Oracle database, and 3) interfacing with the desired authentication
system.
Michael Doran, Systems Librarian [email protected]
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
Michael Doran, Systems Librarian [email protected]
Authentication adaptorsfor LDAP written in Perl
Flatten out the learning curve by adapting these two Perl scripts created by other Voyager customers.
“Adaptor Example Source Code”A production-worthy Voyager third-party patron authentication
adaptor script using Perl to query an LDAP serverby Michael Doran, University of Texas at Arlingtonhttp://rocky.uta.edu/doran/adaptor/
“login”An authentication script used to authenticate access to Voyager's MyOPAC [This is also a production level script, in Perl]by Steve Thomas, University of Adelaidehttp://staff.library.adelaide.edu.au/sthomas/scripts/voyager/login.html
Michael Doran, Systems Librarian [email protected]
An authentication adaptorfor Kerberos written in Java Or if Java is more your cup of tea, take a look at this EndUser presentation:
“External Patron Authentication”EndUser 2004, Session 35 by Jeff Barnett, Gail Barnett, and Kalee Sprague, Yale Universityhttp://support.endinfosys.com/cust/community/vgroup/eu2004/tech.html orhttp://www.library.yale.edu/~jbarnett/EndUser2004/session35.ppt
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/EndUser2004/
Michael Doran, Systems Librarian [email protected]
Some Voyager sites usingexternal patron authentication Columbia University Tarrant County College Monash University University of Adelaide University of British Columbia University of Texas at Arlington Washington Research Library Consortium Worcester Polytechnic Institute Yale University
Get a fuller list of implementing libraries at: http://rocky.uta.edu/doran/adaptor/voysites.html
Michael Doran, Systems Librarian [email protected]
This presentation…
Creating an LDAP Patron Authentication Adaptor (using Perl)
…was an overview
You might also want to take a look at…
Michael Doran, Systems Librarian [email protected]
Any questions?