Integrating API Portal with MS Active Directory

Document ID : KB000077034
Last Modified Date : 10/04/2018
Show Technical Document Details
Introduction:
While integrating the API Portal 4.2.3 with Active Directory, users may face an error about "Incomplete Base Distinguished Name" - even if all the connection data is correct.

Example of the error

This happens when the AD Root DN is configured as Base DN, instead of a specific OU.
Background:
While querying AD via the default LDAP port (389 or 636), the data you reach is not the complete AD Domain data. Even if you have only a single Domain Controller in your Domain (for example, a test environment) you may face the problem.

Why does this happen?

Because of the way AD deals with its internal referrals. When connecting to a Domain Controller using a standard Java LDAP client, having the root of the domain as the Base DN, the Java LDAP client returns an error regarding incomplete search results, because the standard Java LDAP client cannot follow the many referrals that AD reports in the default search. By default, AD will build the domain structure in a way it can be easily split between domain controllers and, since each server will hold a piece of the data - not the whole domain data - AD uses referrals to find the data among all DCs. 

However, AD needs a repository that contains the whole domain data, in order to provide searches and ensure replication integrity. This repository is the Global Catalog, that may reside in one or more Domain Controllers, and it is available at a different port - port 3268. Every time you connect to the Global Catalog server, you are accessing the whole domain data. It is faster to search and do not have any referrals, as a Global Catalog does not need referrals because it already holds the whole data. Microsoft itself recommends the use of the Global Catalog in this kind of use case.
Environment:
API Portal 4.2.3

Note: CA will work to add support for AD LDAP Referrals on future releases.
Instructions:
1. Replace the LDAP URL from: 

ldap://domaincontroller.your.domain:389 

to 

ldap://your.domain:3268 

2. Redo the configuration using the Root DN of the AD Domain as Base DN.
Additional Information:
"What Is the Global Catalog?" - https://technet.microsoft.com/pt-pt/library/cc728188(v=ws.10).aspx 
"Global Catalog and LDAP Searches" - https://technet.microsoft.com/en-us/library/cc978012.aspx