Authentication

SUMMARY

In some cases, libraries may want to import users to the ILLiad database rather than have customers register and create accounts themselves. In order to do this, however, you will need to choose usernames and passwords for your users. The username can be any string under 20 characters. The password can be any length, but is stored in the ILLiad database using MD5 one-way encryption. To create those passwords ahead of time for users, you will need to convert the password from plain text to an encrypted value.

Using the text "ill" as an example, the ILLiad version of that password would first be converted using standard MD5 encryption to the hexadecimal value:

2F9C691594932556EF427450338A74B7

The hexadecimal value would then be converted to a decimal value, two characters at a time:

47156105211481473786239661168051138116183

where 2F converts to 47, 9C converts to 156, 69 converts to 105, etc. You may use any tools you choose to create these passwords on your own and load them pre-encrypted. If you do not have that option, however, you can use the following tool to convert the password after loading it to the Users (or UsersALL for Shared Server installations) table.

WARNINGS

The following tool is for advanced users who have an understanding of how to load data to a SQL database. This program can be run on a schedule or manually but will affect every user in the Users table regardless of NVTGC. Please test this thoroughly before using in production.

Note: See the SQL Help files on DTS Import/Export Wizards or Creating a DTS Package for further information on how to import data.

USING THE MD5USERPASS.EXE TOOL

To run the MD5 ILLiad User Password Tool, you must run it on a machine that has a BDE Administrator and SQL connectivity to the SQL Server. This may be your web server or your SQL Server if they are separate. It would most likely be scheduled to run immediately after the import of users from an outside source to the database. The MD5 ILLiad User Password Tool does the following:

• Queries the ILLiad database's Users table for any records where Special = 'PTP' (for plain text password).
• Updates those user records so that the password is the MD5, numeric version of the original text.
• Changes the Special field from 'PTP' to NULL (the default blank value).

This means when you load the user information that has a plain text password, you would also need to set the Special field to 'PTP' for the tool to find it and convert the password.

COMMAND LINE PARAMETERS

You can run the executable from any folder on the machine and it can be scheduled via Windows Scheduled Tasks. There are two command line parameters that can be added to the program when it runs:

AUTO
This allows the program to run with no user input. It will run, convert the passwords and close on its own. (i.e. c:\illiad\admin\MD5UserPass.exe AUTO)

HIDEGUI
This can be added as well so that when the program runs automatically, it will run minimized. (i.e. c:\illiad\admin\MD5UserPass.exe AUTO HIDEGUI)

DOWNLOAD

The following link is a zipped file of the MD5UserPass.exe.

MD5 ILLiad User Password Tool

SUMMARY

In order to authenticate using PatronAPI, there are several keys that need to be set in the Customization Manager under Web Interface .. Innopac. The keys are described below.

EXAMPLES

InnopacPatronAPIAddress: This the the location of the PatronAPI server. Normally, the key also has a port after it of 4500. An example value would be http://123.123.123.123:4500 - where 123.123.123.123 is the PatronAPI server at your site. Also, the ILLiad server needs to have access to query the PatronAPI server. Most PatronAPI servers restrict access by ip address.

InnopacPatronAPIExclusive: This key should be set to Noif customers not in the PatronAPI server should still be allowed to register and Yes to only allow customers who pass the PatronAPI authentication to register with ILLiad.

InnopacPatronAPIExpireDate: Set this key to Yes to have ILLiad check if a customer is expired before allowing registration.

InnopacPatronAPIField: This is the field that ILLiad sends to the PatronAPI server for authentication. Currently the only two values allowed for this field are SSN or Number.

InnopacPatronAPIFineBlock: Set this key to Yes to have ILLiad check if a customer has exceeded his or her fine limit beforing allowing registration. If this is set to Yes, there needs to be a key for every Patron Code allowed to use ILLiad. There are some examples in a default installation of 0, 1, 2, etc. But for each code, there needs to be the value for number of dollars before customers can no longer register or use ILLiad.

InnopacPatronAPISupport: Set this key to Yes to turn on PatronAPI authentication.

TESTING CONNECTIVITY WITH YOUR PATRONAPI SERVER

To test connectivity with your PatronAPI server using an internet browser, open the browser and go to the following URL:

http://<YourPatronAPIServer>:<YourPatronAPIPort>/PATRONAPI/<UserNumberBeingUsedForVerification>/dump

An example would look something like this:

http://123.123.123.123:4500/PATRONAPI/123456789/dump

This will tell you if the necessary connectivity exists.

If you receive a message like the following, you do not have access from the machine from which you tried to connect.

403 Forbidden
No access permitted from 123.123.123.123

If you receive a message like the following, you have the appropriate level of access.

REC INFO[p!]=p
EXP DATE[p43]= - -
PCODE1[p44]=
PCODE2[p45]=
PCODE3[p46]=0
P TYPE[p47]=3
TOT CHKOUT[p48]=102
TOT RENWAL[p49]=103
CUR CHKOUT[p50]=2
HOME LIBR[p53]=none
PMESSAGE[p54]=
MBLOCK[p56]=-
REC TYPE[p80]=p
RECORD #[p81]=1062432
REC LENG[p82]=335
CREATED[p83]=06-17-94
UPDATED[p84]=08-20-04
REVISIONS[p85]=242
AGENCY[p86]=1
CL RTRND[p95]=0
MONEY OWED[p96]=$0.00
BLK UNTIL[p101]= - -
CUR ITEMA[p102]=0
CUR ITEMB[p103]=0
PIUSE[p104]=0
OD PENALTY[p105]=0
CIRCACTIVE[p163]=08-20-04
PATRN NAME[pn]=LASTNAME, FIRSTNAME MI
ADDRESS[pa]=LIBRARY ASSOCIATE$Library Admin$Library$
ADDRESS2[ph]=123 Library Rd$Librarytown VA 12345
TELEPHONE[pt]=1234567
TELEPHONE2[pp]=1234567
UNIV ID/SS#[pu]=123456789
P BARCODE[pb]=12345678912345
EMAIL ADDR[pz]=emailaddress@atlas-sys.com
PTYPE2[pd]=STAFF
LINK REC[p^]=i

SUMMARY

There are 5 different types of authentication available to ILLiad users with a default install:

Basic ILLiad Authentication is the default option. This version allows the user to select a username and password and register with the system. They are placed in a queue for the staff user to review, who can then allow access, or disavow the user, automatically cancelling all of their requests.

LDAP Authentication is another type of authentication available to ILLiad users. If you have an LDAP server with an authoritative database of users, you can point ILLiad to it for authenticating users as they log in. This is a live link and is used at each logon.

Importing an Authentication Database is another available option. From an OPAC or similar system, you can download patron information into a file format that is compatible with SQL Server, then import those entries into the ImportValidation table in ILLiad. Users are checked against this list when they register (using the model in the Basic ILLiad Authentication above) and if they are in the list, skip the staff review queue. If they are not in the list, they are still allowed to register, but then must be reviewed. You can import block information as well.

Implementing a User Gateway using an Authentication Database is another option. This way works similarily to the Importing an Authentication Database, but will not allow access to patrons not in the Authentication Database.

III's PatronAPI is an option for Innopac sites who have purchased this module from III. A user will register with ILLiad, giving the system in one of the registration fields their "patron number". This matches to a number within the Innopac system and is used for validating the registration as well as for subsequent logons to the system. This can be set to be exclusive (allow only people within this database access) or non-exclusive. Fines, blocks, and expirations are all carried over to ILLiad as well.

MORE INFORMATION

For more information on each of the authentication options, choose a related article from the panel on the right.

SUMMARY

ILLiad has a built-in authentication system that will allow you to clear customers as they register with the system. Here is a scenario using this authentication scheme:

For the User

• A first time user would get to the ILLiad logon screen and click the First Time Users link.
• User will fill out the New User Registration form (NewUserRegistration.html) and submit it.
• User can then start immediately submitting requests.
  

For the Staff

• Several times a day, the staff user would select the Clear New Customers option from the Pre Processing menu in ILLiad. This will show a list of all newly registered users.
• After reviewing each one, they can click the Clear, Disavow, or Merge buttons. Each will send the user a note regarding their current ILLiad status. Disavow cancels all of their requests. Merge will allow you to merge two accounts together.

This is how ILLiad is configured to work upon completion of the installation. No changes are needed to the system to configure it for Basic ILLiad Authentication. All User information is stored in the ILLiad system.

MORE INFORMATION

For a discussion of the available authentication types ILLiad supports, review the related articles in the panel on the right.

SUMMARY

The ExpirationDate field in the Users table can record a date X number of days after the initial date a customer registers with ILLiad (if registering through web pages). That date can be set using the UserExpiration keys found under Borrowing .. Customer Clearance in the Customization Manager. The keys can be set for each Status in the Users table (if your status is not in the table you can add it to the Customization table under System .. General).

The expiration date does not restrict customers from logging into ILLiad or access the web. It only serves as a date to run custom queries against (using Access or some other table link) to find users who have registered within a certain time period. Any blocking or restricting of access would have to be done manually through the ILLiad Client.

SUMMARY

LDAP Authentication can be used in place of the Basic ILLiad Authentication. Here is a
scenario using LDAP for authentication.

For the User

• A first time user would get to the ILLiad logon screen and put in their LDAP UID for the ILLiad username and LDAP Password in place of the ILLiad password.
• ILLiad checks the LDAP server, using the supplied information. If it can successfully bind using the userid and password, then it goes to the next step. If not, it immediately returns a message to the user stating "Bad Username or Password".
• When the username and password are good, next ILLiad looks in its local Users table to see if they have registered before. If yes, then they are automatically routed to the Main Menu. If not, then they are taken to the New User Registration page where they can fill out the registration information. All of their information is stored in the ILLiad Users table. The LDAP server is used for authentication purposes only.
  

For the Staff

• Since the LDAP server is used for authentication purposes, the staff do not need to review any customers as they register.
  

Setup

Setting up LDAP authentication involves updating several keys in the customization table. Here is a list of the keys and what their purpose is.

LDAPSupport - Yes or No to turn LDAP on or off.
LDAPServerName - LDAP Server name or IP address.
LDAPPortNo - port for your LDAP server (389 is default regular LDAP and 636 is default for SSL)
LDAPSearchPrefix,LDAPSearchSuffix - strings around which the ILLiad username is placed in order to bind with the LDAP server.

MORE INFORMATION

For a discussion of the available authentication types ILLiad supports, review the related articles in the panel on the right.