This section describes how to diagnose and resolve some common problems with configuring external authentication for LDAP.

Planning for Troubleshooting

If you have problems configuring external authentication for LDAP, first make sure that you have configured logging and located the files you need to diagnose and resolve the issue. If you need to contact Jaspersoft technical support, they will ask you for this information:

"Invalid Credentials Supplied" Errors

One common error you will see when trying to log in to JasperReports Server is an invalid credential error, with the following message:

This error can be misleading, because it can come from a wide range of root causes, including problems that are not directly related to the credentials used. These include:

Problems Communicating with the LDAP Server

If you receive an invalid credentials error, the first thing to check for is errors connecting to the LDAP server. Search the jasperserver.log file for any stack trace containing the following:

If you see this in the logs, you need to dig a little further to find the cause of the communication exception.

Incorrect Connection URL

Problem

If the URL for the LDAP server is incorrect in applicationContext-externalAuth.xml, you will see an error such as the following:

Solution

To fix this error, locate the following lines in applicationContext-externalAuth.xml and verify that myLDAPServer is correct hostname for your LDAP server and that and port is your LDAP server port:

    [/code]                    

Edit this information to point to the correct server and port.

Timeout Errors

Problem

If the connection is timing out while trying to talk to the LDAP server, you will see a "Connection timed out" error in the log, such as:

Solution

To fix this error, ensure that the LDAP server is reachable from the server that is hosting JasperReports Server. Possible causes for connectivity problems include (but are not limited to): firewalls, anti-virus software, or an incorrectly configured DMZ.

Problems with User Search

"Invalid credentials supplied" errors are frequently caused by problems with the way user search is configured.

Unable to Find an LDAP Branch

Problem

If JasperReports Server can’t find the user because you have not configured the server to communicate with an existing branch within LDAP, you may see an "Invalid search base" error in jasperserver.log. For example:

Solution

To resolve this, check with your LDAP admin that the search base you are using exists within your LDAP directory. The search base is usually specified in the <constructor-arg index="0"> parameter in the userSearch bean in applicationContext-externalAuth.xml.

Incorrect or Missing Partition

Problem

If JasperReports Server can’t find the user because the search is not configured to look in the correct partition, you may see a "Cannot find a partition" error in jasperserver.log, for example:

Solution

This error can arise if you are importing your LDIF file. In this case, the partitions may not be created automatically, and therefore are not searchable. Check the LDAP connection URL in the ldapContextSource bean in applicationContext-externalAuth.xml. If the partition is not present, you can append it to the bean.

Invalid Search Filter

Problem

If the search filter is not constructed correctly in your applicationContext-externalAuth.xml file your connection will fail. This error can be tricky because it does not always give an error code in the log. Instead, the query is valid, but when it searches your LDAP directory, it simply returns nothing:

Solution

If you suspect the search filter might be invalid, run the query in a third-party LDAP client and see if it returns any users. If the query does not return any users, correct the query to retrieve the users you want, then update your applicationContext-externalAuth.xml file with the correct query.

Failure to Bind the User

Problem

In some cases, the user is found, but the bind process fails. You might see an error in the logs such as the following:

Solution

A common reason for this is because of a mismatch in the DN format between what you specify in your search query versus what is acceptable for your specific version of LDAP. The precise solution depends on the implementation and configuration of your LDAP server. For more information, please consult documentation for your LDAP solution.

User Not Found By Valid Search Filter

Problem

A valid search filter that runs and returns results may not find all intended users. In this case you will see the same failed authentication message in the log as you would for an unauthorized user:

Solution

This can happen for a number of causes. One of the most common is that the search filter is valid but is not returning the set of users you want. You could have misconfigured your query or you could be pointing to the wrong query in your applicationContext-externalAuth.xml file. Test the query shown in the log by running it in a third-party LDAP client and see if it returns the missing user.

To fix an incorrect query, look for the search filter in the applicationContext-externalAuth.xml file. Search filters are declared in the ldapAuthenticationManager bean, and the filter definition containing the query string is defined later in the same file. Check to make sure the search string is correct and that ldapAuthenticationManager is pointing to the correct search filter.

Login Page Not Loading

Another common symptom with multiple causes is failure to load the login page.

A blank page is shown instead.

Invalid Application Context File

Problem

If your application context file, applicationContext-externalAuth.xml, is not a valid XML file, the login page does not load. You may see a stack trace in the logs, specifying the invalid file:

Solution

Usually the stack trace shows the name of the invalid file, the location in the file that is causing the problem, and the error that triggered the stack trace. The resolution depends on the error. In some cases, the location in the stack trace will not be the location of the root problem in the file.

In the example above, there is a missing ending tag for property. To fix this, add the tag at the location specified by <lineNumber> and <columnNumber>.

XML Special Characters in Role Names

Problem

Role names can't contain certain special characters, including the XML reserved characters <, >, &, ', ", and . If you use a reserved character in a role name in your XML file, JasperReports Server attempts to interpret it as XML, which results in a stack trace. The precise error depends on the special character. For example, if you use an ampersand (&) in a role name, you see an error like this:

Solution

In general, it is safest to restrict role names to alpha-numeric characters. If extended characters are necessary for your naming convention, choose non-reserved characters.

Missing Bean Definition

Problem

Jasper is trying to read a bean definition that doesn’t exist. In the error message, you see reference to the <type of bean>, which typically refers to the actual java class name for that bean definition. The bean name in the applicationContext-externalAuth.xml file may appear later in the error:

Solution

Check the following:

Missing Java Class

Problem

JasperReports Server can't find a Java class referenced in the XML file. The stack trace shows the name of the class:

Solution

Check the following:

Login Displays Security Check Page

Problem

JasperReports Server displays the j_spring_security_check page:

In the jasperserver.log, look for DefaultLdapAuthoritiesPopulator and problems locating roles:

Solution

Errors with DefaultLdapAuthoritiesPopulator indicate that no roles could be found for this user. As part of the login process, the user is both authenticated and authorized. JasperReports Server uses LDAP and DefaultLdapAuthoritiesPopulator to determine which roles to assign to the user. A user needs at least ROLE_USER to log in. If no roles are assigned to the user, the login fails as above.

Ensure that you've configured role search correctly in the JSDefaultLdapAuthoritiesPopulator bean in your LDAP file. Make sure that it is using the correct branch in your LDAP.