Troubleshoot AD/LDAP Connector

If you are experiencing issues with your AD/LDAP Connector, read below to learn how to troubleshoot common issues.

You can run the troubleshooting tool in the AD/LDAP Connector Admin Console, or outside the Admin Console by executing the program manually.

To detect issues with certificates, set the CONNECTIONS_API_V2_KEY variable in the AD/LDAP Connector configuration file.

You can run the troubleshooting tool in the Admin Console.

1. Switch to the Troubleshooting view to read the logs.

   

2. Select Run to detect the most common problems related to the AD/LDAP Connector.

You can launch the troubleshooting tool outside of the Admin Console.

On a Windows machine, run the provided command file to launch the troubleshooting tool.

1. Locate the AD/LDAP Connector folder (AD LDAP Connector).

2. Run the troubleshoot.cmd file.

For example: C:\Program Files (x86)\Auth0\AD LDAP Connector\troubleshoot.cmd.

On a Linux machine, run the provided Node.js program to launch the troubleshooting tool.

1. Open a new terminal window.

2. Change the working directory to the AD/LDAP Connector folder (AD LDAP Connector).

3. Run the node troubleshoot.js command.

After clicking Save, the AD/LDAP Connector Admin Console performs a series of tests to validate the provided information. The results of the tests are displayed under the Configuration log heading.

The Admin Console performs the following tests:

• 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.

Descriptions of several common issues and their solutions are listed below.

By default, the Auth0 AD/LDAP Connector imports a user’s group memberships from Active Directory and includes them on the user object.

This behavior requires the AD/LDAP Connector to perform additional queries against Active Directory, which can significantly increase the duration of the authentication process.

If you do not need groups to be returned on the user profile, Auth0 recommends that you explicitly disable the GROUPS variable in the AD/LDAP Connector configuration file.

If the CPU utilization on the machine hosting the AD/LDAP Connector is consistently high (for example, sustained utilization above 60%), there are several mitigation strategies.

Uninstall any non-critical services on the host machine that may be consuming CPU cycles.

If you do not require groups to be returned on the user profile, disable group import as described in Authentication requests take too long to process.

If you do require groups to be returned on the user profile, investigate the groups being returned on the Auth0 user profiles. Queries against nested and recursive groups can cause high CPU utilization. If possible, test with group import disabled to assess the impact of the group queries.

To mitigate the impact, fix any recursive or otherwise problematic group assignments in your AD/LDAP server, and/or increase the value of the GROUPS_CACHE_SECONDS variable in the AD/LDAP Connector configuration file.

Check if the number of active users using the AD/LDAP Connector has increased since you initially deployed it. You can evaluate this by using your own monitoring solution, or you can get an estimate from the Auth0 active users report.

If the number of active users has increased, and all steps above have already been followed, you may need to upgrade your host machine’s hardware specifications, or configure a High Availability environment.

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.

To learn how to synchronize your Active Directory environment with an external time server, read How to configure NTP server in Active Directory, Step by step on renanrodrigues.com.

If you are unsure if your server's clock is in sync with NTP, go to 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 (1) second difference between them.

The AD/LDAP Connector must be installed on a server that can reach your LDAP server. When firewalls and VPN connections are placed between the AD/LDAP Connector and the LDAP server, you may experience connectivity issues.

If you’re configuring a Windows Network with Active Directory, use the nltest command. For example, 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 to, use nltest /dsgetdc:.

If a domain does not exist or cannot be reached, 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 AD/LDAP 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 set an HTTP_PROXY system environment variable, or you can set the HTTP_PROXY variable in the AD/LDAP Connector configuration file. If using an authenticated proxy, the URL must be in the format http://USERNAME:PASSWORD@SERVER_URL:PORT.

The HTTP_PROXY URL must be the URL of the proxy itself and cannot point to a .pac (auto-config) file. 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 errors, such as Auth0 servers not reachable and SELF_SIGNED_CERT_IN_CHAIN errors.

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

Ensure that your server can connect to your Auth0 tenant (https://{yourDomain}).

To verify this, open a browser and navigate to https://{yourDomain}/test.

The Service account used to configure the AD/LDAP Connector must have read permissions on the AD/LDAP server, and must be capable of querying groups for users.

To enable verbose logging of Kerberos requests:

1. Add DEBUG=kerberos-server as a system environment variable.

2. Restart the AD/LDAP Connector.

3. Log in.

4. Check the logs for more information.

If you have Kerberos enabled, but your users are being prompted for username/password, verify that the IP address setting is properly configured. For more information, see Configure AD/LDAP Connector Authentication with Kerberos.

The AD/LDAP Connector uses two levels of configurable caching:

1. Auth0 server: Caches both the user’s credentials and their profile.

2. AD/LDAP Connector: Caches a user’s group memberships.

The configuration of these settings determines the immediacy that changes in your directory may be reflected in a user’s profile when they log in to your application(s). In some AD/LDAP installations, user attributes synchronization may take a few minutes.

The Auth0 server caches the user’s last successfully authenticated profile, including a hash of their username and password. 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 during a network outage. It is only activated if the AD/LDAP Connector or the AD/LDAP server(s) are unavailable.

The AD/LDAP Connector caches a user’s group memberships. This cache’s lifetime is determined by the GROUPS_CACHE_SECONDS variable in the AD/LDAP Connector configuration file, with a default value of 600 (seconds).

The purpose of this second-level cache is to minimize execution time. By default, the AD/LDAP Connector retrieves all group membership of a user recursively, which can be an expensive process in some AD/LDAP installations. This cache is deleted every time you restart the AD/LDAP Connector.

To avoid the requirement of an open inbound port in your servers, the AD/LDAP 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 per day (though the frequency may vary under certain circumstances), each server node terminates the connection to allow internal deployment processes to occur. The AD/LDAP Connector detects the closed connection and terminates 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. Go to Auth0 Dashboard > Authentication > Enterprise, and select the Active Directory/LDAP connection type.

2. Select your AD/LDAP connection.

3. Switch to the Applications view, and enable the connection for the desired application(s).

4. Select Save.

You may encounter this error if you have not completed additional configuration for a custom domain.

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. Open the AD/LDAP Connector configuration file.

2. Set the PROVISIONING_TICKET configuration variable to https://{yourDomain}/p/ad/jUG0dN0R.

3. Restart the AD/LDAP Connector.

If you receive the UNABLE_TO_GET_ISSUER_CERT_LOCALLY error after configuring an AD/LDAP Connector, the Certificate Authority could be missing from your machine.

• If your tenant is in the public cloud environment, verify that you have the ISRG Root X1 certificate in your Trusted Store on the machine with the installed AD/LDAP Connector.

• If you are on the converged platform environment, add the ISRG Root X2 certificate to the Trusted Store on the machine with the installed AD/LDAP Connector.

If you are configuring a High Availability environment and are encountering this error on an additional machine, verify that the Trusted Root Certificate Authorities on the additional machine matches the Trusted Root Certificate Authorities on the initial machine.

If you are unable to resolve any of these issues on your own, contact Auth0 Support.

To help the Support team troubleshoot your issue, include the following items in your support ticket:

1. Description of the issue.

2. An export of your AD/LDAP configuration files.

3. A copy of the service log file(s):

   • Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\logs.log

   • Linux: /var/log/auth0-adldap.log

4. The version number of your AD/LDAP Connector.

   

• 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