Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Query LDAP Assertion

Last update December 13, 2016

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.

    Note: 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:


    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

    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".

      Note: 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: 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:
    • 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.

    Note: 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.

    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.

    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.

    Note: The "Fail assertion if search yields too many results" option is disabled if the search scope is "Base DN".

  3. Click [OK] when done.
Was this helpful?

Please log in to post comments.