How to verify/debug LDAP authentication?

I have enabled LDAP authentication for my MATLAB Web App Server. The server can start successfully but I couldn't log in. What is wrong?

Answer 1

[MathWorks Support Team]

Since the server can start, just logging in fails. The syntax of your webapps_authn.json file is correct. 

To find out if the log-in failure is caused by web app server or your LDAP configuration in the webapps_authn.json file, you can use below third party tools to verify the LDAP parameters. These tools can also be used to get the attributes of the person who is going to log into the web app server. The attributes values are useful for further investigation if needed.

We are going to use below snippet of webapps_authn.json file as an example to illustrate the tools. The user's account name that will log into the web app server is JSmith. The port is not specified, so by default, the server uses the standard port 636 for SSL on Windows and port 389 for STARTTLS on Linux and macOS (see port from 

Authentication Documentation

 for more details).

"authnConfig": {
        "host": "ad.mathworks.com",
        "port": "",
        "searcherDN": "CN=admin,DC=ad,DC=mathworks,DC=com",
        "searcherPassword": "xxx",
        "baseDN": "DC=ad,DC=mathworks,DC=com",
        "userFilter": "(&(objectClass=User)(sAMAccountName={username}))"
    },

Linux

For a Linux machine, you can use ldapsearch command line tool. The corresponding ldapsearch example command is provided below. Please note, the {username} in the "userFilter" is replaced with the real user's account name (JSmith) who will log into the web app server. In addition, the "-d 5" flag will return the ldapsearch’s debug information. It will help identify the causes if ldapsearch command doesn’t work.

ldapsearch -x -H ldap://ad.mathworks.com -D "CN=admin,DC=ad,DC=mathworks,DC=com" -W -b "DC=ad,DC=mathworks,DC=com" "(&(objectClass=User)(sAMAccountName=JSmith))" -ZZ -d 5

-H: "host"

-D: "searcherDN"

-W: The command will prompt for "searchPassword"

-b: "baseDN"

"userFilter" is attached to the end.

-ZZ: Issue StartTLS (Transport Layer Security) extended operation

-d 5: return debug information

The entered username (e.g., JSmith in the ldapsearch above) during login is represented as {username} in the userFilter.

If your LDAP server supports anonymous binding and you are using empty ("") values for searcherDN and searcherPassword, please omit the -D and -W flags from your ldapsearch command.

Please note that the above command is different from the following ldapsearch command, which uses LDAPS:

ldapsearch -x -H ldap://ad.mathworks.com -D "CN=admin,DC=ad,DC=mathworks,DC=com" -W -b "DC=ad,DC=mathworks,DC=com" "(&(objectClass=User)(sAMAccountName=JSmith))" -ZZ -d 5

LDAPS is the non-standardized "LDAP over SSL" protocol, in contrast with StartTLS. Please make sure you use the correct ldapsearch command with the -ZZ flag.

 

Windows

For a Windows machine, you can use the tool ldp.exe. If it is already installed, from the Start menu, click Run, type ldp and then click OK. If it is not installed, follow this instruction to install. For example, for Windows 10 Version 1809 and Higher:

As of Windows 10 1809, RSAT is no longer installed using the installer from Microsoft, it is now available as a feature. Use these steps to install it.

1. Right-click the Start button and choose “Settings” > “Apps” > “Manage optional features” > “Add feature“.
2. Select “RSAT: Active Directory Domain Services and Lightweight Directory Tools“.
3. Select “Install“, then wait while Windows installs the feature. It should eventually appear as an option under “Start” > “Windows Administrative Tools“.

For Windows 11.

1. Right-click on the Start icon, then click Settings. Now select System > Optional Features.
2. To add an optional feature, select View Features button on the top.
3.  On the Add an optional feature window, type “RSAT” and click Search.
4. Select “RSAT: Active Directory Domain Services and Lightweight Directory Tools“ and install.

To use ldp.exe, 

1. Open Connection > Connect. Put "host" value from the webapps_authn.json file to the Server box and "port" to Port.
2. If you are not using anonymous binding, open Connection > Bind. Put "searcherDN" value from the webapps_authn.json file to the User box and "searcherPassword" to Password. Skip to Step 3 if you have empty values for searcherDN and searcherPassword. You are now ready to proceed to search the LDAP directory.
3. Go to Browse > Search. Put "baseDN" value from the webapps_authn.json file to the Base DN box and "userFilter" to Filter. Click Run.

Please note, the {username} in the "userFilter" is replaced with the real user's account name (JSmith) who will log into the web app server.

Below screen shots show the corresponding input for the above webapps_authn.json file.

Search Result

A successful search will return the attribute values of the entry (JSmith). Below shows a return example. Please note your entry result might have different attribute values.

CN=JSmith,OU=Users,DC=ad,DC=mathworks,DC=com
accountExpires: 0 (never);
c: US;
cn: JSmith;
co: United States;
company: MathWorks, Inc.;
countryCode: 840; 
...

If you get a successful search result and you still couldn't log in. Please contact MathWorks Support and share your webapps_authn.json file, Web App Server log file, and your ldapsearch/ldp.exe search command and result.

If you cannot get a successful search result, please try to work with your LDAP admin to get the right settings first.