The Query LDAP assertion reads attributes from LDAP entries and stores them in context variables.
Configure the properties as follows:
|LDAP Connector||Select the LDAP connector to use from the drop-down list. This LDAP identity provider must already be configured in the Gateway. For more information, see Creating an LDAP or Simple LDAP Identity Provider.|
|Select the scope of the LDAP query from the drop-down list:
|Enter DN||If the search scope is by Base DN, enter the user DN in this text box. You may reference context variables.|
|LDAP Search Filter||
Specify a search string that is used to select the LDAP entry to query; for example: (cn=jsmith) or (mail=jane). You may use a context variable.
When the request is processed, the Query LDAP assertion connects to the specified LDAP connector and selects a node based on the search filter. The selected node is then used to extract the LDAP attributes; the values from those attributes are then assigned to the specified context variables based on the table below.
Note: If the search filter matches no LDAP nodes, then the context variables shown in the table are not created.
When an LDAP "object" is returned to the Gateway, it has a set of attributes such as:
Technically, the "dn" of an object is not an attribute of the object itself; rather, it represents its location (name) within the LDAP database. However, the "dn" is treated like other attributes by the Gateway.
|Protect against LDAP injection||
Select this check box to protect against an LDAP injection attack (for example, attempts to substitute a context variable in place of a static value).
When the Protect against LDAP injection check box is selected, any substituted variables are escaped in an LDAP search filter, as per RFC 2254 (section "4. String Search Filter Definition"). The following are some examples
myVar = user* // variable
Displays the Attribute Variable Mapping dialog to create a new pairing:
For more information on using multivalued variables, including delimiter characters and concatenation options, see Multivalued Context Variables.
|[Edit]||Displays the Attribute Variable Mapping dialog to modify an existing pairing.|
|[Remove]||Removes the selected pairing from the table.|
|Include empty attributes in multi-valued results||Select this check box to force the assertion to create an empty string when the user object does not have a value. This ensures a consistent index length for all of the LDAP attributes, even when some attributes do not exist for the object.
Example: When querying for objectClass=user and mail is an LDAP attribute being mapped. Users without a mail address causes a missing entry in the multivalued context variable. Consider:
This results in cn (contains three users), but mail (contains two mail entries). The inconsistent list length makes it more difficult to retrieve user data. You will need an additional query to handle the mail attribute. Selecting the "Include empty..." option adds an empty string for user2, resulting in mail balancing with cn.
Clear this check box to not add an empty string for user objects with no value. This may result in LDAP attributes with varying index length. This is the default and it replicates the behavior of the assertion prior to version 9.2.
|Allow multiple search results||
Select this check box to allow multiple search results for the LDAP query. When this option is used, the resulting context variables are always multivalued.
Clear this check box to not allow multiple search results.
Note: The "Allow multiple search results" option is disabled if the search scope is "Base DN".
If allowing multiple search results, enter the maximum number of results permitted. The default "0" (zero) indicates no limit.
Tip: The setting [Fail assertion if search yields too many results] lets you control what happens when the maximum is exceeded.
|Cache LDAP attribute values||
Select this check box to cache the LDAP search results. When a search is performed, the Gateway uses cached results first. This can improve performance in environments where the data on the LDAP server changes infrequently.
Clear this check box to not cache any LDAP search results. The LDAP directory is queried for every search.
If LDAP search results are being cached, specify the maximum number of LDAP search results to be cached. A size of '0' (zero) means an unlimited cache size.
|Cache maximum age||If LDAP search results are being cached, specify how long to cache an item before the information is discarded.|
|Fail assertion if search yields no results||
Select this check box to have the assertion fail if no search results are returned.
Clear this check box if the assertion should always succeed, regardless of the search outcome.
|Fail assertion if search yields too many results||
Select this check box to fail the assertion if the number of search results exceeds the specified maximum.
Clear this check box to never fail the assertion regardless of the number of search results.
Note: The "Fail assertion if search yields too many results" option is disabled if the search scope is "Base DN".