LDAP Connector Troubleshooting

Last modified 21 Dec 2021 11:03 +01:00

Introduction

This page describes troubleshooting of LDAP Connector and Active Directory Connector (LDAP). Please make sure that you are familiar with basic connector troubleshooting techniques.

Logging

LDAP Operation Logging

The LDAP connector has a good logging of all operations. To enable the operation logging enable the following logger:

com.evolveum.polygon.connector.ldap.OperationLog: DEBUG

This will log all the LDAP operation request and responses, like this:

ldap://localhost:10389/ Search REQ base=uid=jbond,ou=People,dc=example,dc=com, filter=(objectClass=*), scope=base, attributes=[entryUUID], controls=null

ldap://localhost:10389/ Search RES Entry
    dn: uid=jbond,ou=People,dc=example,dc=com
    entryUUID: 20972cb8-34e8-43ec-b7a8-907857486394

The request and response logging is an excellent way how to diagnose communication and configuration problems. The logging will record essential parts of each request and response. That allows to clearly see what was sent to the LDAP server and what was received.

Connection Logging

Since 3.3 (LDAP Connector)
This functionality is available since version 3.3 of LDAP Connector.

LDAP operation logging is a detailed log of LDAP operations. Such logging is a great tool for diagnostics of functional problems in development and testing environments. However, LDAP operation log may be too detailed and verbose for busy testing and production environments. Therefore there is an alternative form of condensed connection and operation log called "connection log". Connection logging can be enabled by using following logger:

com.evolveum.polygon.connector.ldap.ConnectionLog: DEBUG

Connection log contains a single live for every LDAP operation, or other important event such as opening a new connection and closing old connection. The log looks like this:

CONN ldap://localhost:389/ connect success (localhost:389)
CONN ldap://localhost:389/ bind success (uid=idm,ou=Administrators,dc=example,dc=com)
CONN ldap://localhost:389/ rootDSE success ([+, *])
CONN ldap://localhost:389/ schema success (348 objectclasses, 0 errors)
CONN ldap://localhost:389/ search success (dc=example,dc=com sub (&(objectClass=inetOrgPerson)(uid=u00000000)) spr): 1 entries returned
...
CONN ldap://localhost:389/ close success (connector dispose)

Connection log is designed in a manner similar to LDAP server access logs, making diagnostics of connection-related issues easier.

Full Connector Logging

Full connector logging can be enabled by using the logger with the name of the connector package:

com.evolveum.polygon.connector.ldap: TRACE

However, this may be a very extensive logging. There is especially one component called SchemaTranslator that will log schema processing and data type conversions and so on. This is usually too much data. Therefore it is recommended to set it to a DEBUG log level:

com.evolveum.polygon.connector.ldap.schema: DEBUG

ConnId Framework Logging

Useful information may also be provided by the logging the operations of the ConnId connector framework. This is very useful in cases where the suspected problem is in the interpretation of the values (e.g. data type conversions). This logs all the communication between connector, connector framework and midPoint. It can be enabled by setting the logging to:

org.identityconnectors.framework.api: TRACE

Tips

There are parts of LDAP connector that log quite a lot of information. AbstractSchemaTranslator is quite notorious in this. Its job is to translate LDAP schema concepts to ConnId concepts, which is not always straigtforward. There are subtle issues that need fine-grained diagnotics to resolve. Hence the AbstractSchemaTranslator logs a lot of information, for almost every connector operation. Quite obviously, this is too noisy for normal troubleshooting. Therefore the best strategy is to explicitly silence the logger:

com.evolveum.polygon.connector.ldap.schema.AbstractSchemaTranslator: INFO

Common Issues

Already Exists Error

Situation: LDAP server responds with "attribute or value exists" error (LDAP error code 20).

This is a normal LDAP error indicating that an attempt was made to add a value of an attribute that already exists in the attribute. Or it may be an attempt to remove a value that is not there. This is most likely caused by midPoint trying it add a value that already exists in an LDAP object. MidPoint is trying to do that because it does not know that the value is already there. This may be caused by several things: the attribute values may not be returned by the LDAP server, the value may have been added to the LDAP very recently, this may be a configuration issue or even a product bug.

This operation is generally harmless - it does not change the state of the LDAP object at all. And this situation may be perfectly OK. However the LDAP standard mandates that the server must respond with an error in this case. Which is a bit of nuisance. But there are two ways to go around this:

  1. Permissive modify control. This control can be used to override the behavior stated by the standard. If this control is used the the LDAP server accepts the operation even if it adds exiting value or removes non-existing value. This is the most efficient way to resolve this situation. The connector should detect support for this control automatically and use it if it is available. However some LDAP severs (OpenLDAP in particular) are not properly advertising support for this control. Therefore it may be enabled by connector configuration:
    usePermissiveModify=true

  2. Avoid duplicate value configuration. This is a midPoint configuration that enables mechanism to avoid sending duplicate modifications to the resource. In that case midPoint will read the resource object and filter out duplicate modifications. This method is less efficient and may not work in some cases. But it usually works. It can be enabled in the resource configuration:

<resource>
    ...
    <schemaHandling>...</schemaHandling>
    <consistency>
        <avoidDuplicateValues>true</avoidDuplicateValues>
    </consistency>
    ...
</resource>

Active Directory Errors

Active Directory is a very unique directory server. It behave in strange, and sometime in quite unexpected way. Active Directory often indicates an error, that may seem wrong or misleading. The best method that we have figured out is not to take the errors at face value. Not not get mislead by the error. Try to systematically follow the troubleshooting guides. What was the LDAP operation that lead to the error. Which attributes were modified? What are the attribute values? Does the operation make sense?

Overall, diagnostics of AD errors is very difficult. There are logs on AD servers, but according to our experience those logs are almost useless. Detailed look at the LDAP operation is probably the best chance.

Was this page helpful?
YES NO
Thanks for your feedback