Active Directory Connector (LDAP)

Last modified 17 Mar 2025 15:11 +01:00

Connector for Active Directory servers based on the LDAP protocol.

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

Capabilities and Features

Schema YES Determined from standard LDAP schema, experimental support for native AD schema.

Provisioning

YES

Live Synchronization

YES

Active Directory DirSync synchronization supported.1)

Password

YES

Activation

YES

Activation using the userAccountControl attribute.

Paging support

YES

Simple Paged Results and VLV

Native attribute names

YES

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

Scripting

NO

Use of dedicated scripting connectors (SSH, PowerHell) is recommended.

Last login date

YES

Using configuration property where user can pick between lastLogon and lastLogonTimestamp attribute. It is important to note that the intended purpose of the lastLogonTimestamp attribute to help identify inactive computer and user accounts. The lastLogon attribute is not designed to provide real time logon information. With default settings in place the lastLogonTimestamp will be 9-14 days behind the current date.

For more info see documentation.

1) For the DirSync synchronization the DS-Replication-Get-Changes ( 1131f6aa-9c07-11d1-f79f-00c04fc2dcd2 ) extended right has to be granted.

Interoperability

Following versions of Active Directory are supported:

  • Active Directory Domain Services (AD DS), Windows Server 2022

  • Active Directory Domain Services (AD DS), Windows Server 2019

Active Directory Lightweight Directory Services (AD LDS) or any other variants of Active Directory or related services are NOT supported.

The connector supports only a subset of the operations that are available by using LDAP protocol and at the same time are documented in public Microsoft documentation. The connector does not claim to support all AD operations and complete AD functionality. Basic provisioning functionality is supported and it is tested in numerous real-world deployments. But advanced functionality may not be supported at all. Active Directory is a complex, proprietary and heavily non-standard system. It is not possible for the connector to support all the available operations. We recommend conducting a feasibility testing before deploying this connector. In case some connector functionality is missing then we recommend to purchase midPoint platform subscription to cover the functionality gap.

Unsupported Active Directory Versions

Following Active Directory versions (including their variants) are no longer supported, as they are not covered by regular (mainstream) support from Microsoft:

  • Active Directory 2016

  • Active Directory 2012, including 2012R2

  • Active Directory 2008, including 2008R2

Please see Evolveum support policy details.

Known Limitations

  • 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. Active Directory DirSync method should be preferred whenever available.

  • Minimal fetch strategy does not work reliably. LDAP has no way to specify that the connector wants to fetch all regular attributes except for one. Therefore, the connector has to list all the other attributes of an object, except the one expensive attribute (such as jpegPhoto or member). However, Active Directory has attributes that cannot be used it a regular (subtree) search. If the list of attributes happen to contain such an "unsearchable" attribute, the request fails. Even worse, AD is not exposing information about search limitations in standard LDAP schema. Therefore, this LDAP-based connector has no way to find out which attributes are not searchable.

    A symptom of this problem is usually an error: 00002120: SvcErr: DSID-…​…​., problem 5012 a.k.a. ERROR_DS_NON_BASE_SEARCH.

    Possible solution is to use non-standard schema definition data structures which are native to Active Directory. However, this code is not production-ready yet.

  • LDAP connector 3.4 introduced a fail-over mechanism for LDAP servers. However, this mechanism is designed for standard-compliant LDAP server (which AD is not), and it was not tested with Active Directory. Therefore, the fail-over mechanism is not supported for Active Directory.

  • The support for the VLV paging strategy depends on the total number of records and the value of MaxTempTableSize parameter on the Domain Controller (default of 10000 records). In case of higher amount of records, Exceptions will be thrown in case of vlv based searches (i.e. while searching for "all" records of a large object class).

    A symptom of this problem is usually an error: 000020EF: SvcErr: DSID-…​…​.., problem 5010 (UNAVAIL_EXTENSION).

    In case you are facing this issue the solution would be setting pagingStrategy to spr. Another possibility is to change the MaxTempTableSize parameter of the Domain controller (after consideration and only when you know what you are doing).

  • There are specific limitations for the Native References capability, see below.

MS Exchange Interoperability

Technically, this connector can be used to provision Microsoft Exchange servers in an indirect way by using PowerShell scripts.

Firstly, the Exchange attributes are accessible in Active Directory when the Exchange software is installed. The AD/LDAP connector dynamically discovers AD schema and therefore it will discover presence of these attributes. Then these attributes can be manipulated in a normal way. Please note that some Exchange attributes may not be properly propagated in the AD LDAP schema. In such case there is a workaround to specify these attributes in the operationalAttributes connector configuration property.

Secondly, since version 1.4.2.18 the connector had support to execute commands and powershell scripts remotely using the WinRM interface. This feature can be used to manage Exchange mailboxes and additional settings. This feature was later "separated" to a dedicated PowerShell scripting connector. Please see Powershell Support in AD/LDAP Connector page for more details.

However, support for MS Exchange is not included in the "bundled" support for this connector (see below).

History

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

1.4.2.0

Evolveum

download jar

GitHub

December 2015

Official release (experimental)

1.4.2.14

Evolveum

download jar

GitHub

April 2016

Official release (stable)

1.4.2.15

Evolveum

download jar

GitHub

April 2016

1.4.2.18

Evolveum

download jar

GitHub

September 2016

3.4.1

Powershell support. Bundled with midPoint 3.4.1.

1.4.2.19

Evolveum

download jar

GitHub

October 2016

1.4.2.18

Improved handling od DNs in AD multi-domain environment. MID-2926

1.4.3

Evolveum

download jar

GitHub

December 2016

1.4.2.18

3.5

1.4.4

Evolveum

download jar

GitHub

April 2017

1.4.2.18

3.5.1

CredSSP and Powershell and Exchange support.

1.4.5

Evolveum

download jar

GitHub

3rd July 2017

1.4.2.18

3.6

Powershell improvements.

1.5

Evolveum

download jar

GitHub

4th October 2017

1.4.2.18

3.6.1

Powerhell support. Alternative objectclass detection. Logging improvements.

1.5.1

Evolveum

download jar

GitHub

11th December 2017

1.4.2.18

3.7

Powerhell fixes.

1.6

Evolveum

download jar

GitHub

4th May 2018

1.4.2.18

3.8

Support for CredSSP version 5 and 6 (CVE-2018-0886)

1.6.1

Evolveum

download jar

GitHub

17th April 2018

1.4.2.18

TBD

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.
Textual representation of SID.
RunAs support that allows password changes using user’s own identity.
Additional search filter support.

2.1

Evolveum

download jar

GitHub

17th April 2019

1.5.0.0

none

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)
Fixed binary encoding of unicodePwd (MID-5242)
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
Experimental support for native AD schema
Experimental support for objectCategory searches and automatic management of objectCategory
Improved support for UserAccountContol (contributed)
Support for defaultSearchScope

2.4

Evolveum

download jar

GitHub

22th November 2019

1.5.0.0

TBD

Upgrade of Apache Directory API
Support for "tree delete" control.

3.0

Evolveum

download jar

GitHub

3rd April 2020

1.5.0.0

4.1

Separated PowerShell to a dedicated PowerShell Connector.
Improved DirSync error handling.
Fixed handling of timestamps (fractions of second)
Implemented baseContextToSynchronize.
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.
Improved support for boolean attributes.
Misc minor fixes.

3.2

Evolveum

download jar

GitHub

31st March 2020

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
includeObjectClassFilter set to true by default
Support for AD 2019

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

3.3.1

Evolveum

download jar

GitHub

22nd December 2021

1.5.0.0

N/A

Fixing AD "range" mechanism (used for large AD groups)

3.4

Evolveum

download jar

GitHub

25th March 2022

1.5.0.0

4.5

AD dirsync fix (MID-6922). Improved error messages. Minor bugfixes.

3.5

Evolveum

download jar

GitHub

10th October 2022

1.5.1.3

4.6

Added support for configuration discovery. Various AD fixes around userParameters and flags.

3.5.1

Evolveum

download jar

GitHub

17th March 2025

1.5.2.0

Bumped mina-core to 2.2.4.

3.6

Evolveum

download jar

GitHub

21st March 2023

1.5.1.3

LDAP integer syntax is mapped to BigInteger, supporting large numbers (MID-4424)

3.6.1

Evolveum

download jar

GitHub

27th March 2023

1.5.1.3

4.7

Synchronized bundle release with LDAP connector.

3.7

Evolveum

download jar

GitHub

10th October 2023

1.5.1.3

4.8

Fixing of repeated adding of removed UAC attributes.

3.7.1

Evolveum

download jar

GitHub

10th January 2024

1.5.1.3

4.8.1, 4.9

Fixing of default value for 'connectTimeout', 'writeOperationTimeout', 'readOperationTimeout', 'closeTimeout' and 'sendTimeout' configuration attributes.

3.7.2

Evolveum

download jar

GitHub

16th August 2024

1.5.2.0

4.8.4

Update dependencies.

3.7.3

Evolveum

download jar

GitHub

8th October 2024

1.5.2.0

4.8.5

Addition of third error code for AD X_BIND_REQUIRED error

3.7.4

Evolveum

download jar

GitHub

17th March 2025

1.5.2.0

4.8.7

Bumped mina-core to 2.2.4.

3.8

Evolveum

download jar

GitHub

17th October 2024

1.5.3.0-M3

4.9

Native association support. Possibility to choose attributes that should not be returned by default. Possibility to choose to encode string values in case of the presence of non standard ASCII characters. Workaround for open-ldap mandatory member attribute. Possibility to specify used auxiliary object classes in connector configuration. Allow to send the LDAP_DIRSYNC_OBJECT_SECURITY flag in Active Directory sync request control.

3.9

Evolveum

download jar

GitHub

10th February 2025

1.5.3.0-M3

Added support for _LAST_LOGIN_DATE_ attribute (capability). Added new configuration option logSchemaErrors to log errors during schema operation. By default, for AD errors are not being logged, for other LDAP servers errors are logged. Fix in the listing of ('out of the scope') attributes in object queries while using native references.

3.9.1

Evolveum

download jar

GitHub

17th March 2025

1.5.3.0-M3

4.9.2

Bumped mina-core to 2.2.4.

fixes handling of ENABLE attribute

This connector is based on the LDAP Connector which was completely rewritten from scratch during 2015-2016.

Support

This 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:

  • Only some Active Directory versions are supported (see above)

  • Only some Active Directory features are supported (see above). The connector does not claim to be feature-complete. We recommend conducting a feasibility testing before deploying this connector. In case some connector functionality is missing then we recommend to purchase midPoint platform subscription to cover the functionality gap.

  • PowerShell scripting implemented in this connector is supposed to be used to supplement creation of Active Directory (windows) accounts by using simple scripts. It is not supposed to be used to manage Microsoft Exchange accounts. Management of Exchange accounts can be quite a complex matter, requiring complicated PowerShell scripts. Support for the use of this connector to manage Exchange accounts has to be purchased separately.

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.

Licensing

The connector itself is available under the terms of Apache License 2.0. The connector is using only the LDAP protocol to access Active Directory. We are not using any Microsoft library or any other component that might be subject to Microsoft licensing. To our best knowledge no extra license is needed to use the connector with Active Directory. However the Microsoft license texts are not entirely clear and we are not lawyers. Therefore it is recommended for each user to make his own analysis of the licensing issues. Please use your Microsoft support program and contact Microsoft with the licensing question when in doubt.

Notes

This connector is contained in LDAP connector bundle, which also contains LDAP connector. Both connectors are specializations of the LDAP connectors. The Active Directory connector has additional support for 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>

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.

Native References

Starting from the connector version 3.8, the LDAP connector is capable of working with reference attributes that describe the relation between resource objects, like between accounts and groups they are members of.

This behavior is governed by the managedAssociationPairs multivalued configuration property.

Each value of this property is a string with a specific formatting convention. Based on this information the connector figures out which object classes have a relation between each other and also which attributes should be used for such relation.

An example: Defining a relation between user and group
<connectorConfiguration>
    <configurationProperties>
        <host>primary.ldap.example.com</host>
        <baseContext>dc=evolveum,dc=com</baseContext>
        <operationalAttributes>memberOf</operationalAttributes>
        <managedAssociationPairs>"user"+memberOf -# "group"+member</managedAssociationPairs>
        ...
    </configurationProperties>
</connectorConfiguration>

The value of "user"+memberOf -# "group"+member specifies that:

  • Object classes user and group are in a relationship.

  • user is the subject (the one who receives an entitlement), while group is the object (the entitlement being granted).

  • The binding attributes on the user side is memberOf. The related groups for a given account are determined by looking at this attribute.

  • The binding attribute on the group side is member. The related members are determined by looking at this attribute. Also, this attribute is used to update the membership information.

Subject and object

As mentioned above,

  • subject is the resource object which receives an entitlement, typically an account;

  • object is the resource object which represents an entitlement, typically a group.

They have a relation between them, typically, a subject (an account) is member of a group. More information about this topic can be found in Entitlements and Associations.

The managedAssociationPairs values have the following formatting convention:

"SubjectObjectClassName"+SubjectAttribute -# "ObjectObjectClassName"+ObjectAttribute

  • SubjectObjectClassName is the object class representing the subject of this relation.

  • SubjectAttribute is the attribute of that object class containing the list of related objects, typically groups that the account is a member of.

  • ObjectObjectClassName is the object class representing the object of this relation.

  • ObjectAttribute is the attribute of that object class containing the list of related subjects, typically the members of the group.

By using the above example, the connector will manage the relations between the object class user and the object class group based on the values present in the parameters memberOf (for user) and member (for group).

As this is a multivalued property, you can specify multiple pairs of object types, each of them having a relation between them marked as managed by the connector.

An example: Defining two relations between object classes
<connectorConfiguration>
    <configurationProperties>
        ...
        <managedAssociationPairs>"user"+memberOf -# "group"+member</managedAssociationPairs>
        <managedAssociationPairs>"group"+memberOf -# "group"+member</managedAssociationPairs>
        ...
    </configurationProperties>
</connectorConfiguration>

The addition of this parameter will signal to the connector that it should use the native references handling. This also changes the way the schema is generated by the connector, see below.

Representation of Native References in the Schema

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

  1. The original attributes used to provide the relation, e.g. memberOf and member in the above examples, will disappear from the schema.

  2. The subject-side attribute, e.g. memberOf, will be replaced by the reference attribute group.

  3. The object-side attribute, e.g. member, will be replaced by the reference attribute member.

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.

The new member attribute on the object (entitlement) side is marked as "not readable" and "not returned by default", because fetching of this attribute is not currently supported by midPoint.

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

Other Things to Consider

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. group) 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.

Limitations

  1. This feature assumes that there is the memberOf (or equivalent) attribute on the subject size that is used to provide the membership information.

    If this attribute is missing, the native references feature of the connector cannot be used.

  2. Only one class of objects (entitlements) is supported per subject-object relation (e.g., for memberOf attribute of user, we assume that all referenced objects will be of the object class group).

  3. Events related to object relations (like adding or deleting a group membership to an account) cannot be currently detected by the live synchronization.

  4. The connector does not handle 'primary groups' as a part of the entitlements managed by the native association handling.

Marking Attributes as Not Returned by Default

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.

Auxiliary Object Classes

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.

An example: Defining the structural object class user with an auxiliary object class posixAccount
<connectorConfiguration>
    <configurationProperties>
        ...
        <auxiliaryObjectClasses>user:posixAccount</auxiliaryObjectClasses>
        ...
    </configurationProperties>
</connectorConfiguration>

What the value user:posixAccount represents:

  • user is the name of the structural object class

  • : delimiter between the name of the structural object class and auxiliary object classes

  • posixAccount is the name of the auxiliary object class

  • Any number of additional auxiliary object classes may be added to the value by using the delimiter , between the names of the auxiliary object classes

Resource Examples

See Also

Was this page helpful?
YES NO
Thanks for your feedback