LDAP Search

Valve for searching LDAP v3 directories

Introduction

Prerequisites

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

Configuration

Valve name: LDAPSearch

Common LDAP valve configuration can be found here.

Properties

Name	Description	Default value	Mandatory	Expanded
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
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

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
        }
    ]
}

All attributes are treated as single values (string) if the result is only 1 value, unless the attribute is configured as multi value (array) specifically.

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.

Binary attributes are encoded in base 64. To use them in another representation they must explicitly be converted.