Creating an LDAP Patron Authentication AdaptorMichael Doran, Systems Librarian

University of Texas at Arlington

Endeavor Users Group Meeting, Chicago, ILSession 46, Friday, 21 April 2006

(using Perl)

Michael Doran - University of Texas at Arlington - EndUser 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...

[1] “Overview of Voyager External Patron Authentication” EndUser 2005, Technical Session 20

Not something tobe switched on...

...but rather somethingthat had to be built.

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

opac.ini

[ExtAuthenticationSystem]ExtAuthSystemEnabled=YExtAuthBypassLoginScreen=YExtAuthSystemURL=login.cgi

Michael Doran - University of Texas at Arlington - EndUser 2006 6

Quick Review

doran

********

login.cgi generates a form...

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

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

Perl has the necessary “tool set”

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

(an oxymoron?)

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 PAGEare key-value pairs in theoriginal 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"; }}

0111 0101110100

110100110

Michael Doran - University of Texas at Arlington - EndUser 2006 18

You’re the one that I want...

ldap.uta.eduload balancer

pi.uta.eduLDAP server

xi.uta.eduLDAP server

LDAP redundancy

LDAP query

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

ldap serverVoyager serverw/ adaptor

LDAP query

username/password

encrypted session

LDAPS or TLS

username/password

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

Adaptor generated login page

Can’t use static URLs for button links

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