Configure LDAP and LDAPS for Authentication to TeleScope

Overview

TeleScope can use LDAP or LDAPS(Secure LDAP) to provide authentication functions for its users through the Authentication Broker. The broker logs messages to the ab.log file. The article has sections on LDAP and LDAPS with an additional section on identifying the base authentication context.

Solution

Pre-requisites

To set up or re-configure LDAP to work with Telescope, you need:

An LDAP Browser Tool. Download this free browser tool. (You will need this tool to identify base authentication. The steps shown in the following sections are based on version 4.5 of this tool.)
Acquire your LDAP Service Account Credentials, including username/password/base DN.
(To find the base DN on your own, see "Identify Base Authentication Using the LDAP
Browser Tool" section on this page).
LDAP server name and port.
A normal user account in the Active Directory forest that you can test with.
A Telescope LDAP Plugin License.

If you also need to set up or re-configure LDAP over SSL(LDAPS), ensure you have the following with you before you start:

LDAP Over SSL server name and port.
Root Certificate, Internal Certificate (if applicable), LDAP certificate in X.509 format (.cer should be sufficient).

Identify Base Authentication Using the LDAP Browser Tool

Launch the LDAP Browser tool.
Click the New button to create a new connection.
Give it any name, and then click Next.
Set the Host Name and Port.
(Leave the Base DN alone. The LDAP URL at the bottom of the panel will self-populate.)
Click the Next Button.
Set the radio button to Other Credentials and the Mechanism to Simple.
Type in the user name and password of the service account.
Click Finish to make the connection.
If this authentication fails at this point, then so will the Authentication Broker, so make sure you can connect before continuing with these instructions.
Find your user account by typing it into the Find What box, then click Find. If the service account is set up correctly, your user account will appear. This step confirms that the Authentication Broker will find you when you attempt to log in.
Double-click on your user name and scroll through the available options.
The Name column will help you set up the mappings later on. Use these entries to take note of mappings for the department, phone number, email, first name, last name, and other values stored about users. The values in the name field are case-sensitive, so take note of the case as well.
You will also need to determine if your environment is using sAMAccountName or UID to look up usernames. This method will determine how you set up your base authentication context within the TSAdmin LDAP Plugin. In this example, we are using sAMAccountName.
Within your profile, scroll down to locate your distinguishedName entry. This will also be critical in
assisting you with building out the Base Authentication Context.
With the information we have, we can construct the base authentication context for the LDAP Plugin as follows sAMAccountName=<<>>,DC=northplains,DC=com (Explanation: We have determined it is a sAMAccountName. <<>> is a replacement parameter to pass the name typed by the user in Telescope The DC entries were derived from the distinguishedName entry. OU entries may also be required to subdivide users into
various groups.)

Configure the LDAP Plugin

The following steps can be used to either set up a new TeleScope installation with LDAP authentication or to update an existing setup in case any parameter has changed. Follow the steps and perform any addition or update of configuration you may need to.

Log in to TSAdmin as a system administrator. (Ensure Administer is set to System.)
Click the Authentication Broker link in the left navigation panel.
In the Telescope Connections section, click Add.
Referencing the screenshot below, set the following:
- Set TeleScope Connection Name to the connection name used by Telescope to connect to the database. Locate it by clicking the connections link in the left navigation panel of the TSAdmin screen.
- If you need access to the Telescope database of users, set Failover Selection to "Direct Authentication Plug-In"; otherwise set it to disabled.
- LDAP Parameter Directory (at the bottom of the window) can be either C:\Temp or \\server\path.
In the same window shown above, click “Add” in the "Primary LDAP Server" section. In the panel that appears, provide values as illustrated in the screenshot below:
- Fill in the Server Name field.
  In Single Domain instances, set the server name to the actual LDAP server name.
  In Multiple Domain instances, set each domain server name to the domain name itself. This setting can then be used as the identifier "hint" on login for when you want Telescope to find your user in a particular domain.
  Set up each domain independently of the others (even if their servers are the same).
  Once the domains are set up, your users will need to use the domain qualifier to log in (for example, NPS\username). The Authentication Broker will use "NPS" against the "server name" field (also called NPS in this scenario) and then look up the user on the domain forest defined by the configuration contained within it.
- To set the Primary LDAP Address, click Add. Use the following format: ldap://servername:port
  (for example, ldap://npsldap.northplains.com:389)
- Primary User Name is the read-only service account, which can access and enumerate the entire
  domain structure. This name is created and used within your organization. The primary username may need to be your FQN or prequalified with a domain (for example, NPS\username or username@nps). You can validate your settings in an LDAP Browser tool, to help speed up the process.
- Primary User Password is the password for the primary user account described in the previous step.
- Base Authentication Context will sometimes be given to you as follows:
  uid=<<>>,OU=Users,DC=Northplains,DC=Com
  sAMAccountName=<<>>,OU=Users,DC=Northplains,DC=com
  You will need to use the LDAP Browser tool to validate the Base DN to ensure you are using the correct user name lookup field. The field can be either UID or sAMAccountName, and you will need to check which one is used. While you are validating, ensure that you are using the correct DN to begin with.
  The <<>> section of the base context is considered a replacement parameter for the passed-in user name of the person logging in.
- Leave Authentication as "Simple". If you require a different setting, contact the North Plains Systems Professional Services Group.
Click OK to commit your changes.
If you get no error messages, proceed to click on all of the OK buttons.
Be sure to click the Save option on the main page of TSAdmin to commit your settings to the broker. If all settings are correct, you will see a "save successful" message.

Set up LDAP Plugin for LDAP over SSL

Follow the steps in "Set up LDAP to Work with Telescope" to first get LDAP authentication working, then proceed with the next steps to add in LDAPS after you know everything else functions.
Log in to TSAdmin as a system administrator. (Ensure Administer is set to System.)
Click the Authentication Broker link in the left navigation panel.
In the Telescope Connections section, click the connection you set up already (it opens in a new window).
Click the Primary LDAP Server link (it opens in a new window).
Click on the "Primary LDAP Address" link.
Use your LDAP Over SSL server name and port to modify the settings as follows: ldaps://servername:port
For example, ldaps://NPSLDAP:636 (Note that both the "S" and the secure port are required
Click OK for all of the open windows. Click Save in the main window to commit to the broker.
Install the certificates into the Java (JRE & SDK) Certificate Store.
Having the certificates in the Operating System Certificate Store is not enough. The certificates MUST reside in the Java certificate store for this to work. Read the points below on using the Java keytool to find out more on how to do this.

Using the Java keytool
- The "-Alias" name is arbitrary and must be unique for each of the certificates.
- Add the key to both the JRE and JDK sections.
- If there are spaces in your string, wrap them in double-quotes.
- The Java keytool only works with .cer X.509 files. Other formats will not import as expected as of the publication date of this document.
- The default password for the java keystore is "changeit". You will be asked for this password during the key import. You will be asked to enter it twice, for each time a key is inserted into the keystore.
With the above points in mind, continue with the next steps to add in the certificates you gathered.
Open a command prompt as an administrator.

Enter the following commands (modify the paths to the certificate as appropriate).
For the Internal Certificate:

keytool -import -alias InternalCert -file "c:\Internal CA.cer" -keystore "C:\Program Files(x86)\Java\jdk1.6.0_37\jre\lib\security\cacerts"

keytool -import -alias InternalCert -file "c:\Internal CA.cer" -keystore "C:\Program Files(x86)\Java\jre6\lib\security\cacerts"

For the Root Certificate:

keytool -import -alias RootCert -file "c:\Root CA.cer" -keystore "C:\Program Files(x86)\Java\jre6\lib\security\cacerts"

keytool -import -alias RootCert -file "c:\Root CA.cer" -keystore "C:\Program Files(x86)\Java\jdk1.6.0_37\jre\lib\security\cacerts"

For the LDAP Server Handshake Certificate:

keytool -import -alias serverCert -file c:\SERVERNAME.cer -keystore "C:\Program Files(x86)\Java\jdk1.6.0_37\jre\lib\security\cacerts"

keytool -import -alias serverCert -file c:\SERVERNAME.cer -keystore "C:\Program Files(x86)\Java\jre6\lib\security\cacerts"

Testing

For LDAP

Attempt to log into "Telescope.Web" with your domain user and password and you should be able to authenticate successfully.

For LDAP over SSL

Attempt to log in to Telescope. If the login is successful, you are logging in with LDAPS. (The authentication may be noticeably slower due to the extra handshake measures performed by the certificate.)