LDAP Query explained
What is LDAP?
LDAP (Lightweight Directory Access Protocol) is an open protocol used to store and retrieve data from a directory service. Usually, it stores information about the users within an organization in a hierarchical structure.
Here's a sample of an LDAP DIT:
LDAP DIT
We won't go in depth into technical details about LDAP, we just need to keep in mind some general terminologies that are important to understand while configuring an Elements Connect filed plugged to LDAP datasource.
DIT (Directory Information Tree): Is the way we represent the data of our directory service (e.g. the tree shown previously in the screenshot).
DC (Domain Component): It represents the top of the DIT (e.g. dc=planetexpress, dc=com)
OU (Organizational UnitName): Is an object that organize other objects (or an object that groups users) based on their position, country, business unit, etc... (e.g. ou=people, ou=printers, ou=Developers).
CN (Common Name): Is the object name (e.g. in case the object is a user, the CN is a user name. In case the object was a department, CN will be the department name).
DN (Distinguished Name): Is a "string" that identifies an LDAP entry in the the DIT. To write it, we start from the bottom back to the root (e.g. for Amy Wong the DN is "cn=Amy Wong,ou=people,dc=planetexpress, dc=com").
Attribute: This is where the data is stored in the LDAP (e.g. uid (user id), mail, department, employeeType, etc...)
Entry: It's a collection of attributes under an entity to describe it and to provide more details about it (e.g. cn=Amy Wong).
Filter: It is part of the LDAP search query, it will identify (restrict) which part of the DIT we need to search.
What is an LDAP query?
An LDAP query is a command that asks the directory service for some information about users.
For an Elements Connect field plugged on an LDAP datasource, there's no special syntax (related to Connect) that needs to be followed; the LDAP query just needs to be valid.
Here's an example of an Elements Connect field connected to LDAP datasource:
And here's the LDAP query:
ou=people,dc=planetexpress,dc=com?uid,cn?sub?(objectClass=person)The first part "ou=people, dc=planetexpress, dc=com" is the DN and it specifies which part of the DIT the Connect field will query.
When placing a question mark ? that means list of parameters will be mentioned.
This query will return two attributes: uid (at position 0) and cn (at position 1).
The field Key is set to 0 (uid attribute) and the Template is set on 1 (cn attribute).sub is an option which determines the search scope. When specified, the query will retrieve informations (attributes) about entires at all levels below the DN
What is in parentheses (objectClass=person) is the filter and it will help us to add more context to our query to filter the retrieved data and get only entries where objectClass equals to "person".
The LDAP filter has usually the below syntax:
<Attribute><comparison operator><value>Filter Operators
Comparison Operators
Operator | Syntax | Description |
|---|---|---|
= | attribute=abc | Equality |
>= | attribute>=abc | Greater than or equal to |
<= | attribute<=abc | less than or equal to |
~= | attribute~=abc | Approximately equal to |
When we need more than one search condition (more than one filter); filters can combined using the boolean (logical) operators.
Boolean Operators
Operator | Syntax | Description |
|---|---|---|
& | (&(filter1) (filter2)) | AND (all conditions must be met) |
| | (|(filter1) (filter2)) | OR (any conditions can be met) |
! | (!(filter1)) | NOT (the condition must not be met) |
Nested | (|(& (filter1) (filter2))(& (filter3) (filter4))) | (filter1 AND filter2) OR (filter3 AND filter4) |
The boolean operators are always placed in front of the filter.
The search filter must be put in parentheses. If more than one filter are combined with boolean operation, then each filter is put in parentheses, and the whole term has to be in parentheses as well.
Special characters
If we need to search an attribute where the value includes a special character (*,(,),\,...), that character must be escaped by using the below format:
\codeWhere the code is the 2 hexadecimal characters that represent the ASCII character.
Character | ASCII code |
|---|---|
* | \2a |
( | \28 |
) | \29 |
\ | \5c |
/ | \2f |
| | \7c |
= | \3d |
~ | \7e |
NULL | \00 |
Examples
Given the below LDAP structure:
Here are some examples on valid LDAP queries to be used in an Elements Connect field:
Match single attribute |
| All entries where objectClass attribute equals to person |
Match multiple attributes (AND) |
| All entries where objectClass attribute equals to person and department equals to Human |
| All entries where CN attribute values don't start with "a" (or "A") and don't start with "h" (or "H") | |
Match one of multiple attributes (OR) |
| All entries where objectClass attribute equals to person, or department equals to Human, or employeeType equals to Intern |
| All entries where CN attribute starts with "a" ("A") or "h" ("H") | |
Negate an attribute |
| All entries where employeeType attribute is other than Ship's Robot |
Equality |
| All entries where cn attribute equals to "Amy Wong" or "amy wong" |
Wildcards |
| All entries where the email domain for the mail attribute equals to "@domain.com" |
| All entries where their CN attribute contains the letters "on" | |
| All entries where CN attribute includes what the user has typed | |
Attribute is present |
| All entries which have a description |
Attribute is absent |
| All entries where their description attribute is empty |
Proximity |
| All entries where CN attribute equals to $userInput variable (what is exactly typed by the user in the field editor) |
Escape special characters |
| All entries where CN attribute includes "*" (encoded to \2a) |
Case sensitive
Most LDAP attributes are case insensitive, so basically, both queries listed below are valid and will return same values.
ou=people,dc=planetexpress,dc=com?uid,cn?sub?(cn=h*)ou=people,dc=planetexpress,dc=com?uid,cn?sub?(CN=H*)Do you still need support?
For more complicated queries, it's always recommended to check with the LDAP administrator