LDAP Debugging Guide

Patrick Russell
2019-08-14 23:20

LDAP Debugging Guide

LDAP (Lightweight Directory Access Protocol) offers a REST API-style method of authenticating users. In Artifactory, this means that almost every time a user uses their LDAP credentials, the application will check the LDAP server for authentication.

This is useful as it allows for dynamic Group synchronization. For example, if a user changes LDAP groups, Artifactory will automatically update its own Group listing to reflect the change.

For more information on LDAP Group Synchronizations, check out this related KnowledgeBase article.

LDAP Setup Requirements:

All LDAP connections need to have the following parameters specified. The exact values are usually kept in the LDAP server configuration.

The LDAP URL 
Example: ldap://example.com/dc=jfrog,dc=org

This URL uses the "ldap" or "ldaps" protocol (The "s" stands for "secure" and uses SSL encryption). The "dc" Directory Components section translates to an organization's top level LDAP coordinates. In the above example this is "jfrog.org".

The Search Filter or User DN Pattern 
Example Search Filter: samAccountName={0}
Example User DN Pattern: uid={0},ou=people

This is how Artifactory searches for users in the LDAP system. The "{0}" is filled in with the username submitted. Either the Search Filter or User DN Pattern can be used, at least one needs to be configured.

LDAP Manager credentials
Example: cn=admin,dc=example,dc=com 

While not strictly required, most LDAP servers require authentication to look up directory information.In LDAP, this takes the form of LDAP Coordinates to a username as well as a password.

Troubleshooting LDAP problems

Search Base Problems
Many times, the Search Base field is used incorrectly when the system is being set up for the first time. The Search Base limits the LDAP directories Artifactory will look for users in. 

If the Search Base is too broad, the search will take a long time and cause timeouts. If it is too specific, users with LDAP coordinates outside of the search base will not be able to log in.

The LDAP debug loggers record a user's LDAP coordinates when they log in. You can use this information to tune the parameter accordingly. 

If there are specific LDAP directories where users are located, one thing to try is to use multiple LDAP settings in Artifactory. These settings can share the same LDAP URL and other information, but have completely different Search Bases. 

Networking Issues
If the LDAP connection test button fails with a networking error, this is usually caused by the LDAP URL. 

The "ldaps" protocol is particularly tricky. It uses SSL encryption, so the URL in use needs to match the certificate's Common Name.

The LDAP debug loggers will print any extra networking issues or information to the ldap.log file.

Another common issue is if networking failures cause a login to time out. This can cause an intermittent build failure problem. One way to solve this problem is to increase the login cache times. 

The setting can be found in the $ARTIFACTORY_HOME/etc/artifactory.system.properties file:

## Number of seconds for authentications to idle in the cache
artifactory.security.authentication.cache.idleTimeSecs=300

Locked User Issues
There are two possible states if an account is locked: Either the user attempting to log in failed to do so, and their LDAP account was locked, or the LDAP Manager's account was locked.

In order to run an LDAP Search, Artifactory uses credentials of an LDAP Manager. This access can sometimes be misconfigured or change, and cause the Manager account to be locked from the LDAP side.

If this happens, the error is printed fully when the LDAP debug logger is used. It can be used to determine if the user or Manager was locked out. Usually an LDAP Administrator is required to unlock either user account.

LDAP Debug loggers

In nearly all circumstances, the LDAP debug loggers for Artifactory are useful in determining the cause of a problem. This XML snippet goes in the $ARTIFACTORY_HOME/etc/logback.xml file and does not require a restart to take effect.

Please keep in mind that with the logger in place, security information such as LDAP coordinates (Not passwords) are logged in plaintext. There is also a slight performance hit to log this extra information. Once debugging is complete, you should remove the logger.

   <appender name="ldap" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <File>${artifactory.home}/logs/ldap.log</File>
      <encoder>
         <pattern>%date ${artifactory.contextId}[%thread] [%-5p] (%-20c{3}:%L) – %m%n</pattern>
      </encoder>
      <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
         <FileNamePattern>${artifactory.home}/logs/ldap.%i.log</FileNamePattern>
         <maxIndex>13</maxIndex>
      </rollingPolicy>
      <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
         <MaxFileSize>10MB</MaxFileSize>
      </triggeringPolicy>
   </appender>

   <logger name="org.springframework.security.ldap" additivity="false">
      <level value="trace" />
      <appender-ref ref="ldap" />
   </logger>
   <logger name="org.artifactory.addon.ldap" additivity="false">
      <level value="trace" />
      <appender-ref ref="ldap" />
   </logger>
   <logger name="org.artifactory.security.ldap" additivity="false">
      <level value="trace" />
      <appender-ref ref="ldap" />
   </logger>
   <logger name="org.artifactory.webapp.servlet.AccessFilter" additivity="false">
      <level value="trace" />
      <appender-ref ref="ldap" />
   </logger>

When applied, an "ldap.log" file will appear in the $ARTIFACTORY_HOME/logs/ folder.