Authenticating against an Active Directory System

The Pharos Active Directory LDAP Plug-in (adldaplogon.exe) is a Logon Plug-in that interfaces with a Windows Active Directory system using the Lightweight Directory Access Protocol (LDAP). The plug-in checks all specified servers for a user's authentication details, returning success if the user is found on any server. (The servers and the order they are checked in are specified in the registry - see Configuration below.)

The ADLDAP plugin uses the ldap_bind_s function, but uses MS-specific behavior.

Using the Plug-in

To configure Pharos to use the LDAP Plug-in:
  1. Open Pharos Administrator.
  2. 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.
  3. Set any Pharos Stations you wish to authenticate against an Active Directory interface to use this Bank at Release Stations > [selected Pharos Station ] > General category.
  4. Click the Change Control button ( ).
  5. If Pharos Remote is being used, set adldaplogon.exe as the Pharos Remote Bank's Logon Plug-in at System > Banks > General category.

If you are migrating to the AD LDAP Plug-in and wish to avoid affecting existing logon functionality, it is a good idea to set up a test Pharos Station first. Once configuration and testing has been completed on the test Pharos Station, all other Pharos Stations can be changed to use the AD LDAP Bank.

Configuring the Plug-in

Before the Active Directory LDAP Plug-in can be used, the registry must be edited to contain the configuration details that the plug-in needs to function. You can either edit the registry manually, or set it up from the command line (see below).

The plug-in requires a key called AdLdapLogon under HKEY_LOCAL_MACHINE\Software\Pharos\Plugins\, with a key underneath that called Servers. The Servers key must contain a string value for each server that the plug-in will search for users. The value name is the search priority, and must be a number (lower numbered servers are searched first). The value data contains five fields, separated by colons:

  1. Server name (or domain name)
  2. Username
  3. Password
  4. Port number
  5. SSL

The server name can be either a specific server, or the domain name. If using the domain name, use only the DC (DomainComponent), rather than the fully qualified domain name. However, if SSL is used, the name specified must match the server name as it appears on the server's SSL certificate, i.e. if the fully qualified domain name appears on the certificate, then the fully qualified domain name must be specified; if the server's IP address appears on the certificate, then the IP address must be specified, and so on.

The username and password must belong to a user that the plug-in can use to access the LDAP database; this only needs to be an ordinary user, with no special privileges. The SSL value must be 1 or 0, depending on whether or not SSL is used to encrypt communications (1 = use SSL, 0 = no SSL).

If you set the port number to 636 (LDAP SSL), the plug-in will always use SSL, even if the SSL value itself is set to 0.

To make configuration easier, the plug-in accepts some command line options to automatically create/update the registry settings. Each option has a long form (e.g. add-server) and a short form (e.g. -a) - either one can be used.

Add a server:

adldaplogon --add-server <priority> <server> <user> <password> [<port>] [<ssl>]
adldaplogon -a <priority> <server> <user> <password> [<port>] [<ssl>]

Notes:

  • If an existing server has the same priority, it will be overwritten.
  • The port number is optional.
  • <ssl> must be either 1 (= use SSL) or 0 (= no SSL).
  • <ssl> is optional; if it is not specified, SSL will not be used. However, if it is specified, a port must be specified as well (636 is the default port for LDAP with SSL).
  • If SSL is used, <server> must match the server name as it appears on the server's SSL certificate, e.g. if the fully qualified domain name appears on the certificate, then the fully qualified domain name must be specified for <server>.

Delete all servers:

adldaplogon --clear-servers
adldaplogon -c

Delete a specific server:

adldaplogon --drop-server <server>
adldaplogon -d <server>

List all servers currently configured:

adldaplogon --list-servers
adldaplogon -l

Testing the Plug-in

Test the plug-in against a user account before using it with Pharos. The user account must already exist in the Active Directory database. If you are using SSL, all relevant SSL certificates should be installed. To test the plug-in, run the following from the command line:

adldaplogon.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 (this value is not actually used by the plug-in; however, entering "trace" for the level will cause information about the logon process to be output to the screen)
  • [username] is the 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" will be written to the file. If the test fails, the file will contain "FAIL", and an error message explaining why the test failed.

If trace information is enabled, it may contain error messages even if the test succeeds. This is because different Active Directory systems use different user attributes when doing an LDAP bind for the user. The AD LDAP Plug-in must therefore check all available attributes for the user account, some of which may fail before the bind is successful. As long as "Success!" appears at the end of the trace information, the bind was successful.