Query LDAP Assertion

The Query LDAP assertion reads attributes from LDAP entries and stores them in context variables.
gateway90
The
Query LDAP
assertion reads attributes from LDAP entries and stores them in context variables.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the
    LDAP Query Properties
    automatically appear; when modifying the assertion, right-click
    Query LDAP
    in the policy window and select
    LDAP Query Properties
    or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
    Setting
    Description
    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.
    LDAP Search Filter
    Specify a search string that will be 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.
    If the search filter matches no LDAP nodes, then the context variables specified in the table below will not be created.
    Technical Details
    When an LDAP "object" is returned to the Gateway, it has a set of attributes such as:
    cn=jsmith ph=6045551234 ...
    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).
    Technical Details
    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 cn=${myVar} // filter cn=user\2a // filter after variable substitution with escaping enabled
    [Add]
    Displays the Attribute Variable Mapping dialog to create a new pairing:
    • LDAP Attribute Name:
      Enter the name of the LDAP attribute to be stored as a context variable.
    • Context Variable Name:
      Enter the name of a new context variable to hold the attribute value. Observe the naming rules for your new variables.
    • If multivalued:
      If the attribute contains more than one value, indicate how the values should be handled:
    • Use first value:
      Select this option to use only the first value, regardless of how many values are present.
    • Join with commas:
      Select this option to concatenate all the values into one string, separated by commas. For example, if the context variable "medal" has three values
      bronze, silver, gold
      , choosing this option will define "medal" as "bronze, silver, gold".
      Using this option, the individual elements in the value are not separately addressable as with the "Set multivalued context variable" option
    • Set multivalued context variable:
      Select this option to place the values in an array where each element is addressable. Using the "medal" example from above, calling
      ${medal}
      will return "bronze, silver, and gold". Calling
      ${medal[0]}
      will return "bronze"; calling
      ${medal[2]}
      will return "gold".
    • Fail:
      Select this option to fail the assertion if the attribute contains more than one value.
    For more information on using multivalued variables, including delimiter characters and concatenation options, see Working with Multivalued Context Variables.
    [Edit]
    Displays the Attribute Variable Mapping dialog to modify an existing pairing.
    [Remove]
    Removes the selected pairing from the table.
    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 will always be multivalued.
    Clear this check box to not allow multiple search results.
    Maximum results
    If allowing multiple search results, enter the maximum number of results permitted. The default "
    0
    " (zero) indicates no limit.
    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 will use 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.
    Cache size
    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.
  4. Click [
    OK
    ]
     
    when done.