User Directory Debugging

Common Issues

The most common reasons for LDAP or Microsoft Active Directory (AD) issues:

  • Account information for connecting to a directory service isn't correct.
  • Users assumed to be in a DN don't exist.
  • Lookup fields such as mail or userID aren't correctly populated.
  • The sub-tree of a DN isn't searchable.
  • Required fields such as First Name, Last Name and Email are missing.

Enterprise-on-Premises (EOP) customers configuring an LDAP service or AD may also run into setup and configuration issues, which you can resolve by logging configuration guidance.

AD and LDAP Configurations

Configuring a directory service can be challenging for Contrast administrators. As noted in the configuration guide, there are many pieces of information needed for basic connectivity, as well as dependencies for configuration. Many customers find this administrative task to be the most challenging part of Contrast setup.

Debug a directory service setup

Before starting the debugging process, review the article on logging to get up to speed on changing the log configuration and levels.

Turning on additional logging about directory services is a simple, one-line change to the log4j2.xml file located in $CONTRAST_HOME/data/conf directory. Change directories through a Unix command prompt or Windows Explorer window. You can edit the file in real-time, and shouldn't have to restart Contrast. Locate the section referrencing Logger, and add the line below. Contrast picks up the change and begin writing log messages to the contrast.log.

<Logger name="com.aspectsecurity.contrast.teamserver.service.ldap" level="TRACE"></Logger>

Review log messages

Once the setting takes effect, Contrast begins sending directory service log messages to the contrast.log file. Contrast recommends that you walk through the configuration of either LDAP or AD as a SuperAdmin after this setting is added.

User Missing from Directory


If you added a user to a Microsoft Active Directory (AD) or LDAP group, but Contrast says that they can't be found during configuration, you might have added them to both the User and SuperAdmin groups in your AD or LDAP instance. (Reminder: This is not allowed.)


After you choose one group for the user and remove them from the other in your AD or LDAP instance, go back to the Contrast interface. If you chose to keep the user in the SuperAdmin group, Contrast automatically adds them as a SuperAdmin-level user in the Contrast interface but doesn't assign them to any Organization Role or Application Access Groups. If you chose to keep the user in the User group, you must go through the steps to add a user in Contrast.

To learn more about configuring these authentication methods, go to the Authentication page.

Single Sign-On Connectivity


You might run into an issue connecting to your identity provider, if you're using a metadata URL with an HTTPS certificate from an unsupported authority, such as a self-signed certificate.


To resolve the issue, configure SSO by unchecking I have access to the metadata URL and pasting the metadata XML for the IDP into the text box.

Two-Step Verification

Backup Methods

If you've implemented two-step verification, but haven't successfully received a verification code through the method you chose, you can click the Can't Sign In? link in Step Two of the login process. Contrast will then email a temporary code to you, which is valid for five minutes. You can also use a backup code.

If email is already the chosen notification method, contact your Administrator to investigate potential issues with email settings.

Reset Your Device

If you're having issues with Google Authenticator, you manually reset your device by clicking the Reset Device link in User Settings. This clears all data for the current device and requires resetting Google Authenticator on the same or a new device.

Rotate Service Keys

Connection Issues After Rotating Keys

Enterprise-on-Premises (EOP) administrators who are responsible for installation, configuration and administration of both the Contrast interface and Crawler may have connection issues when rotating the service key associated with the SuperAdmin account. The service key only needs to be modified within the Crawler configuration if the service key is rotated by Contrast.

Restore Connection

When customers rotate their API Service Key, and one or more Crawlers have been configured, the configuration located in the $CRAWLER_HOME/conf/ file must change. Specifically, the Service Key (apiAuthorization) and the API Key (apiKey) must change, as shown below.


The apiAuthorization is not stored in plain text. This value must be modified by concatenating the username and the service key, then performing a base64 encode operation: