Request for feedback: New ILS Authentication module
Thu, 2009-02-26 17:32 — mark
I've been working on this module for a couple of weeks now and I'm at the stage where I'd like to see if it would be useful to other libraries. The module started off as a replacement for the aging and unmaintained III Authentication module I wrote back in 2006. Here at Simon Fraser University Library we are developing a thesis submission management application in Drupal and need to authenticate students against our Innovative patron records, and this second-generation module grew out of that new need.
Currently, if you install ILS Authentication you can allow new Drupal users to create accounts and log in using their Evergreen or Innovative credentials (either, not both -- the module only supports authenticating against one ILS). The Innovative driver is limited to barcode/name authentication against the III Patron API; I'll be adding a PIN option later. The Evergreen driver supports both XML-RPC and JSON APIs. I plan to work on a Koha driver over the next few weeks. There is also a sample driver that contains credentials for a single account, if you want to see how it works and you don't have access to any Evergreen or III accounts.
The module itself is linked at the bottom of this page, if you want to give it a try or even just look at the code. If you have an ILS you want to authenticate users of a Drupal site against, and you are able to write up a driver, let me know and I'd be happy to assist. It would be neat to include drivers for all major ILSs in the module distribution so local admins who want to manage their Drupal users via their ILS need only select the applicable driver and fill in a few configuration fields.
Thanks to Mike and Niles from the Evergreen development list, and Grant at UPEI, for assistance with the Evergreen driver.
Here's the README.txt file:
ILS Authentication
==================
Author: mjordan am sfu.ca
Last updated: 2009-02-26
IMPORTANT: This module is currently in late alpha state and SHOULD NOT
be used on a production site. For example, any accounts created using
this module are not dealt with in any way if you uninstall the module.
See top of ilsauthen.module file for important 'to do' items.
PURPOSE
-------
ILS Authentication is a framework for authenticating users of a Drupal site
against Integrated Library Systems. Each ILS needs to have a 'driver' in
order to work with this module. A driver is an .inc file that connects to the
ILS, queries its user database/API, and returns specific information to the
ILS Authentication module. This information is either TRUE or FALSE (depending
on whether the current user credentials authenticated against the ILS), and
(optionally) an email address for the account. Site admins who install ILS
Authentication must select which driver to use. The 'sample' driver is
installed by default.
Site admins who install ILS Authentication must select which driver to use.
The 'sample' driver is installed by default.
Existing local Drupal accounts (i.e., those created by the core user module)
are unaffected by his module.
FEATURES
--------
-Designed to easily support new authentication sources by using 'drivers',
which are PHP .inc files that contain only a few functions.
-Allows drivers to add their own admin settings.
-Allows drivers to modify Drupal forms for their own purposes, such as
the login form or the module settings form.
-Allows drivers to perform their own validation on the login form.
-Allows site admins to define default roles for user accounts created with
this module.
-Allows site admins to define driver-specific messages to substitute for
Drupal's core password reset email and to display on the user account
edit form.
-Not all external authentication sources can provide an email address for
the user. This module allows site admins to tell users that they must
add an email address to their profile.
-Provides an option to log usernames/passwords routed to external sources.
This feature is intended to assist driver developers and should be turned
off at all times other then during testing and debugging.
PREREQUISITES
-------------
The module itself has no particular PHP, database, or Drupal requirements,
other than it only works with Drupal 6.x.
Certain PHP configuration options must be enabled to allow drivers to
connect to their authentication targets. For example, if a driver connects
using a URL, file_get_contents or cURL must be enabled, depending on how the
driver is written. If a driver connects to an SQL database, the appropriate
PHP extension for that relational database must be installed. Note that in
Drupal 6, it is not possible to switch between Mysql and Postgres database
connections; this means that if you are running your Drupal site using
Mysql, you can only use other Mysql databases as external authentication
sources. This issue will is apparently being fixed in the new Drupal 7
database abstraction layer.
INSTALLATION
------------
Just like any other module: unpack the distribution in your site's module
directory, go to Administer > Site building > Modules, and enable. The module
does not create any database tables but does insert some entries into your
variable table. If you uninstall the module, these entries are removed.
ILS Authentication does not implement hook_perm(). If you want to grant
access to the admin interface, enable the 'administer site configuration'
permission under 'system module'.
By default, a 'sample' driver is installed. Site admins will need to select
another driver in the 'ILS Authentication' admin form, since 'sample' doesn't
connect to an external authentication source.
In order to illustrate how drivers can modify Drupal forms, the sample
driver changes the labels on the field in your site's user login form
to 'Your custom username field title' and '... and a custom password field
title.' To disable this, comment out the first 'if' block in sample.inc's
ilsauthen_form_alter_driver() function.
UNINSTALLATION
--------------
On uninstall, this module cleans up all {variable} table entries it inserts.
IMPORTANT: Currently, this module does not deal with accounts created using
external authentication sources. Therefore, DO NOT USE IT on a production
site. Sensible handling of such accounts is under development.
DRIVERS
-------
ILS Authentication comes bundeled with several drivers. You are encouraged to
write your own and if possible, contribute it to be distributed with the
module so others can use it. See drivers/sample.inc for inline comments
in addition to the following brief guide.
To create a driver, put the following four functions in a file in the
module's drivers directory. Your file must end in .inc and should be named
to describe what external authentication source it connects to. However,
since the file's name (without the .inc) appears in the Drivers select list
in the module's settings form, keep the name short.
ilsauthen_driver_meta() defines basic information about the driver. Currently,
only the name is defined.
ilsauthen_form_alter_driver() allows you to modify Drupal forms using
hook_form_alter(). $form[$reset_password_message_element] is required, as it
stores the message that users will be sent to when they request new passwords.
This message is required because Drupal doesn't manage passwords for accounts
created by external authentication services.
ilsauthen_driver_validation() allows you to validate form elements that you
add using ilsauthen_form_alter_driver() or any other elements you need to
validate.
ilsauthen_get_email_address() simply returns the account's email address back to
the ilsauthen module. In most cases you can use an exact copy of this
function as it appears in the sample.inc driver.
ilsauthen_driver_connect() is the function that actually connects to the
external authentication service. This function can be quite complex, depending
on how you need to connect to the external service and what type of data you
need to manipulate to determine if the user's credentials authenticate
against the service. At a minimum, this function must return TRUE if the
credentials authenticate and FALSE if they don't. Optionally, you can populate
the $_SESSION['ilsauthen_driver_mail_address'] variable inside this function
(if your external authentication service stores user email addresses and you
can access them) so that user accounts created with ILS Authentication will
contain an email address. Drupal allows programmatic creation of user accounts
with no email address but without one, the user will not be able to receive
messages from the site and they won't be able to update their account profile
without adding an email address, since the account edit form makes the email
address field required.
SECURITY
--------
ILS Authentication does not require, or add, any specific security measures
beyond those provided by Drupal itself. If you write a driver for an external
authentication service, you need to secure the connection between Drupal
and the service yourself. Since most drivers will use some sort of web
service to connect to authentication services, you should consider using the
standard technologies that other web clients and servers use, such as HTTPS,
restricting access to your external service via localhost (where possible)
or IP range, etc.
Passwords for accounts managed by external authentication sources are not
stored in the local Drupal database. On account creation, Drupal creates a
randomly generated password for the user but this is not used. All
authentication for external accounts is handled by the external source.
Since the sample.inc driver contains credentials in ilsauthen_driver_connect()
that anyone can use to log into your site (provided you have this module enabled),
you may want to change the sample password. DO NOT DELETE sample.inc.
As stated above, this module provides an option to log usernames/passwords
routed to external sources. This feature is intended to assist driver developers
and should be turned off at all times other then during testing and debugging.
----------------
End of README.txt| Attachment | Size |
|---|---|
| ilsauthen.zip | 23.56 KB |
This work is licensed under a Creative Commons Attribution- NonCommercial- ShareAlike 2.5 License.
Comments
Works with Evergreen
Quite fantastically, actually! Out of the box!
This solves my issue of not being entirely sure how I was going to authenticate against our Evergreen ILS with our soon-to-be Drupal website.
Thanks for testing it out
That's good to hear. Thanks for testing it out.
You might want to mention
You might want to mention that in order for this to work with the III ILS, a library would actually have to have purchased the Patron API product, which is an optional product.
Yes, III Patron API is required
Bob, that's a good point, thanks. I'll include that in the revised README and the III driver. Alejandro has done some work on walking the III login form for authentication but I didn't incorporate his code into the III driver. I plan on doing that though, so just like with the Evergreen driver, the III driver will provide two options for authenticating users.
Code for III Authentication with no Patron API
I'm currently working on adding this functionality into the Drupal Millennium module; right now you can fetch the 6.x-2.x-DEV version to try it out NOTING that: (a) It might eat your site, so don't try it on a production server. (b) It probably won't work out of the box, unless you modify some of the regular expressions in patroninfo.inc.
The module is here: http://drupal.org/project/millennium
I need to arrive at module settings that'll work in (almost) every WebOpac regardless of settings, to ease barriers to entry to using this module. Testers are welcome!
When I have this working a bit better, I'll post back here =)
What should happen when this module is uninstalled?
I'd like some feedback on my plan to handle what happens when this module is uninstalled. Since this module creates Drupal accounts on the fly from external authentication sources, and does not store the account's password locally, once the module is uninstalled there will be no way for Drupal to authenticate these users against the originating external source. My plan is as follows (taken from the UNINSTALLATION section of my latest README.txt):
Accounts created using this module are converted to "regular" Drupal local
accounts (that is, the association between the ILS Authentication module
and the accounts is deleted). However, because the external authentication
source, and not the local Drupal, was managing account passwords, users of
accounts created by this module will not be able to log in after the module
is uninstalled. This is because on account creation, Drupal generates a
random password for users and stores it in the {user} table. ILS Authentication
never changes this original (random) password since it delegates
authentication to the external source.
After this module is uninstalled, the next time users of accounts it created log in,
they are presented with the standard Drupal error message that appears when
the supplied password does not work, i.e., "Sorry, unrecognized username or
password. Have you forgotten your password?". They then must request a new
password from the site in the usual manner.
Does anyone think this is an unreasonable way to handle accounts created by this module? The only other option I can think of is for this module to update the {user} table with the user's external password every time the external source authenticates them, thereby storing a copy of their external password. Then, when the module is uninstalled, they will not notice the difference since they will be using the same password that they used the last time they logged in.
uninstalling..
I think requiring the user to request a new password might be the best way. That way, the user has some indication that the link between their online catalog account and their website account has been broken. If you just silently set their local Drupal password to the ILS password every time, uninstalling the module wouldn't cause the end user any issue at all -- until they changed their password on one site or the other -- then there would be quite a lot of confusion!
I think any organization that chooses to unlink their website authentication from their ILS authentication would have to seriously consider all the ramifications of doing so, however, and should definitely post a news entry informing all users of the change when it happens in order to prevent a flurry of support calls.
Speaking as a Library Tech, any unannounced change in the ways patrons interface with technological systems will always result in many many phone calls and e-mails. :)
Also, it looks like we are planning to use this on our new Drupal website, but we really would like patrons to be logged into our OPAC when they authenticate with Drupal using this module, so we'll probably try to figure out a way to make that happen so they can view/place holds, renew items, etc without having to log into the OPAC separately.
Thanks again!
Already added solution
All good points. A couple of weeks ago, I integrated the solution I describe in the previous comment but didn't update this page (some paid Drupal work took priority, but now I'm posing this comment on a new Mac paid for partly by that work!), namely that if the remote login is successful, this module updates the user's record with a hashed version of the password they entered. Now, when the module is uninstalled, the _local_ password is the same as the last valid password used to authenticate against the remote service.
It wouldn't be difficult to allow the local admin to control whether the remote password is stored or not. I certainly agree that any major changes in the way users authenticate should be explained clearly. In either case, some users are going to be SOL when logging into the Drupal site, so I guess it's a question of how the local library wants to handle this situation.
Your plan to allow users to view holds, renew items, etc. is commendable, and I think that as long as your ILS is open enough to allow a remote site to do this, Drupal is up to the job. In particular, the XML-RPC handling is extremely straight forward, since Drupal has a built in client and server. But whatever protocol/method you use, I doubt if you'll be limited by the Drupal end of the conversation.
I'm waiting to hear back from one site that wants to use Evergreen barcodes instead of usernames, but when I get that worked out, I'll post a new version of the module, hopefully one that will be functional enough to do some prerelease testing.
ILS Authentication update
It's been two months since I announced this module, and I've got it pretty much ready to set up as a contrib project on d.o. I've got to get my head around using their cvs but that's all that's holding me back.
Some features/fixes that have been added:
Thanks to everyone who provided feedback and help test the module so far.
ILS Authen .zip file updated
I've just replaced the -dev .zip package I originally posted with the latest version (May 4), as someone has asked for it. I still haven't started a project on d.o. but will get in gear and do so this week. This version integrates all the changes described in the previous comment.
Post new comment