introduction to voyager external patron authentication

Introduction to VoyagerIntroduction to VoyagerExternal Patron AuthenticationExternal Patron Authentication

Michael Doran, Systems LibrarianUniversity of Texas at Arlington

doran@uta.edu

October 1, 2004 - South Central Voyager Users Group Meeting - Nacogdoches, TX

2

Standard Patron Authentication- User Perspective -

The user clicks the “Login” (or “Patron”, etc.) button...

... gets a login form...

... enters data and submits...

3

Once logged in, the user has access to their patron information, requests, MyOPAC functionality, etc.

Standard Patron Authentication- User Perspective -

4

External Patron Authentication- User Perspective -

The user clicks the “Login” (or “Patron”, etc.) button...

... gets a login form...

... enters data and submits...

5

External Patron Authentication- User Perspective -

Once logged in, the user has access to their patron information, requests, MyOPAC functionality, etc.

6

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....

7

Standard Patron AuthenticationEverything is handled by WebVoyáge (i.e. Pwebrecon.cgi)

8

Standard Patron Authentication

9

External Patron Authentication

Query string

WebVoyáge hands over control... ... to an “adaptor”...

10

External Patron Authentication

... and then returns control to WebVoyáge

... the adaptor does the authentication...

11

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? ...

12

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.

13

ExtAuthenticationSystem stanzaTo 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.

14

ExtAuthenticationSystem stanzaTo 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.

15

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.

16

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

17

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

When patron info submitted:

18

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

When patron info submitted:

19

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 likely differ slightly in internal data structure from one organization to another.

Time out!

20

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

21

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

When patron info submitted:

22

Query External Authentication System

Authentication Adaptor[customer-adaptor.cgi]

1. Adaptor sends formatted query containing user ID & password

2. Authentication system replies with success/failure response plus user information if success

Authentication System[e.g. LDAP]

Plus user information? memberOf: CN=MCT,CN=Users,DC=uta,DC=edu CN=LIB,CN=Users,DC=uta,DC=edu badPasswordTime: 127054564544756875 cn: smith company: University of Texas at Arlington c: US department: Library description: LIB displayName: John H. Smith mail: Smith@uta.edu givenName: John initials: H l: Arlington distinguishedName: CN=smith,CN=Users,DC=uta,DC=edu objectCategory: CN=Person,CN=Schema,physicalDeliveryOfficeName: BUILDING NAME UNAVAIL postOfficeBox: 19497 postalCode: 76019 NetID: 3133405326 name: smith sAMAccountName: smith st: TX sn: Smith telephoneNumber: (817) 272-1234 title: LIBRARIAN

Example response

from LDAP server

24

Needed: Institution ID memberOf: CN=MCT,CN=Users,DC=uta,DC=edu CN=LIB,CN=Users,DC=uta,DC=edu badPasswordTime: 127054564544756875 cn: smith company: University of Texas at Arlington c: US department: Library description: LIB displayName: John H. Smith mail: Smith@uta.edu givenName: John initials: H l: Arlington distinguishedName: CN=smith,CN=Users,DC=uta,DC=edu objectCategory: CN=Person,CN=SchemaphysicalDeliveryOfficeName: BUILDING NAME UNAVAIL postOfficeBox: 19497 postalCode: 76019 NetID: 3133405326 name: smith sAMAccountName: smith st: TX sn: Smith telephoneNumber: (817) 272-1234 title: LIBRARIAN

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.

25

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.

26

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

When patron info submitted:

27

Provide a Unique Patron IdentifierAlthough 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).

postalCode: 76019 NetID: 3133405326 name: smith

PID value fromsaved query string

Institution ID value fromauthenticator response

insert into XXXDB.WOPAC_PID_PATRON_KEYS (PID, PATRON_KEY) values (‘2063',' 3133405326')

28

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

When patron info submitted:

29

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

30

WebVoyáge Back on the Job

WebVoyáge[Pwebrecon.cgi]

PAGE=pbLogonPatron&PID=2063&SEQ=20040921144400&authenticate=Y

authenticate=YA successful external authentication (“Y”) results in WebVoyáge retrieving the record inserted into the WOPAC table by the adaptor.

authenticate=NAn authentication failure (“N”) results in WebVoyáge displaying an error message, and returning the user to a login screen.

31

Retrieving Unique IdentifierPAGE=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 3133409987 2063 3133405326 2068 3133003245 ...

Voyager grabs the PATRON_KEY value for that PID and then deletes that record in the WOPAC table.

WebVoyáge[Pwebrecon.cgi]

32

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 3133405326 NORMAL_INSTITUTION_ID

If a match is found, the user islogged in for that session.

If no match is found, WebVoyáge displays an error message and returns the user to the login screen.

33

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 include a user’s Institution ID in the data it returns with responses.

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

34

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.

35

Constructing an adaptor There are no real restrictions on the

programming language used...• Perl• Java• 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.

36

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

37

Authentication adaptorsfor 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 Arlingtonhttp://rocky.uta.edu/doran/adaptor/

“login”An authentication script used to authenticate access to Voyager's MyOPAC [This is a production script]by Steve Thomas, University of Adelaidehttp://staff.library.adelaide.edu.au/~sthomas/scripts/voyager/login.html

38

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

Yale University Library put Voyager external patron authentication into production. I believe their adaptor was written in Java and authenticates against a Kerberos server. For more info see:

http://www.library.yale.edu/~jbarnett/EndUser2004/

39

Some Voyager sites usingexternal patron authentication

• Columbia University• University of Adelaide• Washington Research Library

Consortium• Worcester Polytechnic Institute

40

Endeavor Documentation

The Voyager Technical User’s Guide contains “WebVoyáge Patron Authentication Adaptor feature” in Appendix D - Voyager 2001.2 Appendix C - Voyager with Unicode

Note: Endeavor has substantially revised the WebVoyáge Patron Authentication Adaptor documentation since the initial release and I highly recommend you get the latest version.

Always the best place to start...

41

Any questions?

42

Thanks for attending!

The End

Don’t forget to fill out the session evaluation.