Query LDAP Assertion

The Query LDAP assertion reads attributes from LDAP entries and stores them in context variables.
gateway92
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.
    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.
    Select Scope
    Select the scope of the LDAP query from the drop-down list:
    • Whole Subtree: 
      This option searches the Base Object and all its sub groups. For example, an LDAP configuration has this search base:
      ou=My Developers,dc=seattle,dc=local
      Searching the whole subtree queries "My Developers" and all its child directories. This is the default and it reproduces the behavior of this assertion prior to version 9.2.
    • Single Level:
       This option searches only the parent Base Object. Using the example above, the search is restricted to "My Developers"; all child directories are ignored.
    • Base DN:
       This option searches only a single user DN and provides the quickest searches.
    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.
    If the search filter matches no LDAP nodes, then the context variables shown in the table are not 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}
      returns "bronze, silver, and gold". Calling
      ${medal[0]}
      returns "bronze"; calling
      ${medal[2]}
      returns "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 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:
    W
    hen 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:
    • user1
      has 1 email address
    • user2
      has no email
    • user3
      has 2 email addresses
    This results in
    cn[3]
    (contains three users), but
    mail[2]
    (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[3] balancing with cn[3].
    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.
    The "Allow multiple search results" option is disabled if the search scope is "Base DN".
    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 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.
    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.
    The "Fail assertion if search yields too many results" option is disabled if the search scope is "Base DN".
  3. Click [
    OK
    ]
     
    when done.