As a prerequisite, note that the Hansoft Server needs to have a sufficient number of users tied to its license if the LDAP Integration is to create new resources.
The four user accounts central to a properly configured Hansoft LDAP Integration are:
The Hansoft SDK account created in Hansoft in order for the Hansoft LDAP Integration client to connect to the Hansoft server.
The LDAP user account that the Hansoft LDAP Integration uses to request information from the LDAP directory server. A dedicated service user account should be created in the LDAP directory before performing the Hansoft LDAP Integration. This account only requires read-only permissions to the LDAP directory.
The e-mail server account on the SMPT server used by the Hansoft LDAP Integration to send notification e-mails.
An administrative e-mail recipient account to which the Hansoft LDAP Integration addresses its notification e-mails. Correct configuration of this email address and the SMTP e-mail server network address is very important, as detailed diagnostic information is sent to it.
You will also need the network addresses (DNS or IP address) and port numbers of the Hansoft server, LDAP directory server and SMTP e-mail server that the Integration should connect to. In addition to the name of the Hansoft server you will need the name of the server database whose resources the authentication integration will synchronize.
All diagnostic information is also logged in the Hansoft LDAP integration log files (in the \Log folder under the Integration's installation folder), facilitating functional verification and troubleshooting. The Hansoft LDAP Integration runs as a service that can be located on any server able to connect to both to the Hansoft server and the LDAP directory server. Note: best practice is not to install the Hansoft LDAP integration module on an Active Directory domain controller, as the LDAP integration service itself runs under Local System account permissions by default.
The Hansoft SDK Account is created using the Hansoft client as the user Administrator, while all other Hansoft LDAP integration settings are specified in the AuthIntegrationSettings configuration file found in the installation root folder. Please refer to the example configuration file in the appendix of this document and verify that you have the necessary information available before performing the installation.
After you have installed your Hansoft sandbox server, log in with the default Hansoft Administrator account, "Administrator". This is the only account permitted to create SDK accounts.
When you have logged in, upgrade your license to one with the Hansoft SDK module enabled, if you have not done so already. The license upgrade is delivered via e-mail if the server is not connected to the Hansoft license server. If you are connected to the Hansoft license server the SDK module will be automatically enabled when email@example.com has been contacted and confirmed its activation.
Once you have a license with the SDK module enabled and are logged in as the "Administrator" user, the
Create SDK user button will become visible. Press this button to create the Hansoft SDK Account.
If the LDAP Integration is to support Windows (e.g. Kerberos) authentication, you must check the "Account can provide login authentication integration services" checkbox. The second check-box enables the Integration to support authentication on behalf of other Hansoft SDK Integrations, you can leave it unchecked for now and change it later. For the welcome notification emails to display the correct URL and network for your Hansoft server, you also need to check the hostname configuration (click Edit hostname):
You can now run the HansoftAuthIntegration.exe installer program to install the service. The installer will launch a text editor so that you can edit the configuration file, which is "c:\Program Files (x86)\Hansoft\Auth Integration\AuthIntegrationSettings" if you accept the default installation folder. The installer will wait until you close the editor, before completing the installation.
The comments in the configuration file documents the different settings. The most important part to fill out correctly during the initial installation is the email configuration. All errors and notifications are sent to the administrator through email, so make sure that you have the email correctly configured before you edit the other options.
Aside from account names and server network addresses, the main configuration task is to edit the AutocreateResources section, to specify the LDAP query defining the set of LDAP accounts to synchronize with Hansoft users. This is usually done by querying for the users of an LDAP user group created for this purpose, such as "Hansoft Users". This way, if a user is added to the Hansoft LDAP group then the Hansoft LDAP Integration can automatically create the corresponding Hansoft user on the Hansoft server.
After you have completed your changes to the configuration, close the editor to resume the installation. It should now finish and start the Hansoft LDAP Integration service. When the service has started you will receive an e-mail notification that it is running, provided you correctly configured the e-mail options in the configuration file. Recall that errors are logged in the \Log folder below the installation folder as well.
You can always check whether the Hansoft LDAP Integration is running and connected to the Hansoft server by logging in as "Administrator" and verifying that the Hansoft SDK Account you created is shown as being "Online".
Note that when you change settings in the configuration file you need to restart the "Hansoft Authentication Integration Services" (HPMAuthInt) service for the changes to take effect.
For help constructing LDAP queries you may refer to:
An LDAP browser that supports testing of LDAP queries can be helpful, for example:
When logged in as "Administrator", you can manually enable/disable LDAP on individual Hansoft accounts. You can also override the default binding of a Hansoft resource to an LDAP account, by using
the drop down list in the "LDAP" tab in the users properties dialog box.
You can also specify which login methods are enabled on a per-resource basis. We recommend that you allow users to login with the Hansoft credentials as well as LDAP authentication. This to have a fallback in
case the connection to the LDAP server breaks.