Authenticating Against an LDAP System

The Pharos LDAP (LDAPLogin.exe) Plug-in is a Logon Plug-in that interfaces with any authentication system that provides a standard Version 2 Lightweight Directory Access Protocol (LDAP) interface.

The LDAP plugin does a simple bind against the LDAP server, using the standard LDAP method (ldap_simple_bind_s). The authentication method is set to LDAP_AUTH_NEGOTIATE, allowing the underlying Microsoft library to make an appropriate choice based on client and server capabilities.

Windows Active Directory uses a non-standard LDAP interface. Although the Pharos LDAP Plug-in can be configured to work with Active Directory, Pharos Systems recommends that you use the Pharos Active Directory LDAP Plug-in instead.

How the LDAP Plug-in Works

The Pharos LDAP Plug-in allows users to be authenticated against any authentication system that provides an LDAP version 2 interface (e.g. Novell Directory Services, OpenLDAP).

The plug-in authenticates against an LDAP server via a two-step process:

The "Search Bind" - the plug-in searches for a Distinguished Name whose entry has the same User ID as that passed to the plug-in. In order to search the LDAP database it is necessary to first bind (log on) using either an anonymous bind or using the Root Distinguished Name and associated Root Password. Once this bind succeeds, the plug-in searches for the Distinguished Name in each specified search base (see below).
The "Validation Bind" - the plug-in attempts to bind to the LDAP server with the Distinguished Name and Password found during the Search Bind. The plug-in then reports the success or failure of this bind.

Using the Plug-in

To install the LDAPPlug-in, copy the executable LDAPLogin.exe to the pharos\bin directory of all Pharos servers.

The Pharos LDAP Plug-in is a separately chargeable component of the Pharos system. Contact your Pharos Authorized Reseller if you want to use this plug-in.

To configure Pharos to use the LDAP Plug-in:

Copy the LDAPLogin.exe file to the Pharos\bin folder.
Open Pharos Administrator.
Create a new Bank called "LDAP Bank" at System > Banks.
Select the new LDAP Bank, and click the edit box at the end of the Plug-ins property.
Select the Logon Plug-in event and choose executable plug-in.
Browse to the Pharos\bin folder and then select the LDAPLogin.exe file you have copied earlier.
Click OK.
Set Print and/or SignUp Services to use this Bank at System > Server Configuration > Pharos Print Server > Bank and/or System > Server Configuration > Pharos SignUp Server > Bank.
Set any Pharos Stations you wish to authenticate against an LDAP interface to use this Bank at Release Stations > [selected Pharos Station[ > General category.
Click the Change Control button ( ).
If Pharos Remote is being used, set LDAPLogin.exe as the Pharos Remote Bank's Logon Plug-in at System > Banks > General category.

Configuring the Plug-in

Before the plug-in can be used, the registry must be manually edited to contain the configuration details that the plug-in needs to function. To set up the registry:

Open the Registry Editor (regedit).
Create a new key called LDAP Plugin under HKEY_LOCAL_MACHINE\Software\Pharos.

The following values must be created and configured:

Name	Type	Meaning
hostname	REG_SZ	A domain name, or a space-separated list of host names or dotted IP addresses of hosts running an LDAP server to connect to. Each host name in the list can include an optional port number, separated from the host itself with a colon ( : ).
base1, base2, ... baseN	REG_SZ	Specify as many search base values as necessary (must start with "base1"). Each node in an LDAP directory tree is identified by its "Relative Distinguished Name" (RDN). A search base is an RDN to search in. A typical base entry looks like "o=Pharos,c=NZ", where the root node is of class "c" and has a name "NZ", and you wish to search the "o=Pharos" node under the root.
use anonymous bind	REG_DWORD	LDAP systems require binding to before they can be searched. However, it is possible to specify an anonymous user. Default is 0 (false).
root dn	REG_SZ	If "use anonymous bind" is set to false, this value must be specified. The root distinguished name (and root password) is used if the LDAP system requires an authenticated login before it will allow searching. The root distinguished name is an entry in the LDAP database that is always valid - typically "cn=root," plus the Distinguished Name of the root of the directory.
root password	REG_SZ	If "use anonymous bind" is set to false, this value must be specified. See above.

The following optional values may be created and configured:

Name	Type	Meaning
active directory	REG_DWORD	Windows Active Directory uses a non-standard LDAP interface. When this value is set to 1, the LDAP Plug-in modifies its behavior to be compatible with Active Directory. See below for more information.
allow blank passwords	REG_DWORD	Some LDAP systems will treat a bind request with no password as an anonymous bind. If blank passwords are allowed on such a system then a blank password will always succeed the Validation Bind. Recommend leaving this set to false (0).
search scope1, search scope2, ... search scopeN	REG_DWORD	Specify as many search scope values as necessary. The Search Scope entries correspond to the Search Base entries with the same index, i.e. "search scope1" applies to "base1". 0 = BASE - Checks to see if the user is the node specified by the corresponding base entry. 1 = ONE - Searches for the user in the first level below the node specified by the corresponding base entry. 2 = SUB - Searches for the user in all levels below the node specified by the corresponding base entry. Any base without a corresponding search scope entry defaults to Search Scope = SUB (2).
timeout	REG_DWORD	Timeout for connection to the LDAP server (in seconds). Default is 120.
use SSL	REG_DWORD	Specify if SSL authentication is to be used (0 = false, 1= true.). Using SSL encrypts network traffic, so that passwords can't be sniffed off the network. To enable SSL, the LDAP database must be configured to use SSL, and the server and client issued with the appropriate SSL certificates.
logon attribute	REG_SZ	This is the name of the attribute that holds a patron's "logon name" in a User entry in the LDAP system. Most systems use the "cn" attribute for this, and this is what LDAP will search on if this registry entry is not present.
use aliases	REG_DWORD	Set this value to 1 if the LDAP system uses aliases. Default is 0 (false).
use LDAP version3	REG_DWORD	If this value is set to 1, LDAP version 3 will be used. If it is set to 0 or does not exist, LDAP version 2 is used. If SSL is used, LDAP version 3 will always be used, regardless of this value, as SSL is only supported by version 3.
extra attribs	REG_SZ	This is a comma-separated list of any extra attributes that the plug-in is to return along with validating the logon. These extra attributes can be used for advanced customizations, e.g. just-in-time user creation. Attribute names are case sensitive.

The root dn and root password values, while not strictly speaking necessary, are required in the default configuration.

Windows Active Directory

To use the Pharos LDAP Plug-in with Active Directory, configure the Plug-in as follows:

Configure the hostname registry value as required.
Specify a value for the base1 registry value. This may be anything - the Plug-in requires that this value be present, although it is not actually used with Active Directory.
Set the active directory value to 1.
Set the use anonymous bind value to 1.
Set the use SSL value to 0 or 1, depending on whether SSL is used or not.

No other registry values are required.

The extra attribs registry value is supported with Active Directory provided that root dn and root password registry values are specified.

Also, Windows Active Directory uses the Display Name when logging on via LDAP, so users' Active Directory Display Names must be the same as their Pharos User IDs.

Using the LDAP Plug-in without SSL

When SSL is used, LDAP version 3 will always be used, as SSL is only supported by version 3. However, when SSL is not used (i.e. the use SSL value is not present or set to 0), the Plug-in attempts to bind using the version 2 LDAP protocol by default. Newer versions of some LDAP software, e.g. OpenLDAP, require version 3.

To use OpenLDAP 2.1 or later with the Pharos LDAP Plug-in, either add the following to the file slapd.conf above the first "database" line:

set allow bind_v2

Or enable the use LDAP version3 registry value (see above).

Testing the Plug-in

Test the plug-in against a user account before using it with Pharos. The user account should exist in the LDAP database, and in the Pharos Database (the account in the Pharos Database should not have a password). To test the plug-in, run the following from the command line:

LDAPLogin.exe [filename] [level] [username] [password]

Where:

[filename] is the full path of the file that results will be written to
[level] is the Pharos access level of the user being tested; required but currently has no effect. However, entering "trace" for the level parameter instead of an access level will output debug information to the command line.
[username] is the Pharos Logon ID of the user being tested
[password] is the password in the LDAP database for the user being tested

The results of the test will be written to the specified file. If the test is successful, "OK" and the returned values of any extra attributes (as specified by the extra attribs registry value) will be written to the file. If the test fails, the file will contain "FAIL", and an error message explaining why the test failed.

As of Uniprint 8.3, this plug-in now returns extra attributes correctly as strings. In previous versions, these were returned as single characters instead of strings.