I am configuring the LDAP options in xMatters and have created a template, but I need to be able to query the LDAP directory for a User's Distinguished Name. Can I do this in xMatters?
xMatters substitutes the login name supplied by the User for the %UID% in the template configured on the LDAP Servers page, and sends this and the password making the login request to the LDAP directory. xMatters then examines the result to determine whether the user has valid credentials.
If you know the format in which Distinguished Names (DN) are stored in your LDAP directory, you can enter the DN format directly in the template field; for example:
If you do not know the format of the DN, or if the xMatters Login ID is not part of the DN, you can configure the ldap.properties file to query the LDAP Directory and bind the correct DN to the User.
Note: bind query search is available on AlarmPoint 3.2.1 patch 11 and higher, and AlarmPoint 4.0 patch 5 and higher; otherwise, the LDAP server must support anonymous access for querying the DN. Searching with bindID and password is not supported.
Create the LDAP configuration file ldap.properties in the /common/ directory.
NOTE: The ldap.properties file should be created on all web servers.
This file includes the following configuration values:
- queryDN: must be set to true (i.e., queryDN=true) for xMatters to query for the DN before authentication.
- base: specifies the DN of the LDAP directory branch from which all searches should begin. At a minimum, this value should be set to the top of your LDAP directory tree.
- filterPrefix: specifies the filter prefix used for searching; it must specify a valid LDAP search filter. Note that the login name is inserted into the template specified in the web user interface, and then appended to the prefix to form the DN query. For more information, see the examples below.
- userSearchFilter: (added in AlarmPoint 4.0 patch 009 and 4.1 patch 001) specifies the entire search filter, which must be a valid LDAP search filter. This parameter replaces the filterPrefix parameter.
This parameter provides greater flexibility in searching because it allows you to put the LDAP Domain Template (from the web user interface) in any location within the search filter. A special substitution token, %TMPL%, indicates where the template should be inserted. For more information about using this parameter, see the article How do I create an LDAP search filter?.
- bindDN: optional DN used in conjunction with the password value to bind to the server when searching for entries (if not provided, an anonymous bind is used).
- password: bind password used in conjunction with bindDN. Since the bind password is probably sensitive data, it should be properly protected using APSecure (for an example of how to use APSecure, click here).
- connectTimeout: maximum time (in milliseconds) to wait when making a connection to the LDAP server. If this time is exceeded, the authentication will fail. (Available in xMatters 5.0 patch 010 and later.)
- soTimeout: maximum time (in milliseconds) when waiting for a response from the LDAP server. If this time is exceeded, the authentication will fail. (Available in xMatters 5.0 patch 010 and later.)
The following examples illustrate how to use the filterPrefix parameter.
For this example, assume that you do not know the format of the DN for each User, but you know that the User's Login ID is part of the DN, and is identified within the LDAP directory as "uid". You also know that all xMatters Users are part of a specific LDAP branch. You could set the template on the LDAP Servers page to pass in only the User's Login Name: %UID%
The ldap.properties file would resemble the following:
queryDN=true base=ou=directory,dc=company,dc=com,o=users,ou=alarmpoint filterPrefix=uid=
For this example, assume that you do not know the format of the DN for each User, nor whether the User's Login ID is part of the DN. You do know that the Login ID is part of the User's email address, which is an attribute you can use to search the LDAP directory. The template on the LDAP Servers page would then resemble the Internet format:
You could then configure the ldap.properties file to query anonymously for the DN based on the email address:
queryDN=true base=ou=directory,dc=company,dc=com filterPrefix=email=
In this example, the LDAP server does not allow anonymous searching. As a result, you must provide a bind DN and password.
You would then configure the ldap.properties file to query for the DN based on the email address:
queryDN=true base=ou=directory,dc=company,dc=com filterPrefix=email= bindDN=cn=bsmith,dc=company,dc=com password= connectTimeout=60000 soTimeout=60000
NOTE: After modifying the ldap.properties file, restart the xMatters web server.
DTN-3291, APO-7090, JDN-1047
Originally created by Don Clark