Debugging

Connectivity

LdapRecord-Laravel comes with a built-in command to test connectivity to your LDAP servers. The exception message, error code, and diagnostic message are displayed after a failure to bind to your LDAP server.

To test your connectivity, run the following command:

php artisan ldap:test

Then, the following will be output:

Testing LDAP connection [default]...

+------------+------------+-----------------+-------------------------------------------------------------------------------------------------------------+---------------+
| Connection | Successful | Username        | Message                                                                                                     | Response Time |
+------------+------------+-----------------+-------------------------------------------------------------------------------------------------------------+---------------+
| default    | ✘ No       | [email protected]  | ldap_bind(): Unable to bind to server: Can't contact LDAP server. Error Code: [-1] Diagnostic Message: null | 5008.72ms     |
+------------+------------+-----------------+-------------------------------------------------------------------------------------------------------------+---------------+

The returned error codes and diagnostic messages can help you greatly when attempting to debug SSL and TLS connectivity issues.

TLS & SSL

TLS and SSL can be very tricky to get up and running. You will most likely have to place an ldap.conf file onto your local / production server to indicate that you would like to either bypass TLS / SSL certificate verification, or use a valid certificate that you have retrieved from your LDAP server.

This process is fully documented on the configuration documentation. It includes per operating system level instructions on where your ldap.conf file is located (or where it must be created), as well as what it must contain.

Detailed TLS Errors

A TLS failure can return Can't contact LDAP server with an empty diagnostic message. To see the underlying certificate error, add LDAP_OPT_DEBUG_LEVEL to your connection's existing options in config/ldap.php:

return [
    // ...

    'connections' => [
        'default' => [
            // ...

            'options' => [
                LDAP_OPT_DEBUG_LEVEL => 7,
            ],
        ],
    ],
];

If your configuration is cached, clear it before testing the connection again:

php artisan config:clear
php artisan ldap:test

The OpenLDAP client writes its debug output directly to standard error. It appears separately from the command's result table and may contain details that are missing from the diagnostic message. This option requires a PHP LDAP extension built with OpenLDAP support.

Use the reported error to check that:

• Your configured LDAP host matches a DNS name in the server certificate. For example, use dc01.example.com when the certificate identifies that host, rather than example.com.
• Your CA certificate file is readable by the PHP process and contains the certificates needed to trust the server's certificate chain.

For multiple CA certificates, LDAP_OPT_X_TLS_CACERTFILE can point to a PEM file containing the trusted CA certificates. If you use LDAP_OPT_X_TLS_CACERTDIR, OpenLDAP requires a certificate directory prepared with hashed filenames, such as those generated by openssl rehash.

Remove the debug option once you have resolved the connection issue. Keep certificate verification enabled for your application.

Directory and Objects

LdapRecord-Laravel comes with a built-in command to browse and navigate through your LDAP directories interactively.

To browse your directory, use the ldap:browse {connection} command:

php artisan ldap:browse

Logging In

To debug issues logging in, it's recommended to first complete the following steps:

1. Enabled logging via the logging key inside your config/ldap.php file
   (or by enabling it via your .env by using the LDAP_LOGGING key)
2. Clear your configurations cache (if enabled) by running the php artisan config:clear command
3. Add the ListensForLdapBindFailure trait onto your LoginController
4. Attempt logging in again

After completing the above, the first thing to lookout for is whether a red error message is being displayed underneath your username / email field.

If you do not see any error message and are immediately returned back to the login page, then you have likely changed the username field on your resources/views/auth/login.blade.php but have not updated it inside your LoginController, or vice versa.

For example, if you want users to login by a username instead of their email, make sure you've changed this via the username method, and the credentials method on your LoginController

// app/Http/Controllers/Auth/LoginController.php

use Illuminate\Http\Request;

public function username()
{
    // This is the name of the HTML 'input' inside
    // of our 'login.blade.php' view:
    return 'username';
}

protected function credentials(Request $request)
{
    // 'samaccountname' is the attribute we are using to
    // locate users in our LDAP directory with. The
    // value of the key must be the input name of
    // our HTML input, as shown above:
    return [
        'samaccountname' => $request->get('username'),
        'password' => $request->get('password'),
    ];
}

If you simply see an Invalid Credentials, or Can't contact LDAP server error, refer to your log files inside your applications storage/logs directory to investigate further. With logging enabled, all LDAP searches, binds, failures and exceptions will be reported there.