LDAP users
Queries a generic LDAP directory — OpenLDAP, 389 Directory Server, or anything else speaking LDAP — and creates user assets from the entries it returns.
| Type name | ldap_users |
| Creates | Users |
| Runs on | A sensor with network reach to the LDAP server |
| Presence flag | ldap_exits |
| Field prefix | ldap_ |
What it contributes
The attributes it maps are the POSIX and inetOrgPerson set:
- Identity — distinguished name,
cn,uid, display name, given name, surname - Contact — mail
- POSIX account — uidNumber, gidNumber, home directory, login shell
- Classification — object classes, description
- Everything else — the full attribute set, kept verbatim
Alongside its own ldap_* fields it writes the shared user fields
user_full_name and user_email, and adds the entry's DN to the shared
distinguished_name, so its entries correlate against the other identity
sources. See Exported fields for the complete list.
ldap_attributesOnly the attributes above get their own field, but the raw entry is retained. If your directory carries something specific — an employee number, a cost centre — it is preserved there even without a dedicated field.
Requirements
The integration is outbound-only: it binds to the directory and runs a paged search on a schedule. Nothing is installed on the directory server, and nothing has to reach into the deployment.
Network access
| From | To | Protocol | Port |
|---|---|---|---|
| The sensor running the integration | The directory named in LDAP Server | LDAP over TCP | 389, or 636 for LDAPS |
Which of the two applies is decided by what you put in LDAP Server: an
ldaps:// URL selects LDAPS, an ldap:// URL or a bare hostname selects plain
LDAP on 389. That field is the only thing that decides it — see the warning
under Configuration before assuming the Ignore SSL checkbox
has a say.
This is an internal destination, so the rule belongs in the internal firewall rather than at the perimeter.
Access in the directory
| Need | Why |
|---|---|
| A read-only bind account | The run binds as LDAP User and searches; it never writes |
| Search rights on the configured Search Base | Scope the account to that subtree and no wider — see Preparing the bind account |
| Read access to the attributes you care about | The search asks for all attributes; anything the bind account may not read is simply absent from the result, with no error |
| A directory that permits paged search | Results are collected with a paged search of 1000 entries at a time |
In this deployment
| Need | Why |
|---|---|
| A registered, healthy sensor with reach to the directory | The integration runs on a sensor, on the platform's schedule — see Sensors |
Confirming reach and the bind credential in one step is worth doing before you
configure the instance — the ldapsearch command under
Preparing the bind account does both from the
sensor host itself.
Configuration
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Label for this instance |
| LDAP Server | Yes | Server to pull data from. The scheme decides the transport — ldaps://ldap.example.com for LDAPS, ldap:// or a bare hostname for plain LDAP |
| LDAP User | Yes | Bind DN or username |
| LDAP Password | Yes | Bind credential. Write-only: once saved, the console shows a locked box with Replace and never displays it again |
| Search Base | Yes | Subtree to search, e.g. ou=people,dc=example,dc=com |
| Search Filter | Yes | LDAP filter, e.g. (objectClass=inetOrgPerson) |
| Sensor | Yes | Sensor that will run the integration |
| Ignore SSL | Yes | Present on the form, but not consulted — see the warning below |
Search base and search filter are both mandatory — there is no implicit default, which is deliberate: an unscoped subtree search against a large directory is slow and rarely what you want.
The sensor connects to LDAP Server exactly as written and never reads Ignore SSL, so ticking or clearing it changes nothing. LDAPS or plain LDAP is chosen by the URL scheme alone, and a bare hostname means plain LDAP on 389.
Confirm whether the sensor validates the directory's certificate on an ldaps://
connection. The sensor passes no certificate settings of its own, so the behaviour
is the LDAP client library's default.
ldapsearch firstGetting a filter wrong produces an empty run rather than an error. Confirm it returns what you expect from the sensor host itself, which also proves network reach and the bind credential in one step:
ldapsearch -x -H ldaps://ldap.example.com \
-D 'cn=velumedge,ou=services,dc=example,dc=com' -W \
-b 'ou=people,dc=example,dc=com' '(objectClass=inetOrgPerson)' dn
Preparing the bind account
A read-only bind account with search access to the configured base is enough. Grant it nothing beyond the subtree you point the integration at.
There is no key or client to create — the credential is an ordinary directory account, and the two values you enter are simply its DN and password:
| The directory has | Enter it as | Example |
|---|---|---|
| The account's bind DN | LDAP User | cn=velumedge,ou=services,dc=example,dc=com |
| That account's password | LDAP Password | — |
The run then binds as that account and issues a paged search of Search Base with Search Filter, requesting every attribute the account is allowed to read.
Exported fields
Each directory entry the search returns becomes one asset record. The integration
copies the LDAP attributes into fields prefixed ldap_, keeping the attribute name
so a value in the platform can always be traced back to the entry it came from, and
additionally writes the shared user fields that make the entry correlate with other
identity sources.
Nothing is dropped after the fact — unlike the endpoint integrations, there is no staleness or completeness rule here. Every entry the search returns is written, so Search Base and Search Filter are the whole of the scoping.
Identity
| Field | Type | Holds |
|---|---|---|
ldap_exits | Boolean | Always true — the presence flag marking this asset as LDAP-covered |
ldap_dn | Text | The entry's distinguished name. The one single-valued field here, and what the run fingerprints an entry on |
ldap_cn | Text | cn |
ldap_uid | Text | uid |
ldap_displayName | Text | displayName. Its first value also becomes the shared user_full_name |
ldap_givenName | Text | givenName |
ldap_sn | Text | sn |
Contact
| Field | Type | Holds |
|---|---|---|
ldap_mail | Text | mail. Also becomes the shared user_email |
POSIX account
| Field | Type | Holds |
|---|---|---|
ldap_uidNumber | Text | uidNumber |
ldap_gidNumber | Text | gidNumber |
ldap_homeDirectory | Text | homeDirectory |
ldap_loginShell | Text | loginShell |
Classification
| Field | Type | Holds |
|---|---|---|
ldap_objectClass | Text | objectClass — the classes the entry declares |
ldap_description | Text | description |
Everything else
| Field | Type | Holds |
|---|---|---|
ldap_attributes | Text | Every attribute the search returned, flattened to name=value strings — one entry per value, so a multi-valued attribute contributes several |
ldap_dn is multi-valuedLDAP attributes are multi-valued by definition, and the integration preserves that
rather than collapsing to the first value. A filter on ldap_mail matches an entry
if any of its addresses match, and a report column will show all of them.
ldap_dn is the exception — an entry has exactly one.
These fields are registered without display labels, so ldap_uidNumber and
ldap_objectClass appear in the field picker, layouts and reports exactly as
written above, rather than as "UID Number" or "Object Class". Search by the
attribute name.
Shared fields it writes
These are the normalised, source-independent fields. They are what other integrations correlate against:
| Shared field | Derived from |
|---|---|
user_full_name | The first value of displayName, written only when the entry has one. It replaces a value another source wrote |
user_email | All values of mail, written only when the entry has at least one. It replaces a value another source wrote |
distinguished_name | The entry's DN, added to the DNs the user already holds, so the entry meets the copy of itself another directory integration wrote |
updated_at | Time of the run that produced the record |
The endpoint integrations report when an agent last checked in, and the platform
stores that as first_seen and last_seen. A directory entry carries no
equivalent, and this integration supplies none — so both stay empty on assets it
creates, and the Ignore of host is offline setting in the instance's advanced
parameters has nothing to act on. Use updated_at to tell when a user was last
confirmed present in the directory.
On each run the platform tries, in order: the entry's DN against ldap_dn, then
against the shared distinguished_name, then its mail values against
ldap_mail, then its uid values against ldap_uid, then its mail values
against the shared user_email, then its displayName values against the shared
user_full_name. The multi-valued comparisons need the whole set to match: an
entry with two addresses does not match a user holding only one of them. An entry
seen before is therefore found by its DN, and an entry renamed or moved in the
directory falls through to mail, uid and finally a name-only match, which is the
case most likely to produce a duplicate user asset.
See also
- Active Directory users — for AD specifically, with far richer account-state attributes
- Integrations overview — the shared configuration model
- Assets — inspecting which source asserted an attribute