Overview of Voyager
External Patron Authentication
Michael Doran, Systems Librarian
Ex Libris Southwest Users Group
February 6, 2008 – Santa Ana College
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]
Standard Patron Authentication
- User Perspective -
Once logged in, the user has access to their patron
information, requests, MyOPAC functionality, etc.
Michael Doran, Systems Librarian
[email protected]
External 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]
External Patron Authentication
- User Perspective -
Once logged in, the user has access to their patron
information, requests, MyOPAC functionality, etc.
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
WebVoyáge hands over control...
... to an “adaptor”...
query string
Michael Doran, Systems Librarian
[email protected]
External Patron Authentication
... the adaptor does
the authentication...
... and then returns control to WebVoyáge
Michael Doran, Systems Librarian
[email protected]
WebVoyáge to Adaptor Hand Off
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400
“query string”
WebVoyáge
[Pwebrecon.cgi]
Authentication Adaptor
[customer-adaptor.cgi]
What determines whether this hand off occurs? ...
Michael Doran, Systems Librarian
[email protected]
ExtAuthenticationSystem stanza
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.
[ExtAuthenticationSystem]
ExtAuthSystemEnabled=Y
ExtAuthBypassLoginScreen=Y
ExtAuthSubmitText=Login with NetID
ExtAuthSystemURL=/cgi-bin/customer-adaptor.cgi
ExtAuthButtonMethod=GET
Michael Doran, Systems Librarian
[email protected]
ExtAuthenticationSystem stanza
To totally bypass the WebVoyáge login screen:
[ExtAuthenticationSystem]
ExtAuthSystemEnabled=Y
ExtAuthBypassLoginScreen=Y
ExtAuthSubmitText=Login with NetID
ExtAuthSystemURL=/cgi-bin/customer-adaptor.cgi
ExtAuthButtonMethod=GET
Takes user
directly to external
authentication
login 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=Y
ExtAuthBypassLoginScreen=N
ExtAuthSubmitText=Login with NetID
ExtAuthSystemURL=/cgi-bin/customer-adaptor.cgi
ExtAuthButtonMethod=GET
Takes user to
standard
WebVoyáge
login screen...
...which includes
a 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
When first called:
• Parse and store WebVoyá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]
Michael Doran, Systems Librarian
[email protected]
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 WebVoyáge via a redirect
to Pwebrecon.cgi URL appended with:
 Original (saved) query string, plus
 Authentication key-value pair
Michael Doran, Systems Librarian
[email protected]
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 WebVoyáge via a redirect
to Pwebrecon.cgi URL appended with:
 Original (saved) query string, plus
 Authentication key-value pair
Michael Doran, Systems Librarian
[email protected]
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.
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.
Systems Librarian
And which are also why the feature is
entirely authentication-system neutral,
but the adaptor itself is by necessity,
authentication-system specific.
Michael Doran, Systems Librarian
[email protected]
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 WebVoyáge via a redirect
to Pwebrecon.cgi URL appended with:
 Original (saved) query string, plus
 Authentication key-value pair
Michael Doran, Systems Librarian
[email protected]
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]
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 d
utaPrevAccountName: doran
utaAccountName: doran
uid: doranmd
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
The authenticator response
sn: doran
needs to be parsed for a
givenName: michael
value (preferably the
displayName: doran, michael d
Institution ID) that can be
utaPrevAccountName: doran
used to identify that user’s
utaAccountName: doran
Voyager patron record.
uid: doranmd
Michael Doran, Systems Librarian
[email protected]
Standard Patron Authentication
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.
Voyager Tables
XXXDB.PATRON
PATRON_ID
SSAN
NORMAL_LAST_NAME
NORMAL_INSTITUTION_ID
XXXDB.PATRON_BARCODE
PATRON_ID
PATRON_BARCODE
Michael Doran, Systems Librarian
[email protected]
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 WebVoyáge via a redirect
to Pwebrecon.cgi URL appended with:
 Original (saved) query string, plus
 Authentication key-value pair
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).
insert into XXXDB.WOPAC_PID_PATRON_KEYS
(PID, PATRON_KEY) values (‘2063','123456789')
cedarid: 10856915705
utaSSN: 123456789
mail: [email protected]
PID value from
saved query string
Institution ID value from
authenticator response
Michael Doran, Systems Librarian
[email protected]
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 WebVoyáge via a redirect
to Pwebrecon.cgi URL appended with:
 Original (saved) query string, plus
 Authentication key-value pair
Michael Doran, Systems Librarian
[email protected]
Adaptor to WebVoyáge Hand Off
PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400&authenticate=Y
“query string”
Authentication Adaptor
[customer-adaptor.cgi]
WebVoyáge
[Pwebrecon.cgi]
Michael Doran, Systems Librarian
[email protected]
WebVoyáge Back on the Job
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
WebVoyáge
[Pwebrecon.cgi]
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
WebVoyá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.
Michael Doran, Systems Librarian
[email protected]
Looking Up Patron Record
WebVoyá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.
WebVoyáge
[Pwebrecon.cgi]
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
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.
Michael Doran, Systems Librarian
[email protected]
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 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.
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.
Michael Doran, Systems Librarian
[email protected]
Ex Libris Documentation
Always the best place to start...
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.
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 prebuilt 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 adaptors
for 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 server
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
MyOPAC [This is also a production level script, in Perl]
by Steve Thomas, University of Adelaide
http://staff.library.adelaide.edu.au/sthomas/scripts/voyager/login.html
Michael Doran, Systems Librarian
[email protected]
An authentication adaptor
for 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 University
http://support.endinfosys.com/cust/community/vgroup/eu2004/tech.html or
http://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 using
external 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…
…was an overview
You might also want to take a look at…
Creating an LDAP Patron Authentication Adaptor (using Perl)
Michael Doran, Systems Librarian
[email protected]
Any questions?
Michael Doran, Systems Librarian
[email protected]