LDAP Search

Valve for searching LDAP v3 directories

The LDAPSearch valve searches an LDAP v3 directory and adds matching entries to the current item set.

Prerequisites

Before using this valve the LdapClient module must be configured and deployed.

Configuration

Common LDAP valve configuration can be found here.

Properties
Example

Name	Description	Default value
`base_dn`	Search base DN or list of base DNs. Each base DN is searched separately, and matching entries are merged with duplicate DNs removed. *
`scope`	Search scope.	`"SUB"`
`filter`	Search filter.
`attributes`	Specification of attributes to include in search response. `("*" = all attributes)`	`"*"`
`filter_allow_wildcard`	Allow filters with wildcard (*)	`false`
`filter_escape`	If special characters in the filter should be escaped.	`true`
`max_results`	Maximum number of LDAP entries returned by the valve. The value must be greater than zero.	`1000`
`expected_item_count`	The valve will fail if this value is set (integer) and the result count differs from this value.
`merge_with_current_item`	Merge the search result to current item.	`false`

// Example with one base DN
{
  "name" : "LDAPSearch",
  "config" : {
    "destination" : "default",
    "base_dn" : "dc=example,dc=com",
    "scope" : "SUB",
    "attributes" : [ {
      "name" : "uid",
      "multivalue" : false
    }, {
      "name" : "cn",
      "multivalue" : false
    }, {
      "name" : "mail",
      "multivalue" : true
    } ],
    "max_results" : 100,
    "expected_item_count" : 1
  }
}
// Example with multiple base DNs
{
  "name" : "LDAPSearch",
  "config" : {
    "destination" : "default",
    "base_dn" : [
      "dc=example,dc=com",
      "dc=local,dc=com"
    ],
    "scope" : "SUB",
    "attributes" : [ {
      "name" : "uid",
      "multivalue" : false
    }, {
      "name" : "cn",
      "multivalue" : false
    }, {
      "name" : "mail",
      "multivalue" : true
    } ],
    "expected_item_count" : 1
  }
}

Result limit

max_results limits the number of LDAP entries returned by the valve. The default is 1000, including for existing configurations where the property is omitted. When multiple base_dn values are configured, the limit applies to the combined, deduplicated result.

expected_item_count remains a separate validation setting. It checks the number of entries in the limited, deduplicated result and does not change the LDAP search limit.

Multiple Base DNs

base_dn can be configured as either a single string or a list of strings. When multiple values are provided, LDAPSearch performs one search per base DN during the same valve execution and merges all matches into the result.

Entries are deduplicated by LDAP distinguished name (DN). This means that if the same LDAP object is found under more than one search base, it is only added once.

Example configuration:

{
  "destination": "default",
  "base_dn": [
    "ou=Stockholm,dc=example,dc=com",
    "ou=Copenhagen,dc=example,dc=com"
  ],
  "scope": "SUB",
  "filter": "uid=${request.username}",
  "attributes": ["uid", "cn", "mail"]
}

If the searches return two different users, the resulting items may look like this:

[
  {
    "dn": "uid=anna,ou=Stockholm,dc=example,dc=com",
    "uid": "anna",
    "cn": "Anna Andersson",
    "mail": "[email protected]"
  },
  {
    "dn": "uid=erik,ou=Copenhagen,dc=example,dc=com",
    "uid": "erik",
    "cn": "Erik Eriksson",
    "mail": "[email protected]"
  }
]

If both searches return the same user, only one item is kept:

[
  {
    "dn": "uid=anna,ou=Stockholm,dc=example,dc=com",
    "uid": "anna",
    "cn": "Anna Andersson",
    "mail": "[email protected]"
  }
]

In practice, multiple base_dn values let you search across several directory branches in a single LDAPSearch valve while still producing a deduplicated result set.

Search scopes

The following search scopes are supported:

BASE
SUB
SUBORDINATE_SUBTREE
ONE

Filter

{
    "filter": "uid=*"
}

Attributes specification

The attributes specification is used for defining the entry attributes to include in the search response. If not specified; all non-operational attributes will returned.

The specification can be a comma separated list or an array of attribute names:

"uid,cn,mail,userCertificate;binary"

["uid","cn","mail","userCertificate;binary"]

To enable control of multi value and single value attributes the specification must be an array of attribute spec objects:

{
    "attributes": [
        {
            "name": "uid",
            "multivalue": false
        },
        {
            "name": "cn",
            "multivalue": false
        },
        {
            "name": "mail",
            "multivalue": true
        },
        {
            "name": "jpegPhoto",
            "multivalue": false,
            "binary": true
        }
    ]
}

For correct treatment of binary attributes, they must be tagged as binary either by using the binary attribute option "attribute;binary" or by setting "binary": true in the attribute spec.