Overview

The Auth0 Active Directory (AD)/Lightweight Directory Access Protocol (LDAP) Connector must maintain stable connections to both the LDAP server and the Auth0 service to authenticate users correctly. When issues arise, the troubleshooting areas covered include running the built-in troubleshooting tool, resolving installation and configuration test failures, and diagnosing common issues such as clock skew, proxy misconfiguration, certificate errors, and caching behavior.

Applies To

• Auth0
• AD/LDAP Connector
• Enterprise Identity Providers
• Active Directory
• Private Cloud

Solution

How to Run the AD/LDAP Connector Troubleshooting Tool

The troubleshooting tool is available inside the AD/LDAP Connector Admin Console or can be launched manually outside of it. To detect issues with certificates, set the CONNECTIONS_API_V2_KEY variable in the AD/LDAP Connector configuration file before running the tool.

Running the Tool Inside the Admin Console

Switch to the Troubleshooting view, then select Run to detect the most common problems with the AD/LDAP Connector.

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.

Running the Tool Outside the Admin Console

Windows

Locate the AD/LDAP Connector folder and run the troubleshoot.cmd 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

Linux

Open a terminal, navigate to the AD/LDAP Connector folder, and run the Node.js troubleshooting program to launch the tool.

1. Open a new terminal window.
2. Change the working directory to the AD/LDAP Connector folder (AD LDAP Connector).
3. Run the following command:

   node troubleshoot.js

Installation and Configuration Test Results

After selecting Save, the AD/LDAP Connector Admin Console performs a series of tests to validate the provided information. Results appear 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 any firewall settings that might prevent the connection.
• Test 2: Attempts to perform an LDAP bind on the LDAP server and port specified using 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 username's privileges 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

Authentication Requests Take Too Long to Process

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 authentication process duration.

If groups are not required on the user profile, explicitly disable the GROUPS variable in the AD/LDAP Connector configuration file.

High Host CPU Utilization Requires Mitigation

If CPU utilization on the machine hosting the AD/LDAP Connector is consistently high (for example, sustained utilization above 60%), apply one or more of the following mitigation strategies.

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

• Modify Group Import Configuration
  • If groups are not required on the user profile, disable group import as described in the Authentication Requests Take Too Long to Process section above.
  • If groups are required on the user profile, investigate which groups are returned for the Auth0 user profile. Queries against nested and recursive groups can cause high CPU utilization. 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 the AD/LDAP server, and/or increase the value of the GROUPS_CACHE_SECONDS variable in the AD/LDAP Connector configuration file.

• Evaluate the Volume of Active Users
  • Check whether the number of active users using the AD/LDAP Connector has increased since initial deployment. Evaluate this using a monitoring solution or by reviewing the Auth0 active users report.
    • NOTE: In Microsoft Windows Server environments, Microsoft System Center Operations Manager (SCOM) can be configured to monitor and alert on the AD/LDAP Connector service status. For more information, see Monitor AD/LDAP Connector with System Center Operations Manager.
  • If the number of active users has increased and all mitigation strategies outlined above have been implemented, upgrade the host machine's hardware or configure a High Availability environment.

Clock Skew Causes Authentication Failures

The AD/LDAP Connector requires the server clock to be synchronized with the Auth0 service. The maximum allowed threshold is 5 seconds. Clock skew produces output similar to the following 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

Ensure the server clock is current. An incorrect clock causes authentication requests to fail. Configure the system to poll a sync server via the Network Time Protocol (NTP). In Windows environments, the NTP provider is usually the same domain controller. Ensure that the domain controller is synchronized with an external service.

To learn how to synchronize an Active Directory environment with an external time server, read How to configure an authoritative time server in Windows Server.

To verify whether the server clock is in sync with NTP, go to the National Institute of Standards and Technology page and compare the time displayed with the time on the server running the connector. The difference should not exceed one second.

No Connection to Active Directory

The AD/LDAP Connector must be installed on a server that can reach the LDAP server. Firewalls and VPN connections placed between the AD/LDAP Connector and the LDAP server may cause connectivity issues.

When configuring a Windows Network with Active Directory, use the nltest command. For example, to test whether a specific machine can reach the fabrikam.local domain, run:

nltest /dsgetdc:fabrikam.local

To see which domain the current server is connected to, run:

nltest /dsgetdc:

If a domain does not exist or cannot be reached, nltest returns the following error:

Getting DC name failed: Status = 1355 0x54b ERROR_NO_SUCH_DOMAIN

How is the UNABLE_TO_VERIFY_LEAF_SIGNATURE error resolved in Auth0?

The following error applies to the AD/LDAP Connector in combination with Private Cloud.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

Auth0 generates this error when the AD/LDAP Connector fails to start because it cannot validate the SSL certificate configured in the Private Cloud. This can occur when the Root Certificate or any Intermediate Certificates are missing from the machine's Certificate Store (Windows).

To resolve the issue, import the certificate chain into the Local Machine > Trusted Root certificate store on the machine where the AD/LDAP Connector is installed.

Connector Behind a Proxy Requires Additional Configuration

If the machine hosting the connector is behind a proxy, set an HTTP_PROXY system environment variable or set the HTTP_PROXY variable in the AD/LDAP Connector configuration file. If using an authenticated proxy, the URL must follow this format:

http://USERNAME:PASSWORD@SERVER_URL:PORT

• NOTE: After setting system environment variables or modifying the AD/LDAP Connector configuration file, restart the AD/LDAP Connector for the changes to take effect.

The HTTP_PROXY URL must be the URL of the proxy itself and cannot point to a .pac (auto-config) file. If the proxy is configured through a .pac file, download the .pac file and locate the proxy URL within it.

An incorrectly configured proxy can result in errors such as Auth0 servers not reachable and SELF_SIGNED_CERT_IN_CHAIN. If a proxy URL has been configured and the AD/LDAP Connector has been restarted but SELF_SIGNED_CERT_IN_CHAIN errors persist, confirm that the server trusts the root certificate of the proxy. On a Windows machine, open certmgr.msc and look for the proxy's certificate. To learn more, read Proxy Auto-Configuration (PAC) file.

No Internet Connectivity Prevents Auth0 Tenant Access

Ensure that the server can connect to the Auth0 tenant (https://{exampleDomain}). To verify connectivity, open a browser and navigate to:

https://{exampleDomain}/test

Service Account Permissions Must Include Read Access

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.

Kerberos Issues Require Verbose Logging to Diagnose

Enable verbose logging, restart the connector, sign in, and review the logs to diagnose Kerberos request issues.

1. Add DEBUG=kerberos-server as a system environment variable.
2. Restart the AD/LDAP Connector.
3. Sign in.
4. Check the logs for more information.

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

Changes in Active Directory User Profiles Are Not Immediately Reflected in the Application

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 how quickly changes in the directory are reflected in a user's profile when they sign in to the application(s). In some AD/LDAP installations, user attribute synchronization may take a few minutes.

• Caching on the Auth0 Server
  • The Auth0 server caches the user's last successfully authenticated profile, including a hash of their username and password. This cache is enabled by default and can be disabled. Its purpose is to maximize the availability of authentication transactions when Active Directory is unavailable, for example, during a network outage. Auth0 activates this cache only if the AD/LDAP Connector or the AD/LDAP server(s) are unavailable.
• Caching in the AD/LDAP Connector
  • The AD/LDAP Connector caches a user's group memberships. The cache 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 cache is to minimize execution time. By default, the AD/LDAP Connector retrieves all a user's group memberships recursively, which can be an expensive operation in some AD/LDAP installations. This cache is deleted every time the AD/LDAP Connector restarts.

The Connector Restarts After an "auth0: Connection closed." Log Message

To avoid requiring an open inbound port on the server, the AD/LDAP Connector creates a WebSocket connection to an available node in Auth0's server cluster and keeps it open to listen for incoming messages from Auth0. Approximately once per day (though the frequency may vary), each server node terminates the connection to allow internal deployment processes to occur. The AD/LDAP Connector detects the closed connection, terminates the process, and allows the service stack to restart the process, create a new connection to an available node, and resume operations.

To avoid downtime, enable the cache by navigating to the Auth0 Dashboard > Authentication > Enterprise, selecting the Active Directory/LDAP connection, enabling the connection for the desired applications on the Applications view, and saving the changes.

1. Go to Auth0 Dashboard > Authentication > Enterprise, and select the Active Directory/LDAP connection type.
2. Select the AD/LDAP connection.
3. Switch to the Applications view, and enable the connection for the desired application(s).
4. Select Save.

How is the postUrl is required error resolved in Auth0?

The following error may occur when additional configuration for a custom domain has not been completed.

postUrl is required

To use AD/LDAP connections with Kerberos support, update the Ticket endpoint to work with the custom domain by opening the configuration file, setting the PROVISIONING_TICKET variable, and restarting the connector.

1. Open the AD/LDAP Connector configuration file.
2. Set the PROVISIONING_TICKET configuration variable to:

   https://{exampleDomain}/p/ad/jUG0dN0R

3. Restart the AD/LDAP Connector.

How is the UNABLE_TO_GET_ISSUER_CERT_LOCALLY error resolved in Auth0?

If the following error appears after configuring an AD/LDAP Connector, the Certificate Authority may be missing from the machine.

UNABLE_TO_GET_ISSUER_CERT_LOCALLY

To resolve this error, check the following:

• If the tenant is in the public cloud environment, verify that the ISRG Root X1 certificate is present in the Trusted Store on the machine with the installed AD/LDAP Connector.
• If the tenant is 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 configuring a High Availability environment and this error appears on an additional machine, verify that the Trusted Root Certificate Authorities on the additional machine match those on the initial machine.

Contact Auth0 Support

If the issues above cannot be resolved independently, contact Auth0 Support. Include the following items in the support ticket to help the Support team troubleshoot the issue:

1. A description of the issue.
2. An export of the 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 the AD/LDAP Connector.

Related References

• 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