Versions:4.6+ (LDAP), 6.3+ (LDAPS)
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 via LDAP or LDAPS
Setting up QuerySurge LDAP Authentication
- Log into QuerySurge as a QuerySurge Admin user.
- Navigate to the Admin view in QuerySurge, and in the admin tree at the left, click on Configuration > Authentication Settings.
- To start the process, click on the Enable LDAP Authentication checkbox.
- In the LDAP Hostname editbox, enter the LDAP server hostname or IP address.
- In the LDAP Port editbox, enter the LDAP port for your LDAP service.
- 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), select Simple SSL and then select the appropriate security option for your LDAPS configuration from the dropdown.
Note: The Simple SSL (LDAPS) option is available starting with QuerySurge 6.3+.
Note: 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.
- 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:
- Under Authentication Password, enter the password for the Authentication Principal.
- 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:
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).
- 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:
A set of typical values for this configuration looks like:
If your users plan to log in using another LDAP attribute (sAMAccountName, UserPrincipalName, cn, displayName, sn), make sure that the Search for DN using attribute radiobutton is selected. In the drop-down list, select the default attribute describing the type of value that users plan to use for login.
Note: LDAP DN Searches via attribute are only supported for Simple authentication.
A set of typical values for this configuration looks like:
- 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. If enabled, click on the button to test your settings.
- 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.
- 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(S) Authentication
- In the Admin view, at the upper left, click on Users and Agents > Users in the tree.
- Edit every QuerySurge user to provide a valid LDAP user name in QuerySurge.
For users who do not use the default 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 each user. Click on the Save button to save your changes.
An example of a user that uses a non-default Base DN looks like:
- 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 Admin view by a QuerySurge 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:
If your LDAP service is available
- If your LDAP service is available, log into QuerySurge as a QuerySurge Admin, navigate to the Admin view, click on Configuration > Authentication Settings, and uncheck the Enable LDAP Authentication checkbox.
- Click on the Save button to disable LDAP Authentication.
If your LDAP service is not available
- If you are not logged in, and LDAP Authentication is enabled, you can still disable LDAP. Navigate to your QuerySurge admin URL:
Note: This is not your regular login URL – "/admin.jsp" is appended to the end of your regular URL. If you specified a port other than port "80" when installing the QuerySurge Application Server, then the URL is: http://<servername>:<port>/QuerySurge/admin.jsp.
- Login to the QuerySurge admin app using a QuerySurge Admin login account.
Note: Even if your LDAP service is not available, you should be able to login using your most recent LDAP 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.
- In the admin tree at the left, click on Authentication Settings. Uncheck Enable LDAP Authentication. Click on the Save button at the lower right to save the new settings. All users should now be able to login with their most recent LDAP passwords. (If a user never logged in with LDAP, you will need to set a password manually.)
Notes on Simple SSL (LDAPS) Authentication
- The Simple SSL option is available starting with QuerySurge 6.3+ only.
- 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.
- Simple SSL for QuerySurge is implemented with SSL/TLS for Simple authentication only; there is no option for "Anonymous SSL".
- Simple SSL uses the default Java TrustManager on your QuerySurge server to validate your certificate chains.