Creating an LDAP Patron Authentication Adaptor

1. Creating an LDAP Patron Authentication Adaptor (using Perl) Michael Doran, Systems Librarian University of Texas at Arlington Endeavor Users Group Meeting, Chicago, IL Session 46, Friday, 21 April 2006

2. Why do external authentication? • The default WebVoyáge authentication is inherently insecure since login as a particular user requires credentials (last name and either SSN/Institution ID/barcode number) that are potentially known to people other than that user. • External authentication login requires a password known only to a particular user. Michael Doran - University of Texas at Arlington - EndUser 2006

3. Voyager external authentication Part 2 • In “Part 1” [1] we learned that external patron authentication was... ...but rather something that had to be built. Not something to be switched on... • [1] “Overview of Voyager External Patron Authentication” • EndUser 2005, Technical Session 20 Michael Doran - University of Texas at Arlington - EndUser 2006

4. 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 - University of Texas at Arlington - EndUser 2006

5. Quick Review Pwebrecon.cgi [ExtAuthenticationSystem] ExtAuthSystemEnabled=Y ExtAuthBypassLoginScreen=Y ExtAuthSystemURL=login.cgi opac.ini Michael Doran - University of Texas at Arlington - EndUser 2006

6. Quick Review login.cgi generates a form... doran ******** ...authenticates credentials via an LDAP server... ...and tells WebVoyáge to display patron info Michael Doran - University of Texas at Arlington - EndUser 2006

7. Authentication adaptor tasks • Parse and store WebVoyáge query string • Generate HTML code for a patron login form • Query external authentication server • Insert entry into Voyager database table • Return control (and query string) to WebVoyáge Michael Doran - University of Texas at Arlington - EndUser 2006

8. From theory to concrete example • Example: an LDAP adaptor written in Perl • Do you have to use LDAP? – No • CAS • Kerberos • whatever • Do you have to use Perl? – No • JSP • ColdFusion • PHP • whatever Michael Doran - University of Texas at Arlington - EndUser 2006

9. Perl has the necessary “tool set” Authentication adaptor tasks • Parse and store WebVoyáge query string • Perl CGI module (however not used in example) • Generate HTML code for a patron login form • Perl CGI module (however not used in example) • Query external authentication server • Perl Net::LDAP module • Insert entry into Voyager database table • Perl DBI & DBD::Oracle modules • Return control (and query string) to WebVoyáge Michael Doran - University of Texas at Arlington - EndUser 2006

10. Perl modules • Perl comes with the CGI module • Endeavor should have installed the DBI and DBD::Oracle modules on your database server, but they probably won’t be on your WebVoyáge server. • You’ll almost certainly have to install Net::LDAP and it will have other prerequisite modules. • If you plan on encrypting your LDAP transactions (highly recommended), you’ll likely also need OpenSSL (not a Perl module) Michael Doran - University of Texas at Arlington - EndUser 2006

11. The split server decision • Separate Voyager database and WebVoyáge servers? Should the adaptor go on... • the Voyager database server... • already has Perl DBI & DBD::Oracle modules • security considerations – behind firewall? • or the WebVoyáge server? • need to install Perl DBI & DBD::Oracle modules • DBD requires (minimal) Oracle client installation • Testing on (integrated) Voyager test server Michael Doran - University of Texas at Arlington - EndUser 2006

12. The adaptor script • Line-by-line analysis of the entire source code Michael Doran - University of Texas at Arlington - EndUser 2006

13. Optional adaptor requirements (an oxymoron?) • Bypass default Voyager authentication, yet offer it as an alternative... i.e. both standard and external authentication on same form. • Adaptor login form “works” even if not invoked by WebVoyáge. • LDAP server failover redundancy. • Encrypt LDAP authentication sessions. • Adaptor login screen has working WebVoyáge buttons. • Clean up orphan entries in Voyager “wopac” table Michael Doran - University of Texas at Arlington - EndUser 2006

14. Two, two, two forms in one! One web page... two login methods Michael Doran - University of Texas at Arlington - EndUser 2006

15. Relevant code snippets $pid = $formdata{'PID'}; $seq = $formdata{'SEQ'}; $pweb_page = $formdata{'PAGE'}; sub PrintLoginForm { print qq(yada, yada); print qq(\t<input type="hidden" name="PID" value="$pid" />\n); print qq(\t<input type="hidden" name="SEQ" value="$seq" />\n); print qq(\t<input type="hidden" name="PAGE" value="$pweb_page" />\n); print qq(yada, yada); } PID, SEQ, and PAGE are key-value pairs in the original query string Michael Doran - University of Texas at Arlington - EndUser 2006

16. Reach out and touch someone Pwebrecon.cgi Michael Doran - University of Texas at Arlington - EndUser 2006

17. Relevant code snippet # Logic on what to do based on the input if ($external) { &AuthenticatePatron("$patron_ext_username", "$patron_ext_password"); } else { if ($pid) { &PrintLoginForm; } else { # If the login script URL is bookmarked, this will get it via # a detour thru Pwebrecon.cgi in order to pick up a valid PID print "Location: $webvoyage_base_URL/cgi-bin/Pwebrecon.cgi?DB=local&PAGE=pbLogon\n\n"; } } 0 0 0111 010111010 11010011 Michael Doran - University of Texas at Arlington - EndUser 2006

18. You’re the one that I want... LDAP redundancy pi.uta.edu LDAP server LDAP query ldap.uta.edu load balancer xi.uta.edu LDAP server Michael Doran - University of Texas at Arlington - EndUser 2006

19. LDAP redundancy in the adaptor # LDAP server variables # # University of Texas at Arlington LDAP servers: # ldap.cedar.uta.edu - LDAP server load balancer # pi.cedar.uta.edu - individual LDAP server # xi.cedar.uta.edu - individual LDAP server # # Connection approaches: # OK : Connect to an individual LDAP server. # Better : Connect to a LDAP server load balancer (if your campus has one). # This will distribute the load among available LDAP servers and # authentication will succeed even if one of the individual LDAP servers # is unavailable. # Best : Per the Net::LDAP documentation, create a list (array) of LDAP servers, # putting the LDAP load balancing host first, followed by the individual LDAP # servers. Reference the array, and connect to the array reference. Each # host in the list will be tried in order until a connection is made. This avoids # a single point of failure of either an individual LDAP server *or* the LDAP # load balancer. Michael Doran - University of Texas at Arlington - EndUser 2006

20. Relevant code snippet # List (array) of LDAP servers and array reference my @ldap_server = ('ldap.cedar.uta.edu', 'pi.cedar.uta.edu', 'xi.cedar.uta.edu'); my $rldap_server = \@ldap_server; # Create a new Net::LDAP object and open a connection # to an LDAP server. my $ldap = Net::LDAP->new( $rldap_server, version => 3, port => 389, debug => 0 ) or &AuthenticationFailure("1","$@"); Michael Doran - University of Texas at Arlington - EndUser 2006

21. Security is as security does LDAPS or TLS encrypted session LDAP query username/password username/password Voyager server w/ adaptor ldap server SSL Michael Doran - University of Texas at Arlington - EndUser 2006

22. Transport Layer Security (TLS) # The start_tls method converts the existing connection to # Transport Layer Security (TLS), which provides encrypted # traffic. It is an alternative to using LDAPS. # The verify options are 'none', 'optional', and 'require'. # The most secure option is 'require'. # If you set verify to optional or require, you must also set # either cafile or capath. If you have installed Apache with # SSL, you can probably use the ca-bundle.crt as your cafile # file, but make sure it has the necessary read permissions. Michael Doran - University of Texas at Arlington - EndUser 2006

23. Relevant code snippets # Create a new Net::LDAP object and open a connection # to an LDAP server. my $ldap = Net::LDAP->new( $rldap_server, version => 3, port => 389, debug => 0 ) or &AuthenticationFailure("1","$@"); my $mesg = $ldap->start_tls( verify => 'require', cafile => '/usr/local/apache/conf/ssl.crt/ca-bundle.crt' ); $mesg = $ldap->bind("$user", password => "$pw"); Michael Doran - University of Texas at Arlington - EndUser 2006

24. Working WebVoyáge buttons Can’t use static URLs for button links Adaptor generated login page Michael Doran - University of Texas at Arlington - EndUser 2006

25. Relevant code snippet ############################################################ # PrintButtons ############################################################ sub PrintButtons { print <<EOF; <a href="$pwebrecon_base_URL\PAGE=sbSearch&SEQ=$seq&PID=$pid"> <img src=“/images/UpSearch.gif" /></a> <img src="/images/DownLogin.gif" /> <a href="/cgi-bin/loginhelp.cgi"><img src="/images/UpHelp.gif" /></a> <a href="$pwebrecon_base_URL\PAGE=Exit&SEQ=$seq&PID=$pid"> <img src="/images/UpExit.gif" /></a> </div> EOF } Michael Doran - University of Texas at Arlington - EndUser 2006

26. Failure is an orphan • Aborted login attempts can result in “orphan” entries in the wopac_pid_patron_keys table • These orphan entries have the potential to prevent a subsequent login • The adaptor should delete any orphan entries that could prevent authentication by that user SQL> select * from xxxdb.wopac_pid_patron_keys; PID PATRON_KEY ---------- ------------------------------ 15699 1000053247 19303 1000458528 6250 1000266681 Michael Doran - University of Texas at Arlington - EndUser 2006

27. Relevant code snippet # Clean out any "orphan" entries in the wopac_pid_patron_keys table # that are associated with this patron. my $sql_string = "delete from $db_name. wopac_pid_patron_keys where $db_name. wopac_pid_patron_keys.pid = '$pid' or $db_name. wopac_pid_patron_keys.patron_key = '$institution_id'"; $sth = $dbh->prepare($sql_string) || warn $dbh->errstr; $sth->execute || warn $dbh->errstr; Michael Doran - University of Texas at Arlington - EndUser 2006

28. Includes • Consider putting the static HTML code (e.g. for portions of the web login form) in “include” files outside of your script • This keeps the script lean and allows you to easily view and validate the HTML portion by concatenating the include files together and viewing the resulting file in a browser Michael Doran - University of Texas at Arlington - EndUser 2006

29. Relevant code snippet sub PrintLoginForm { # Location of your HTML login form components (i.e. “includes”) # in relation to your Voyager cgi-bin directory my $form_dir = "../html/adaptor"; print "Content-type: text/html\n\n"; &PrintInc ("$form_dir/login0.inc"); if ($pid) { &PrintButtons; } &PrintInc ("$form_dir/login1.inc"); if ($pid) { print qq(\t<input type="hidden" name="PID" value="$pid" />\n); } &PrintInc ("$form_dir/login2.inc"); Michael Doran - University of Texas at Arlington - EndUser 2006

30. Advice for getting started • Read the Voyager documentation • “WebVoyáge Patron Authentication Adaptor feature” in the Technical User’s Guide • Learn about the authentication system you will be using (e.g. LDAP) • The protocol itself – specifically the API • How it is implemented at your university • Talk to your university’s IT people • Look at some example adaptor scripts Michael Doran - University of Texas at Arlington - EndUser 2006

31. Development & testing • Test server is nice but not necessary • You can easily develop and test with a WebVoyáge “preview server” type set up • First step should be to write a minimal LDAP client in your chosen programming language • You are welcome to modify/adapt UTA’s “login.cgi” adaptor script included as a separate handout Michael Doran - University of Texas at Arlington - EndUser 2006

32. Questions & (hopefully) answers doran@uta.edu Michael Doran - University of Texas at Arlington - EndUser 2006