Skip to main content
Version: 0.10

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 nameldap_users
CreatesUsers
Runs onA sensor with network reach to the LDAP server
Presence flagldap_exits
Field prefixldap_

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.

Everything else is still in ldap_attributes

Only 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​

FromToProtocolPort
The sensor running the integrationThe directory named in LDAP ServerLDAP over TCP389, 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​

NeedWhy
A read-only bind accountThe run binds as LDAP User and searches; it never writes
Search rights on the configured Search BaseScope the account to that subtree and no wider — see Preparing the bind account
Read access to the attributes you care aboutThe 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 searchResults are collected with a paged search of 1000 entries at a time

In this deployment​

NeedWhy
A registered, healthy sensor with reach to the directoryThe 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​

FieldRequiredNotes
NameYesLabel for this instance
LDAP ServerYesServer to pull data from. The scheme decides the transport — ldaps://ldap.example.com for LDAPS, ldap:// or a bare hostname for plain LDAP
LDAP UserYesBind DN or username
LDAP PasswordYesBind credential. Write-only: once saved, the console shows a locked box with Replace and never displays it again
Search BaseYesSubtree to search, e.g. ou=people,dc=example,dc=com
Search FilterYesLDAP filter, e.g. (objectClass=inetOrgPerson)
SensorYesSensor that will run the integration
Ignore SSLYesPresent 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.

Ignore SSL does nothing here

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.

TODO

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.

Test the filter with ldapsearch first

Getting 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 hasEnter it asExample
The account's bind DNLDAP Usercn=velumedge,ou=services,dc=example,dc=com
That account's passwordLDAP 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​

FieldTypeHolds
ldap_exitsBooleanAlways true — the presence flag marking this asset as LDAP-covered
ldap_dnTextThe entry's distinguished name. The one single-valued field here, and what the run fingerprints an entry on
ldap_cnTextcn
ldap_uidTextuid
ldap_displayNameTextdisplayName. Its first value also becomes the shared user_full_name
ldap_givenNameTextgivenName
ldap_snTextsn

Contact​

FieldTypeHolds
ldap_mailTextmail. Also becomes the shared user_email

POSIX account​

FieldTypeHolds
ldap_uidNumberTextuidNumber
ldap_gidNumberTextgidNumber
ldap_homeDirectoryTexthomeDirectory
ldap_loginShellTextloginShell

Classification​

FieldTypeHolds
ldap_objectClassTextobjectClass — the classes the entry declares
ldap_descriptionTextdescription

Everything else​

FieldTypeHolds
ldap_attributesTextEvery attribute the search returned, flattened to name=value strings — one entry per value, so a multi-valued attribute contributes several
Every field except ldap_dn is multi-valued

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

The field picker shows raw attribute names

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 fieldDerived from
user_full_nameThe first value of displayName, written only when the entry has one. It replaces a value another source wrote
user_emailAll values of mail, written only when the entry has at least one. It replaces a value another source wrote
distinguished_nameThe entry's DN, added to the DNs the user already holds, so the entry meets the copy of itself another directory integration wrote
updated_atTime of the run that produced the record
No first-seen or last-seen for LDAP users

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.

How an entry is matched to an existing user

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​