Motivation

In 2014 the "state of the art" for connectors in open source provisioning was the legacy of Identity Connector Framework (ICF) created by Sun Microsystems. This is still perhaps the best option for supporting identity connectors that is available to the open world. However, the Sun ICF framework is flawed. It was poorly designed and the framework issues are also reflected to the connectors. Projects such as ConnId are working towards the improvement of the Sun ICF. And there is a reasonable success. However one thing is the improvement of the framework and a slightly different thing is improvement of the connectors. The connectors often significantly lack behind the framework capabilities.

Old LDAP Connector

Original Sun LDAP connector is one of the connectors that is falling behind.There have been efforts from Evolveum and also from the OpenICF project to improve this connector - and some were quite successful. But now it is clear that the original Sun LDAP connector is a development dead end. It can be maintained, but there is very little potential of future development. The old LDAP connector has many fundamental problems:

New LDAP Connector

Therefore the Evolveum team has decided to write a completely new connector from scratch. The new LDAP connector is inherently better:

LDAP Connectors in midPoint

All midPoint versions up to Release 3.1.1 used the legacy SunICF/OpenICF LDAP connector. This connector was bundled inside midPoint.

All midPoint versions starting from Release 3.2 are using the new LDAP Connector. This connector is bundled inside midPoint.

Starting from Release 3.2 the legacy connector is no longer included inside midPoint. But it still can be used if the connector JAR file is downloaded and deployed. See Legacy LDAP Connector page for supported versions and download locations. The legacy LDAP connector will not be extended or developed any more. But it will be maintained in a working state during a reasonable migration period.

Therefore the change from Release 3.1.1 (or earlier) to Release 3.2 (or later) is an incompatible change when it comes to an LDAP connector. The migration steps are described below.

Migration: New LDAP Connector

The new LDAP connector is not backwards compatible with the old connector. It is a completely new connector in code, behavior and also in philosophy. There are three major differences:

Connector Name and Bundle

The new LDAP connector is using bundle and connector name from com.evolveum.polygon namespace. The configuration XML namespace also reflects that:

Bundle name (connectorBundle)

com.evolveum.polygon.connector-ldap

Connector name (connectorType)

com.evolveum.polygon.connector.ldap.LdapConnector

Configuration namespacehttp://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/com.evolveum.polygon.connector-ldap/com.evolveum.polygon.connector.ldap.LdapConnector

Connector Configuration

LDAP Connector has a completely new configuration schema. The new connector is using similar configuration properties than the old connector when that was appropriate. But due to the major changes in connector philosophy it was almost not possible at all. The new configuration properties are summarized below:

Property nameLabelDescription
hostHostThe name or IP address of the LDAP server host.
portPort numberLDAP server port number.
connectionSecurityConnection securityMethod to use to secure connection to the LDAP server. Values: "ssl", "starttls"
authenticationTypeAuthentication typeThe authentication mechanism to use. Values: "simple", "SASL-GSSAPI"
bindDnBind DNThe DN to use when binding to the LDAP server
bindPasswordBind passwordPassword to use when binding to the LDAP server
connectTimeoutConnect timeoutTimeout for LDAP server connection (in milliseconds)
baseContextBase contextThe base DN used when no explicit base DN is specified
referralStrategyReferral strategyStrategy of referral resolution. Values: "follow", "ignore", "throw"
passwordAttributePassword attributeName of the LDAP attribute that is used to store account password
passwordHashAlgorithmPassword hash algorithmHash the passwords with a specified algorithm before they are sent to the server.
pagingStrategyPaging strategyStrategy used to send search requests that require paging. Usually specified preference over mechanisms such as VLV or simple paged results. Values: "none", "auto", "spr", "vlv"
pagingBlockSizePaging block sizeNumber of entries in one paging block. Used as a default value when page size is not explicitly specified in the request.
vlvSortAttributeVLV sort attributeName of LDAP attribute used to sort the results if VLV is used for paging and no explicit sorting attribute is specified in the request.
vlvSortOrderingRuleVLV ordering ruleLDAP ordering rule to use in VLV requests. Some LDAP servers require explicit specification of ordering rule.
uidAttributePrimary identifier attributeName of LDAP attribute to use as a primary identifier. This will be used as ConnId __UID__ attribute. The default is entryUUID which is the best choice for modern LDAP servers. Value of "dn" can be used here to use entry DN as a primary identifier.
operationalAttributesOperational attributesNames of significant LDAP operational attributes. Connector will try to return these attributes in each entry.
readSchemaRead schemaIf set to true (which is the default) then the connector will try to read LDAP schema.
schemaQuirksModeSchema quirks modeSome LDAP servers use strange or non-standard variations of schema definition. The quirks mode is used to tolerate these variations and use as much of the schema definition as possible.
synchronizationStrategySynchronization strategyStrategy to use for almost-real-time synchronization. Values: "none", "auto", "sunChangeLog", "modifyTimestamp"
changeLogBlockSizeChangelog block sizeNumber of change log entries to fetch in a single request.
changeNumberAttributeChange number attribute"Change number" attribute - unique indentifier of the change in the change log.

Configuration samples for all LDAP resources were updated to the new LDAP connector. The Configuration Samples are located at the usual places.

Shadows

The shadows in the old connector looked like this:

<shadow>
  <objectClass>AccountObjectClass</objectClass>
  ...
  <attributes>
    <icfs:name>uid=foo,ou=people,dc=example,dc=com</icfs:name>
    <icfs:uid>b41da37e-3b58-11e5-ad73-001e8c717e5b</icfs:uid>
    <ri:uid>foo</ri:uid>
    <ri:cn>Foo Bar</ri:cn>
    ...
  </attributes>
</shadow>

Shadow for new connector looks like this:

<shadow>
  <objectClass>inetOrgPerson</objectClass>
  ...
  <attributes>
    <ri:dn>uid=foo,ou=people,dc=example,dc=com</ri:dn>
    <ri:entryUUID>b41da37e-3b58-11e5-ad73-001e8c717e5b</ri:entryUUID>
    <ri:uid>foo</ri:uid>
    <ri:cn>Foo Bar</ri:cn>
    ...
  </attributes>
</shadow>

The new LDAP connector is using native names of attributes and object classes and therefore it has obviously cleaner and better data structure. But this data structure is different and currently there is no way how to automatically transform the shadows.

Migration steps

We recommend the following migration procedure:

  1. Add resource that will use the new LDAP connector. Configure it as a completely new resource using the same hostname/port/credentials as the old one.

  2. Change assignment enforcement level to a permissive value (none or positive).

  3. Set up a correlation expression to correlate users with the LDAP accounts. Reconcile the new LDAP resource. The result should be that the LDAP accounts on the new resource are linked.

  4. Modify definitions of role and/or direct assignments to point to the new LDAP resource instead of the old one. Resource reference (resourceRef) needs to be changed, but also any mappings for identifier attributes (icfs:name and icfs:uid in the old connector).

  5. Delete old LDAP resource and all shadows that belong to that resource (there is now an option to do this efficiently in the “Repository Objects” GUI page).

  6. Recompute the users. This should remove the orphaned linkRefs in user objects.

  7. Double-ckeck that every thing is switched to the new resource (roles, assignments, shadows exist and are linked to users).

  8. Change assignment enforcement level to the original.

Migration: Legacy LDAP Connector

The legacy LDAP connector is still available and it still can be used. This avoids the need for data (shadow) migration. There is only a change in legacy LDAP connector bundle name (from “com.evolveum.polygon.connector-ldap” to “com.evolveum.polygon.connector-ldap-legacy”).

To use the legacy LDAP connector in midPoint 3.2 or later please follow these steps:

  1. Download JAR of the legacy LDAP connector and deploy it into midPoint

  2. In all the resource definitions change connectorRef to point to the newly discovered legacy LDAP connector.

  3. In all the resource definitions change connector configuration namespace from “http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/com.evolveum.polygon.connector-ldap/org.identityconnectors.ldap.LdapConnector” to “http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/com.evolveum.polygon.connector-ldap-legacy/org.identityconnectors.ldap.LdapConnector”.

  4. No change in configuration, shadows or roles is needed.

The legacy LDAP connector will be maintained for a reasonable migration period which mostly depends on the requirements of midPoint subscribers. After that period the legacy connector will no longer be supported. Therefore please plan the migration to the new connector accordingly.

See Also