Troubleshoot AD/LDAP Connector

1. Go to the Troubleshooting tab in the Admin Console to view the logs for the AD/LDAP Connector:

   

2. 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 CONNECTIONS_API_V2_KEY in the config.json file.

   You can also launch outside of the Admin Console:

   • Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\troubleshoot.cmd

   • Linux: node troubleshoot.js

   

   To learn more, see AD/LDAP Connector Configuration File Schema.

3. See the list of common issues and solutions below.

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.

The connector requires the clock on the server to be synchronized with the Auth0 service. The maximum allowed threshold is 5 seconds.

If you have a clock skew, you'll see output like this in the troubleshooter and connector logs:

12:18:55 - info: * Testing clock skew...
12:18:55 - error: × Clock skew detected:
12:18:55 - error: > Local time: 2020-05-04 12:18:55
12:18:55 - error: > Auth0 time: 2020-05-04 12:19:10

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.

If you are unsure if your server's clock is in sync with NTP, goto https://nist.time.gov/ and compare the time on that page with the time in the server where the connector is running. You shouldn't notice more than a one second difference between them.

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 nltest command. To test if a specific machine can reach the fabrikam.local domain, use nltest /dsgetdc:fabrikam.local.

• To see to which domain the current server is connected use nltest /dsgetdc:.

• When the domain does not exist or is unreachable, nltest will return an error message: Getting DC name failed: Status = 1355 0x54b ERROR_NO_SUCH_DOMAIN

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.

• If the machine hosting the connector is behind a proxy, you can configure an HTTP_PROXY system environment variable pointing to the URL of your proxy, or you can set this variable in the config.json file in the connector installation directory. If using an authenticated proxy, the URL must be in the format http://USERNAME:PASSWORD@SERVER_URL:PORT.

• Changing the config.json file or setting environment variables requires restarting the Connector service for the changes to take effect.

• The HTTP_PROXY URL cannot point to a .pac (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

  • SELF_SIGNED_CERT_IN_CHAIN errors

• If you have configured a proxy URL and restarted the connector service but are still seeing SELF_SIGNED_CERT_IN_CHAIN errors, make sure that your server is trusting the root certificate of the proxy. On Windows servers, you can check this by opening certmgr.msc and looking for your proxy's certificate. To learn more, see the article Proxy auto config (PAC) on Wikipedia.

https://{yourDomain} should be reachable from the server. A quick test for this is to open a browser pointing to https://{yourDomain}/test.

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 setting properly configured.

For more information on using Kerberos, see Configure AD/LDAP Connector Authentication with Kerberos.

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.

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:

1. Navigate to Auth0 Dashboard > Authentication > Enterprise, and select the Active Directory/LDAP connection type.

2. Select the name of the AD/LDAP connection to view.

3. Go to the Applications view, and enable the connection for the appropriate application(s).

4. Select Save.

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.

1. Modify the Connector configuration file with the PROVISIONING_TICKET value changed to use your custom domain in the format https://<YOUR-CUSTOM-DOMAIN>/p/ad/jUG0dN0R.

2. Restart the AD/LDAP Connector service for the change to take effect.

If you have not been able to resolve your issues contact Auth0 Support.

1. Click Export to create a .zip file containing the config.json file, the lib\\profileMapper.js file, the certs folder and the output of the troubleshooting tool.

2. Open a support ticket if you're experiencing problems with the following information:

   1. Symptoms

   2. AD/LDAP Connector version

      

   3. The .zip file containing: Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\config.json Linux: /opt/auth0-adldap/config.json

   4. The service log files from: Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\logs.log Linux: /var/log/auth0-adldap.log

• AD/LDAP Connector System Requirements
• Import and Export AD/LDAP Connector Configurations
• Set Up AD/LDAP Connector Test Environment
• Update AD/LDAP Connectors
• AD/LDAP Connector Configuration File Schema
• Monitor AD/LDAP Connector with System Center Operations Manager