LDAP Connector

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.

You can control the way LDAP connector presents dates and times by by using timestampPresentation configuration property. It has three possible values:

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.

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.

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

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:

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.

Since version 3.4 of the connector, LDAP connector has a support for fail-over functionality. Several LDAP servers can be configured in LDAP connector. The connector will fail over to a secondary server(s) in case that the primary server fails. This can be configured using the servers configuration property:

The main LDAP server configured using the usual configuration properties (host, port and similar) is considered a primary server. Secondary servers can be configured using servers configuration property. The example above is a configuration of two LDAP servers:

There are several requirements, assumptions and limitations to this functionality:

LDAP replication functionality is quite common in LDAP server implementations. The fail-over functionality of LDAP connector takes advantage of this functionality. However, LDAP servers generally implement only weak consistency guarantees for replicated directory topologies, which is somehow given by the design of LDAP protocol and directory data structures. Weak consistency has its significant advantages, yet it has also disadvantages. When it comes to operation of LDAP connector, perhaps the most problematic is a read-after-write scenario. The connector may write data to primary server, then the primary server goes down, connector fails over to the secondary server, which means that subsequent read gets outdated data from a secondary server. As the fail-over happens transparently in the connector, the application (midPoint) is not aware that fail-over took place, it has no idea that the data may be out of date. This may cause temporary fluctuations, where old data may be presented as current data for a limited period of time. However, both LDAP servers and midPoint are built for eventual consistency, converging data values eventually. However, data consistency has to be kept in mind, and proper method should be employed both at the LDAP side (e.g. replication failure recovery) and midPoint side (e.g. regular reconciliation) to make the entire system eventually consistent.

When you define the relation between object classes, the following changes automatically occur:

Both of the attributes, group and member, are currently constants in the connector code.

Reference attributes are special kinds of attributes that do not have simple values (string, integer, and so on), but contain references to other objects.

If you already have a schema generated before the Native References configuration has been set up, you have to refresh the connector schema.

If you use operational attributes in the values for the managedAssociationPairs configuration property, please also specify these attributes in the operationalAttributes configuration property. As we can see in the example above.

In rare cases, when using an "Object" object class (i.e. groupOfNames) which is extended via an auxiliary object class, please also add the auxiliaryObjectClasses configuration property to your resource configuration, and specify the auxiliary object classes which are used. The reason for this is that, the object-side attribute (i.e. member) is, in some cases, explicitly removed from object searches.

As there can be no empty groups, at least based on the LDAP specification, we had to implement a feature working around this. You can read about it the section, Groups Without Members And Native References.

The attributesNotReturnedByDefault parameter gives us the possibility to mark some of the standard attributes of the resource object with the NOT_RETURNED_BY_DEFAULT flag. Such attributes will be by default omitted from ldap search requests, unless the IAM explicitly requests them. We can use this configuration if some attributes are too large or expensive to retrieve (i.e. the member attribute).

The attributes specified in this property will be marked as NOT_RETURNED_BY_DEFAULT for all object classes.

If you already have a schema generated and add or modify this property in your configuration, you will have to refresh the connector schema.

If you are intending to use this configuration property, and your object classes are extended via an auxiliary object class, please also add the auxiliaryObjectClasses configuration property to your configuration.

The current implementation of the connector uses a wildcard (*) to return all non-operational attributes of an object in a search request, operational attributes are added to the request explicitly. In some cases we need to explicitly enumerate the non-operational attributes as well (rather than use a wildcard). The only problem here is that the connector does not know about the Auxiliary Object Classes, and is not capable of requesting the proper non-structural objectClass attributes.

The solution to this is to specify the Auxiliary Object Classes as values of the auxiliaryObjectClasses configuration property. Each value of this property is a string following a specific convention.

What the value inetOrgPerson:posixAccount represents:

One of the requirements specified in the LDAP standard is that the group attribute member is mandatory. This can be problematic during the creation and modification of groups (i.e. no initial values in member, removal of the last value in member).

If you are not using the native references configuration, you can work around this limitation with mappings in the resource configuration. With the native references, if you configure an object class amongst the values of the managedAssociationPairs property ,the schema for the member attribute of this object class changes.

Because of this a workaround was implemented directly in the ldap connector, wherever a new group is created or the last member of a group is removed a dummy member is added to the group as a placeholder.

This is mandated by the placeholderMember configuration property. The value of this property is a string representing the DN of a dummy member which is going to be used in the create or update operations.

This feature is currently supported only together with the Native References configuration.