LDAP Connector

Last modified 08 Oct 2021 16:55 +02:00

Identity connector for standard LDAPv3 directory servers.

Functionalitystable
Development statusactive (actively developed and maintained)
Support statussupported
OriginEvolveum
Support provided byEvolveum
Target systemsStandard LDAP servers (LDAPv3)
ProtocolLDAP/LDAPS
Source codehttps://github.com/Evolveum/connector-ldap

Capabilities and Features

Schema YES Determined from standard LDAP schema.

Provisioning

YES

Live Synchronization

YES

For LDAP servers that support Sun-style changelog (Retro ChangeLog) or modifyTimestamp. There is a contributed code for OpenLDAP synchronization. However, this is not included in "bundled" support.

Password

YES

It is assumed that the server will hash the password and store it securely. Support for connector-side hashing is limited.

Activation

PARTIAL

No activation for generic LDAP as there is not LDAP standard for that. This can be simulated in midPoint.

Filtering changes

PARTIAL

currently limited

Paging support

YES

Simple Paged Results and VLV

Native attribute names

YES

Use ri:dn instead of icfs:name. Use ri:entryUUID instead of icfs:uid.

Scripting

NO

Use of dedicated scripting connectors (SSH) is recommended.

Interoperability

In theory the connector should work with any LDAPv3 compliant LDAP server. However, many servers claim LDAPv3 compliance while the reality is far from ideal. The connector supports "quirks" of several popular LDAP servers and it tolerates some violations of LDAPv3 standards.

The connector was successfully tested with the following LDAP servers (assuming reasonably recent versions of the servers):

  • OpenLDAP

  • ForgeRock OpenDJ / wren:DS

  • 389 directory server / Red Hat Directory Server / Fedora Directory Server

  • Oracle Directory Server Enterprise Edition (DSEE) / Sun One / Sun Java System / iPlanet Directory Server

  • ViewDS

We know that at least some operations of the connector works with these servers and they are supported in some midPoint deployments. However, support for any specific server is not part of standard midPoint subscription and it has to be negotiated separately (see below).

If you are using this connector with a different directory server please let us know. We would like to know both about the positive and negative experiences.

Limitations

  • Additional search filter does not work for "Sun changelog" synchronization strategy. The structure of changelog does not allow direct application of the filter on server-side. Client side application of filter is not straightforward due various complexities and the implementation is not planned for now.

  • Synchronization based on modifyTimestamp has a simplistic implementation. It does not support SPR, VLV or referral-following functionality. This synchronization method is inherently inefficient and unreliable. It should be used only as a last resort, if no other method is available.

History

Version Origin Binary Sources Build Date Framework version Bundled with midPoint Description

1.4.1.23

Evolveum

download jar

GitHub

August 2015

Experimental version.

1.4.2.0

Evolveum

download jar

GitHub

December 2015

1.4.2.0

LDAP stable, AD experimental

1.4.2.14

Evolveum

download jar

GitHub

April 2016

1.4.2.14

3.3.1

Stable.

1.4.2.15

Evolveum

download jar

GitHub

April 2016

1.4.2.14

Stable.

1.4.2.16

Evolveum

download jar

GitHub

June 2016

1.4.2.14

Fixes timeout errors and resource leaks during AD connector resets.

1.4.2.17

Evolveum

download jar

GitHub

June 2016

1.4.2.14

3.4

Minor fixes.

1.4.2.18

Evolveum

download jar

GitHub

September 2016

1.4.2.14

3.4.1

Minor improvements.

1.4.2.19

Evolveum

download jar

GitHub

October 2016

1.4.2.18

Minor improvements.

1.4.3

Evolveum

download jar

GitHub

December 2016

1.4.2.18

3.5

Minor improvements.

1.4.4

Evolveum

download jar

GitHub

April 2017

1.4.2.18

3.5.1

CredSSP and Exchange powershell support, bugfixes, minor improvements.

1.4.5

Evolveum

download jar

GitHub

3rd July 2017

1.4.2.18

3.6

Powershell bugfixes, minor improvements.

1.5

Evolveum

download jar

GitHub

4th October 2017

1.4.2.18

3.6.1

More powershell execution alternatives and improvements, alternative auxiliary object class detection, explicit object class filter, configurable timestamp presentation, better error messages.

1.5.1

Evolveum

download jar

GitHub

11th December 2017

1.4.2.18

3.7, 3.7.1

Release coupled with AD connector.

1.6

Evolveum

download jar

GitHub

4th May 2018

1.4.2.18

3.7.2, 3.8

Release coupled with AD connector.

1.6.1

Evolveum

download jar

GitHub

17th April 2019

1.4.2.18

none

Fix of security vulnerability: missing check of certificate validity.

2.0

Evolveum

download jar

GitHub

7th November 2018

1.5.0.0

3.9

Native timestamp support. Support for delta-based updates. Additional search filter support.

2.1

Evolveum

download jar

GitHub

17th April 2019

1.5.0.0

none

OpenLDAP access log synchronization (contributed by Jonathan Gietz)
Object class handling improvements (contributed by Matthias Wolf)
Experimental support for "language-tagged" attributes.
Fix of security vulnerability: missing check of certificate validity.

2.2

Evolveum

download jar

GitHub

31st May 2019

1.5.0.0

none

Upgrade of Apache Directory API (may fix some connection issues)
Support for substring filter anchors (MID-5383)
Fixing localization of configuration properties

2.3

Evolveum

download jar

GitHub

13th August 2019

1.5.0.0

4.0

Upgrade of Apache Directory API
Support for defaultSearchScope

2.4

Evolveum

download jar

GitHub

22nd November 2019

1.5.0.0

TBD

Removed legacy support for eDirectory
Upgrade of Apache Directory API (2.0e1)
Support for "tree delete" LDAP control.

2.4.1

Evolveum

download jar

GitHub

23rd September 2020

1.5.0.0

TBD (probably 4.0.3)

Fix configuration order (MID-6312)

3.0

Evolveum

download jar

GitHub

3rd April 2020

1.5.0.0

4.1

Fixed detection of polystring attributes.
Implemented baseContextToSynchronize in timestamp-based synchronization.
Java 11 support (no Java 8 support any more).

3.1

Evolveum

download jar

GitHub

20th October 2020

1.5.0.0

4.2

Additional filter fixes at several places.
Improved VLV detection.
Proper SPR "abandon".
Improved error handling.
Misc minor fixes.

3.2

Evolveum

download jar

GitHub

31th March 2021

1.5.0.0

4.3

Optional unbind before disconnect
Improved connection handling (connection reuse, reconnects)
Upgraded Directory API to Evolveum version 2.0.1e1, which fixes file descriptor leak
Slightly improved logging
includeObjectClassFilter set to true by default

3.3

Evolveum

download jar

GitHub

8th October 2021

1.5.0.0

4.4

Fixed problem with excessive abandons
Several fixes and improvements related to timeouts and unbind operations
Support for TCP keepalive
Connection logging (terse format)
Smarter handling of root DSE fetches
Finer-grained timeouts
Root DSE fetch option for checkAlive
SHA-2 hash support (contribution, untested)

This is an LDAP connector completely rewritten from scratch in 2015. It is using Apache Directory API and it is designed and built to work with recent ConnId versions and to take all the advantages of that. This is the supported and recommended LDAP and AD connector for midPoint. The old LDAP and AD connectors are now deprecated and they are no longer supported.

Support

LDAP connector is bundled with midPoint distribution. Support for LDAP connector is included in standard midPoint support service (a.k.a. bundled support) - however, there are limitations. This "bundled" support only includes operations of LDAP connector that 100% compliant with LDAP standards. Any non-standard functionality is explicitly excluded from the bundled support.

It is a sad fact that so far we haven’t seen any LDAP server that would be 100% standard-compliant or that would not require any non-standard extensions to work. Therefore if you want to be sure that this LDAP connector will work with your LDAP server, we strongly recommend to negotiate support for that specific server in your midPoint support contract.

For the purposes of this definition "standard" means RFC specifications that reach at least a "proposed standard" status. Drafts, informational documents, vendor specifications or any other documents are not considered to be part of LDAP standards.

This means that the bundled support does not include support for any specific LDAP server. Support for specific servers needs to be explicitly negotiated in the support contract.

There may be exception to this rule for the customers that purchased support before the release of midPoint 4.0. In case of any doubts please contact Evolveum sales representatives.

When dealing with connector issues, please make sure to follow LDAP Connector Troubleshooting Guide.

Notes

The LDAP connector bundle also contains connector for Active Directory. These connectors are specializations of the LDAP connector and support the LDAP quirks needed to work with AD.

ConnId Result Handlers

We strongly recommend to disable all the handlers when working with well-designed connectors in general and when working with our LDAP or AD/LDAP connectors in particular.

Those "result handlers" are an artifact of an original original Identity Connector Framework over-engineering. The handlers are supposed to assist connectors by implementing "mechanism" that the connector or resource does not support - such as search result filtering, data normalization and so on. However, those handler are generic and they know nothing about the particulars of the resource that the connector connects to. Therefore in vast majority of cases those handlers just get into the way and they distort the data. Good connectors usually do not need those handlers at all. Unfortunately, these handler are enabled by default and there is no way for a connector to tell the framework to turn them off. The handlers needs to be explicitly disabled in the resource configuration.

<icfs:resultsHandlerConfiguration>
  <icfs:enableNormalizingResultsHandler>false</icfs:enableNormalizingResultsHandler>
  <icfs:enableFilteredResultsHandler>false</icfs:enableFilteredResultsHandler>
  <icfs:enableAttributesToGetSearchResultsHandler>false</icfs:enableAttributesToGetSearchResultsHandler>
</icfs:resultsHandlerConfiguration>

Date and Time Formats

 You can control the way LDAP connecto presents dates and times by by using timestampPresentation configuration property.
It has three possible values:
  • native: LDAP connector will present timestamps in native ConnId date format. This is the most natural and default setting.

  • unixEpoch: LDAP connector will present timestamps in UNIX epoch format (number of seconds since 1970)

  • ` string`: LDAP connector will present timestamps in LDAP-native format (generalized time, ISO 8601

In a normal case all timestamps in midPoint are in W3C DateTime format. When using the native time representation, MidPoint automatically converts all the date/time values to this format.

However, older versions of ConnId framework did not have any way how to express date/time information in the schema. The native time representation was not possible. ConnId framework was representing date/time information as (long) integers in UNIX timestamp format. For these cases there are options to represents time as long integer or string. This is mostly a historical feature now.

ObjectClass Filters

Natural way to use LDAP is to use "short" search filters, such as (cn=foo). However, such search filter can match objects of several incompatible objectclasses, producing incorrect results. Therefore a strict way to construct a search filter is to always add an objectclass clause to the filter, resulting in (&(objectclass=inetOrgPerson)(cn=foo)) filter. Use of such search filter ensures that the results will be correct.

This search filter should work flawlessly on standard-compliance and correctly-configured LDAP servers. Therefore since connector version 3.2, use of such search filters is tuned on by default. However, such search filters may cause issues on non-compliant and/or incorrectly configured and populated servers. In such case, the behavior can be controlled by includeObjectClassFilter configuration property.

Apache Directory API Warnings

You may be getting warnings and info messages in your log, like this:

WARN (org.apache.directory.api.ldap.model.entry.DefaultAttribute): ERR_13207_VALUE_ALREADY_EXISTS The value 'telephoneNumber' already exists in the attribute (m-may)
INFO (org.apache.directory.api.ldap.model.schema.registries.helper.MatchingRuleHelper): ERR_13765_MR_MUST_REFER_EXISTING_SYNTAX The created MatchingRule must refers to an existing SYNTAX element
WARN (org.apache.directory.api.ldap.model.entry.DefaultAttribute): ERR_13207_VALUE_ALREADY_EXISTS The value 'telephoneNumber' already exists in the attribute (m-may)
2021-04-27 13:35:58,121 [] [http-nio-8080-exec-35] INFO (org.apache.directory.api.ldap.model.schema.registries.helper.MatchingRuleHelper): ERR_13765_MR_MUST_REFER_EXISTING_SYNTAX The created MatchingRule must refers to an existing SYNTAX element

Generally speaking, those messages are benign. We are using Apache Directory API as an LDAP client library in our LDAP connector. The Directory API is quite pedantic when it comes to adherence to LDAP standards and schema consistency. However, there is perhaps no single LDAP server that is 100% compliant with LDAP standards (see LDAP Survival Guide). Hence the warnings and info messages in log files.

As we cannot really fix the serves, and the behavior of Directory API is technically correct, there is no right way to solve this issue. The easiest practical way to get rid of the messages is to set levels for particular loggers:

Logger Lever

org.apache.directory.api.ldap.model.entry.DefaultAttribute

ERROR

org.apache.directory.api.ldap.model.schema.registries

ERROR

Setting Directory API loggers to these levels should still be safe. In case of any major problem the connector itself should log appropriate error message.