Troubleshoot AD/LDAP Connector
Initial troubleshooting steps
Go to the Troubleshooting tab in the Admin Console to view the logs for the AD/LDAP Connector:
Click Run on the Troubleshooting page to run the troubleshooting tool to detect the most common problems related to the AD/LDAP Connector. To detect issues with certificates set
config.jsonfile. See AD/LDAP Connector Configuration File Schema for details.
You can also launch outside of the Admin Console:
Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\troubleshoot.cmd
Linux: node troubleshoot.js
See the list of common issues and solutions below.
Installation and configuration issues
After clicking Save, the AD/LDAP Connector configuration console performs a series of tests to validate the entered information. The results of the tests are displayed under the Configuration log heading in the console screen. An explanation is provided below of the tests performed.
Test 1: Attempts to establish a TCP connection to the LDAP server and port specified. If Test 1 fails, check basic network connectivity and firewall settings that might prevent such a connection.
Test 2: Attempts to perform an LDAP bind on the LDAP server and port specified and with the username and password provided. If Test 2 fails, check the LDAP connection string, search path, username, and password.
Test 3: Attempts to perform an LDAP search against the directory to check the privileges of the specified username. If Test 3 fails, check the privileges of the username in the target directory.
Test 4: Attempts to establish a connection to the Auth0 server. If Test 4 fails, check network connectivity and firewall settings that might prevent such a connection.
Common issues and solutions
Make sure the clock of your server is current. If the time is not correct, it will cause authentication requests to fail. This can be fixed by ensuring the system is properly configured to poll a sync server via the Network Time Protocol (NTP). In Windows environments, the NTP provider is usually the same domain controller. Make sure that your Domain Controller is synchronized with some external service.
For instructions on synchronizing your Active Directory environment with an external time server check out this blog post: How to configure NTP server in Active Directory, Step by step.
No connection to Active Directory
The connector should be installed on a server that can reach the LDAP server. When firewalls and VPN connections are placed between the AD/LDAP Connector and the LDAP server it may lead to connectivity issues.
In a Windows Network with Active Directory use the
nltestcommand. To test if a specific machine can reach the
To see to which domain the current server is connected use
When the domain does not exist or is unreachable,
nltestwill return an error message:
Getting DC name failed: Status = 1355 0x54b ERROR_NO_SUCH_DOMAIN
UNABLE_TO_VERIFY_LEAF_SIGNATURE error message (Private Cloud)
This error applies to the AD/LDAP Connector in combination with Private Cloud.
This error message occurs when the Connector fails to start when it can't validate the SSL certificate configured in the Private Cloud. This can happen when the Root Certificate (or any Intermediate Certificates) are missing in the machine's Certificate Store (Windows). In order to solve this, import the certificate chain in the Local Machine > Trusted Root certificate store on the machine where the AD/LDAP Connector is installed.
Connector behind a proxy
If the machine hosting the connector is behind a proxy, you can configure an
HTTP_PROXYsystem environment variable pointing to the URL of your proxy, or you can set this variable in the
config.jsonfile in the connector installation directory. If using an authenticated proxy, the URL must be in the format
config.jsonfile or setting environment variables requires restarting the Connector service for the changes to take effect.
HTTP_PROXYURL cannot point to a .pac (proxy auto-config) file; it must be the URL of the proxy itself. If your proxy is configured through a .pac file, download the .pac file and find the proxy URL there.
An incorrectly configured proxy can result in several problems, such as:
Auth0 servers not reachable
If you have configured a proxy URL and restarted the connector service but are still seeing
SELF_SIGNED_CERT_IN_CHAINerrors, make sure that your server is trusting the root certificate of the proxy. On Windows servers, you can check this by opening
certmgr.mscand looking for your proxy's certificate.
No internet connectivity
https://YOUR_DOMAIN should be reachable from the server.
A quick test for this is to open a browser pointing to
Service account permissions
The Service account used to configure the connector must have read permissions on the AD/LDAP server, as well as capable of querying groups for users.
To enable verbose logging of Kerberos requests, add a system level environment variable
DEBUG=kerberos-server. Then restart the Connector. Try logging in again, and check the logs for more information.
If you have Kerberos enabled, but your users are being prompt for username/password, you likely don't have the IP address settings properly configured.
Changes in user profile in AD are not immediately reflected in the app
The Connector uses two levels of configurable caching:
One on the Auth0 server, which caches both credentials and user profile.
A second level in the connector itself, which only caches group membership of a user.
The server caches the last successfully authenticated user profile, including the username and password (hash). It is enabled by default, and can be disabled. The purpose of this first level cache is to maximize availability of authentication transactions when AD is unavailable (such as a network outage). It is only activated if the Connector/AD/LDAP servers are unavailable.
The Connector caches only groups a user might be a member of. Its lifetime is controlled with the
GROUPS_CACHE_SECONDS configuration variable. If not present, the value is 600 seconds. Groups are cached, because by default, the Connector retrieves all group membership of a user recursively, which can be costly in some AD/LDAP installations. Cache is deleted on each Connector restart.
These two settings might affect how profile information flows to an app. But in general, AD changes don't happen very often.
In some AD/LDAP installations, user attributes synchronization takes a few minutes.
Connector restarts after "auth0: Connection closed." message in the log
To avoid the requirement of an open inbound port in your servers, the Connector creates a websocket connection to an available node in Auth0's server cluster and keeps it open to listen to incoming messages from Auth0.
Approximately once a day (though this frequency might vary under certain circumstances) each server node will terminate the connection to allow internal deployment processes to occur. The Connector will detect the closed connection and terminate the process, allowing the service stack to restart the process, create a new connection to an available node and resume operations. To avoid any downtime, enable the cache:
Navigate to the Connections > Enterprise page in the Auth0 Dashboard.
Click the name of the AD/LDAP connection to view.
Go to the Applications tab.
Enable the connection for the appropriate application(s).
Receive "postUrl is required" error
This is usually thrown if additional configuration for custom domains have not been made. In order to use AD/LDAP connections with Kerberos support, you will need to update the Ticket endpoint to work with the custom domain.
Modify the Connector configuration file with the
PROVISIONING_TICKETvalue changed to use your custom domain in the format
Restart the AD/LDAP Connector service for the change to take effect.
Contact Auth0 Support
If you have not been able to resolve your issues contact Auth0 Support.
Click Export to create a .zip file containing the
certsfolder and the output of the troubleshooting tool.
Open a support ticket if you're experiencing problems with the following information:
AD/LDAP Connector version
The .zip file containing: Windows:
C:\Program Files (x86)\Auth0\AD LDAP Connector\config.jsonLinux:
The service log files from: Windows:
C:\Program Files (x86)\Auth0\AD LDAP Connector\logs.logLinux: