Troubleshooting the Active Directory/LDAP Connector
We do our best to support many scenarios and different configurations.
Unfortunately some issues are very hard to predict. Especially those that happen behind our customer's firewall. We have less control over that environment, and the related infrastructure dependencies (such as network, proxies, OS versions, and so on).
If you are experiencing problems with the connector, please open a support ticket with the following information:
- Symptoms, explain your problem
- Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\config.json
- Linux: /opt/auth0-adldap/config.json
- the service log files from:
- Windows: C:\Program Files (x86)\Auth0\AD LDAP Connector\logs.log
- Linux: /var/log/auth0-adldap.log
These logs are not accessible to us directly.
It is usually a good idea to keep the connector up to date. You can check the version of the installed connector on the Dashboard:
Troubleshooting in the Admin Console
The Troubleshooting section in the Admin Console will show the logs for the AD/LDAP Connector:
The Run button on the Troubleshooting page will run the troubleshooting tool to detect the most common problems related to the AD/LDAP Connector.
The Export button will create a .zip file containing the
config.json file, the
lib\\profileMapper.js file, the
certs folder and the output of the troubleshooting tool. Send this troubleshooting package to us by opening a support ticket if you're experiencing problems with the connector.
The troubleshooting tool is part of the AD LDAP Connector and can be launched on Windows using C:\Program Files (x86)\Auth0\AD LDAP Connector\troubleshoot.cmd or on Linux using node troubleshoot.js.
This tool will try to detect the most common problems related to the AD/LDAP Connector:
These are the most common problems:
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 that the System is properly configured to use to poll a sync server via the NTP (Network Time Protocol).
No connection to Active Directory
The connector should be installed on a server that can reach the LDAP server. When firewalls, VPN connections, ... are placed between the connector and the LDAP server this might lead to connectivity issues between the connector and the LDAP server.
In a Windows Network with Active Directory you can try the
nltest command. To test if a specific machine can reach the
fabrikam.local domain you can try
To see to which domain the current server is connected you can also try: `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
UNABLE_TO_VERIFY_LEAF_SIGNATURE error message
This error applies to the AD/LDAP Connector in combination with the Private Cloud.
When the connector will fail to start if unable to 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 you should import the certificate chain in the Local Machine > Trusted Root certificate store on the machine where the AD/LDAP Connector is installed.
Running the connector behind a proxy
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_PROXY URL 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, you must 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_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.
No internet connectivity
https://YOUR_DOMAIN should be reachable from the server.
A quick test for this is to open a browser pointing to https://YOUR_DOMAIN/test.
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 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.
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 few minutes too.
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, make sure you enable the cache for the connection.
Receive a "postUrl is required" error
This is usually thrown if additional configuration for custom domains have not been made. See the custom domains documentation for more info.