QuerySurge Authentication with LDAP and LDAPS (Versions: 12.0+)

Versions: 8.0+

QuerySurge and LDAP

When you deploy QuerySurge, by default QuerySurge authentication is handled locally. Many organizations use LDAP for authentication, however, so you can switch QuerySurge over to authenticate from your LDAP server. The procedure for this setup is described below.

Note: You will most likely need to work with an LDAP admin or other knowledgeable resource to set up the proper LDAP settings.

Configuring QuerySurge Authentication with LDAP

Setting up QuerySurge LDAP Authentication

1. Open a browser and navigate to your QuerySurge Admin URL:
   http://<server>/QuerySurge/admin
   
   If you specified a port other than “80” when installing the QuerySurge Application Server, then the URL is: http://<server>:<port>/QuerySurge/admin 
   
   Note: This is NOT your regular QuerySurge login URL; please enter the Admin URL as shown here.
   
2. Log in to QuerySurge Global Administration Portal view as a QuerySurge Global Admin user.
   
3. In the Administration Tree (at the left), click Authentication Settings. 
   
   
4. To start the process, click on the Enable LDAP Authentication checkbox.
5. In the LDAP Hostname input box, enter the LDAP server hostname or IP address.
   Note: Enter the hostname or IP address alone with no prefix of any sort and without the port (which is entered in the next step).
6. In the LDAP Port input box, enter the LDAP port for your LDAP service.
7. In the LDAP Authentication Type section, choose the type of LDAP authentication your LDAP service uses:
   
   • If your LDAP service requires no prior LDAP authentication before responding to a request for client application authentication, then you are using Anonymous authentication.
   • If a client application must authenticate with the LDAP server prior to requesting client authentication, then you should select Simple authentication.
   • If your organization uses Secure LDAP (LDAPS), see the section below "Configuring QuerySurge Authentication with LDAPS".
8. If you selected either form of Simple authentication, enter the DN (Distinguished Name) for your Authentication Principal under Authentication Principal DN. Most likely, you'll need to obtain this from an admin on your LDAP system. Sample DNs include:
   CN=myuser,CN=users,DC=mydomain,DC=local
   CN=myuser,OU=managers,OU=dev,DC=mydomain,DC=local
9. Under Authentication Password, enter the password for the Authentication Principal.
10. Under Base DN, enter the "base" or default Distinguished Name for your users. Use the key-value pairs that work for the largest number of your users. Sample Base DNs include:
    CN=users,DC=mydomain,DC=local
    OU=managers,OU=dev,DC=mydomain,DC=local
    Note: The Base DN is used only to establish a default DN for users, in order to make User set up a bit simpler. If the Base DN is not applicable to your implementation because users are spread out over multiple LDAP containers, choose a common search path for the Base DN. You can specify searches individually at the user level (see the next section).
11. For the User Lookup Method: if your users plan to log in using their actual LDAP names make sure that the DN Username Attribute radiobutton is selected, and enter the attribute for your users LDAP user names. Use the key that works for the largest number of your users. Sample username attributes include: CN or UID
    
    A set of typical values for this configuration looks like:
    
    If your users plan to log in using another LDAP attribute (e.g. sAMAccountName, userPrincipalName, cn, displayName, sn), make sure that the Search for DN using attribute radio button is selected. In the drop-down list, select the default attribute describing the type of value that users plan to use for login, or type in an attribute useful for your LDAP search.
    
    Note: LDAP DN Searches via attribute are only supported for Simple/Simple SSL authentication.
    
    Note: If you are using the Search for DN using attribute option, if the attribute you want to use is not in the drop-down list, you can type it in.
    
    A set of typical values for this configuration, using sAMAccountName as the search attribute, looks like:
    
12. If you have selected either form of Simple authentication, the Test LDAP Settings button is enabled. This tests the authentication step to the LDAP server without testing any user authentication. If you selected Anonymous authentication, this button is disabled, as there is no need to test this. If enabled, click on the button to test your settings.
13. Click on the Test Admin Login button. This button lets you select a QuerySurge Admin user to test for authentication. Note that every QuerySurge Admin, like every QuerySurge user, requires a QuerySurge user name that is a valid LDAP user name once you have set up LDAP Authentication.
    
    
    • Choose a QuerySurge Admin user name from the drop down.
    • If the user name is not an LDAP name, click the Edit User  button and change the user name to an LDAP user Name.
    • Enter the LDAP password.
    • Click the Test button.
    If your QuerySurge Admin user successfully authenticates with the LDAP server, you'll be notified via a popup. Likewise, if authentication fails, you'll receive a popup notification. The purpose of this step is to ensure that you have at least one QuerySurge Admin user that can authenticate via LDAP. You may choose to test or edit other QuerySurge Admin users, as well.
14. Once you have ensured that you have at least one QuerySurge Admin user that can authenticate via LDAP by conducting a successful test, the Save button should be enabled. Click the Save button to save your LDAP settings.

Configuring QuerySurge Users for LDAP Authentication

1. In the Global Admin view, at the upper left, click on Users in the tree.
2. Select a user and click the Edit button.
3. Click the Security tab.
4. Provide a valid LDAP user name for the user.
5. For a user that cannot be looked up in the directory with the Base DN or User Lookup Method that are set in Steps 9 - 10 above, click on the Override Default LDAP Settings checkbox, and set the correct Base DN and Username Attribute for the user.
   
   An example of a user that uses a non-default Base DN looks like:
   
6. Click on the Save button to save your changes.
7. Repeat for all remaining QuerySurge users.
8. QuerySurge is now set up to authenticate via LDAP.
   
   Note: When LDAP authentication is enabled in QuerySurge, every QuerySurge user name needs to be an LDAP user name. Existing QuerySurge user names may have to be changed to the corresponding LDAP user name. Any user name changes are performed in QuerySurge's Global Administration view by a QuerySurge Global Admin user.
   
   Note: QuerySurge will store the current LDAP password for each user (as a hash), but will not use it to authenticate while LDAP Authentication is enabled. QuerySurge does this in case you need to disable LDAP Authentication; each user will then be able to authenticate locally using the most recent valid LDAP password.

Disabling LDAP Authentication

You may need to disable LDAP authentication under some circumstances. For example, if your LDAP server goes down, and you still want to access QuerySurge while the problem is being resolved, you'll need to disable LDAP Authentication. If you disable LDAP Authentication, QuerySurge should have cached your most recent LDAP passwords for local authentication, so you should be able to authenticate with QuerySurge. The steps for disabling LDAP authentication follow:

1. Navigate to your QuerySurge Global Administration URL:
   http://<servername>/QuerySurge/admin
2. Login to the QuerySurge Global Administration app using a QuerySurge Global Admin login account.
   
   Note: Even if your LDAP service is not available, you should be able to login using your most recent valid LDAP username and password. This may take a while, since QuerySurge will try to authenticate your login via LDAP first (because LDAP is still enabled). If LDAP authentication fails, QuerySurge will try to authenticate locally.
3. In the Global Administration tree at the left, click on Authentication Settings.
4. Uncheck Enable LDAP Authentication.
5. Click on the Save button at the lower right to disable LDAP Authentication. All users should now be able to login with their most recent valid LDAP usernames and passwords. (If a user never logged in with LDAP, you will need to set a password manually.)

Configuring QuerySurge Authentication via Secure LDAP (LDAPS)

Some organizations configure their LDAP server(s) to communication via SSL/TLS as an additional security measure. This configuration typically involves importing a certificate for your LDAP server into QuerySurge's truststore, and then setting the LDAP configuration in QuerySurge to use Simple authentication with SSL. 

Before reviewing these procedures, note the following key points about LDAPS support:

1. The Simple SSL option is available starting with QuerySurge 6.3+ only.
2. Simple SSL security options include SSLv3, and TLS levels TLSv1 through TLSv1.2. You can also select the generic TLS value, which lets QuerySurge negotiate the level. The SSLv3 option is included for backwards compatibility only and is not recommended. Check with your LDAP or network administrator to find the correct setting.
3. Simple SSL for QuerySurge is implemented with SSL/TLS for Simple authentication only; there is no option for "Anonymous SSL".
4. Simple SSL uses the default Java TrustManager on your QuerySurge server to validate your certificate chains.

Configuring QuerySurge Authentication with LDAPS

LDAPS usually requires importing a certificate for your LDAP server into QuerySurge's truststore. You'll need to obtain the cert from an LDAP administrator or some other similar resource.

Steps for importing your LDAP server cert follow:

1. Import your CERT to the QuerySurge App Server Truststore

1. Shut down all QuerySurge processes. See this article for details.
2. Copy your certificate file to /<QuerySurge Install Dir>/QuerySurge/java/lib/security/. Then use the Java keytool to import the file into the default Java truststore (cacerts), using the following command:
   
   keytool -import -alias <your alias> -file <your certificate file> -keystore cacerts
   
   Note: The 'alias' is an alias to this entry in the truststore. The 'file' is the cert file that has been obtained for the QuerySurge App Server.
   
   Note: It is important to know the alias of the certificate that was generated for your QuerySurge server as you will want to use the same alias when importing it into the cacerts truststore.
   
   Note: If prompted for a password while importing the cert, the default password for the cacerts truststore is: "changeit". If you want to change it, you can find instructions here.
   
   EXAMPLE 1.1 (Windows 64-Bit Install)
   

   "C:\Program Files\QuerySurge\java\bin\keytool" -import -trustcacerts -file "C:\path\to\your\cert\mycert.cer" -alias YOUR_LDAPS_ALIAS -keystore "C:\Program Files\QuerySurge\java\lib\security\cacerts"

   Note: You may need to use the fully qualified path to access the keytool or truststore based on how and where you are calling this command. In the example above, we navigate to QuerySurge's truststore directory and call the keytool using the fully qualified path name. This applies to the keytool commands in the later steps as well.
   
   Note: If you encounter an error message like "Input not an X.509 certificate" you may have to have the certificate regenerated in a more Java-friendly encoding like ".der".
   
   Note: If your certificate requires a password, upon import you may encounter an error message like "Cannot recover key".  This means that the password for the certificate is different than the password of your cacerts truststore.  You will have to update the password for the cacerts truststore to the same password as the certificate.  Again, you can find instructions on how to change truststore password here. 
3. Start the QuerySurge services. See this article for details.

2. Configure QuerySurge Authentication for LDAPS

These steps are largely parallel to steps (7) - (11) above under "Setting up QuerySurge LDAP Authentication":

1. Log into the QuerySurge Global Administration area as a QuerySurge Global Admin user.
2. In the Global Administration tree on the left, click on Authentication Settings.
3. Under LDAP Authentication Type, configure your LDAPS authentication option:
   
   • Select Simple SSL and then select the appropriate security option for your LDAPS configuration from the dropdown. The TLS option lets QuerySurge negotiate the TLS level, and is usually sufficient, as noted above. Check with your LDAP or network administrator for the proper setting.
     
     
4. For the User Lookup Method: if your users plan to log in using their actual LDAP names make sure that the DN Username Attribute radio button is selected, and enter the attribute for your users LDAP user names. Use the key that works for the largest number of your users. Sample username attributes include: CN or UID. See the image above for a typical set of values.
5. Review steps (12) - (17) above under "Setting up QuerySurge LDAP Authentication" to configure the remaining LDAP settings.

Using a Non-default Truststore 

While we strongly recommend using Java's default truststore (<QuerySurge Install Dir>/QuerySurge/java/lib/security/cacerts), there are circumstances where your organization may want to use a different truststore. You can use a non-default truststore containing your LDAP cert by performing the following steps.

Note: Even if you use the default truststore, we strongly recommend changing the password from the default value. When you change the password, set the arguments in step (5) to indicate the nondefault password.

Windows

1. Shut down your QuerySurge instance. See this article for details.
2. Copy your non-default truststore with the LDAPS cert imported to a designated location on your QuerySurge App server. Be sure to note the directory path and file name of the truststore.
3. Find the QuerySurge install directory (the default is: C:\Program Files\QuerySurge). 
4. Under the QuerySurge install directory, navigate to the tomcat/bin directory (default path: C:\Program Files\QuerySurge\tomcat\bin). With administrative rights, launch QuerySurgeTomcatw.exe.
5. Click on the Java tab, and find the Java Options box. At the end of the entries in this box, add the following two lines, with modifications for the specifics of your installation. (The first of these settings specifies the full path to your custom truststore, and the second specifies the password for the truststore.)

   -Djavax.net.ssl.trustStore=C:\path\to\truststore\mynewtrusstore
   -Djavax.net.ssl.trustStorePassword=mytruststorepassword

   Note: Be extremely careful not to modify the existing values in the Java Options box. Modifying these values may cause your QuerySurge instance to fail to run.
6. In the lower right, click the Apply button.
7. In the bottom center, click the OK button.
8. Re-start QuerySurge. See this article for details.

Linux

1. Shut down your QuerySurge instance. See this article for details.
2. Copy your non-default truststore with the LDAPS cert imported to a designated location on your QuerySurge App server. Be sure to note the directory path and file name of the truststore.
3. Find the QuerySurge install directory (the default is: /opt/QuerySurge). 
4. Under the QuerySurge install directory, navigate to the tomcat/scripts directory (default path: /opt/QuerySurge/tomcat/scripts ).
5. Make a copy of the ctl.sh file. Carefully edit the original file in your favorite text editor. Add the following two switches to JAVA_OPTS, separated by a space, with modifications for the specifics of your installation. Be careful to respect the double-quotes. (The first of these settings specifies the full path to your custom truststore, and the second specifies the password for the truststore.)

   -Djavax.net.ssl.trustStore=/opt/path/to/truststore/mynewtrusstore
   -Djavax.net.ssl.trustStorePassword=mytruststorepassword

   Note: Be extremely careful not to modify anything else in the file. Modifying any commands in the file may cause your QuerySurge instance to fail to run.
6. Save the modified file.
7. Re-start QuerySurge. See this article for details.