Using LDAP Authentication - EcoSys - Administration & Configuration - Hexagon

EcoSys supports three methods for authenticating application users –

1. native, where passwords are stored in the EcoSys "ESFM" database

2. LDAP, where passwords are validated via an external LDAP server

3. custom, where users are authenticated by an external authentication system

The authentication mode for users in EcoSys is configured on a per-user basis, so some users may use the native mode, another subset may use LDAP, and yet others might use custom. Only authentication is supported currently, not any authorization (security groups) or user data synchronization. Currently only Microsoft’s Active Directory LDAP server is supported.

Follow these steps to configure EcoSys to authenticate via LDAP:

Configuring LDAP Settings

1. Log on to EcoSys as an admin super user, and navigate to System Administration > Application Settings > LDAP Settings.

2. Enter the values in the top part of the screen to match your local LDAP server’s settings. You can follow the examples on the screen. Typical settings look like this:

   providerurl = ldap://server.mydomain.com:389
   servertype = ActiveDirectory
   domain = mydomain.com
   context = dc=mydomain,dc=com
   search = dc=mydomain,dc=com
   pattern = (&(objectClass=user)(sAMAccountName=%s))
   usessl = N

3. Click Save to save the settings.

4. Test the settings by entering a valid username and password in the lower section of the screen, and click "Test Authentication". If the settings and credentials are correct, you should see a success message. If not, note the error message and troubleshoot the connection accordingly.

Configuring LDAP to Use SSL (Optional)

If you prefer that the EcoSys server communicate with your LDAP server via SSL, follow the steps below to configure SSL communication. Note that without SSL, the user’s credentials pass over the network between the servers in cleartext, and could be captured by anyone with access to that network.

In order to use SSL, you must first configure your LDAP server to support SSL.

After the certificates have been configured on the LDAP server, you need to import them into the Java keystore on your Java application server where EcoSys is installed. Follow the steps below to import the keys.

1. On your LDAP server, locate the SSL certificate and copy it to the Java application server. Typically this resides in C:\ and is called something like myserver-domain.cer.

2. On your Java application server, locate the Java keystore. Typically this resides under the directory where your JDK is installed, and resides in a subfolder/file called /lib/security/cacerts.

3. On your Java application server, using a command prompt, import the SSL certificate into the Java keystore (as all one line). If you are using a Unix or Linux server, adjust the command accordingly.

   keytool.bat -import -alias MyServer -keystore cacerts -storepass changeit -file myserver-domain.cer

   The default keystore password for Java is "changeit". If you wish to use an alternate keystore location or password, you’ll need to add the following options to the command:

   -Djavax.net.ssl.trustStore={JRE Location}/lib/security/cacerts
   -Djavax.net.ssl.keyStore={JRE Location}/lib/security/keystore
   -Djavax.net.ssl.keyStorePassword=your_new_password

4. If you have used a non-default keystore location or password, you will need to add those parameters above to your Java application server’s startup command, as well. Refer to the documentation on configuring your specific Java application server for how to configure these runtime parameters. If, instead, you use the default values, Java should find the keystore automatically.

5. Next you should adjust the settings in EcoSys: System Administration > Application Settings > LDAP Settings. Change the "Provider URL" to use port :636 instead of :389 and protocol "ldaps://" instead of "ldap://". Also change the "Use SSL" value to be "Y". Save the settings, and test authentication with a sample user.

Configuring Users to Authenticate Via LDAP

1. In EcoSys, navigate to System Administration > Users and Security.

2. Create a user that you wish to use LDAP authentication.

   The User Name field must match exactly the account name in your LDAP server.

3. Set the user’s Authentication Mode to be "LDAP" instead of "Native". This means the native password field is not used for this user.

4. Subsequent logons for this user will use the LDAP server settings to authenticate this user’s password against your LDAP server. If the LDAP user is expired, disabled, or if the LDAP server is not available, the user’s logon will be rejected.

Troubleshooting LDAP

• When a user configured for LDAP attempts to log on to EcoSys, their logon will be rejected if they are not able to authenticate to LDAP for any reason, including: LDAP account expired, LDAP password expired, or invalid LDAP password.

• If the LDAP server is not available when an LDAP user attempts to log on, the user will see a special error message indicating that there may be a problem with communication to the LDAP server.

• To troubleshoot LDAP connections and settings, use the System Administration > Application Settings > LDAP Settings page and the test section and the bottom of the screen. Detailed error messages are displayed on that screen as well as in the application log file.