Active Directory LDAP Plug-in

The Pharos Active Directory LDAP Plug-in 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 Pharos Active Directory LDAP Plug-in is compatible with Pharos 5.0 and later.

Note: This plug-in is different from the Pharos LDAP Plug-in, which supports any authentication system that provides a standard LDAP interface, but which requires special configuration to support Active Directory. The Pharos LDAP Plug-in is available on the Pharos CD at \tools\plugins\LDAP. See the Pharos Online Help for more information.

To install the AD LDAP Plug-in, copy the adldaplogon.exe executable to the pharos\bin directory of all Pharos servers.

To configure Pharos to use the AD LDAP Plug-in:

  1. Open Pharos Administrator.
  2. Create a new Bank called "ADLDAP Bank" at Charging > Banks.
  3. Select the new ADLDAP Bank, and click the edit box at the end of the Plug-ins property.
  4. Select the Logon Plug-in event.
  5. Enter the path to the adldaplogon.exe executable and click the < button to set the AD LDAP Plug-in as the Bank's Logon Plug-in. Click OK.
  6. Set Print and/or SignUp Services to use this Bank at Printing > Print Services > General tab and/or SignUp > SignUp Globals > SignUp Services > General tab.
  7. Set any Pharos Stations you wish to authenticate against an LDAP interface to use this Bank at Pharos Stations > PC Pharos Stations > General tab.
  8. Click the Change Control button.
  9. If Pharos Remote is being used, set adldaplogon.exe as the Pharos Remote Bank's Logon Plug-in at Charging > Banks > General tab.

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

Before the AD 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).

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:

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.

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