Adapters

LDAP Authentication

Laminas\Authentication\Adapter\Ldap supports web application authentication with LDAP services. Its features include username and domain name canonicalization, multi-domain authentication, and failover capabilities. It has been tested to work with Microsoft Active Directory and OpenLDAP, but it should also work with other LDAP service providers.

This documentation includes a guide on using Laminas\Authentication\Adapter\Ldap, an exploration of its API, an outline of the various available options, diagnostic information for troubleshooting authentication problems, and example options for both Active Directory and OpenLDAP servers.

Usage

The following example demonstrates creating and configuring the Ldap authentication adapter, and also illustrates how to work with the authentication messages returned in the authentication result.

use Laminas\Authentication\AuthenticationService;
use Laminas\Authentication\Adapter\Ldap as LdapAdapter;

// Retrieve the username and pasword from the request somehow.
$username = /* ... */;
$password = /* ... */;

$auth = new AuthenticationService();

$config = [
    'server1' => [
        'host'                   => 's0.foo.net',
        'accountDomainName'      => 'foo.net',
        'accountDomainNameShort' => 'FOO',
        'accountCanonicalForm'   => 3,
        'username'               => 'CN=user1,DC=foo,DC=net',
        'password'               => 'pass1',
        'baseDn'                 => 'OU=Sales,DC=foo,DC=net',
        'bindRequiresDn'         => true,
    ],
    'server2' => [
        'host'                   => 'dc1.w.net',
        'useStartTls'            => true,
        'accountDomainName'      => 'w.net',
        'accountDomainNameShort' => 'W',
        'accountCanonicalForm'   => 3,
        'baseDn'                 => 'CN=Users,DC=w,DC=net',
    ],
];

$adapter = new LdapAdapter($config, $username, $password);

$result = $auth->authenticate($adapter);

// Messages from position 2 and up are informational messages from the LDAP
// server:
foreach ($result->getMessages() as $i => $message) {
    if ($i < 2) {
        continue;
    }

    // Potentially log the $message
}

As noted in the above example, the returned authentication result contains messages even on success. LDAP has some notoriety for difficulty in debugging, and the Ldap adapter attempts to assist you with this by providing informational messages for every authentication attempt. A later section in this document provides more detail on the messages returned.

You will note that the configuration contains information for multiple servers. When multiple server configuration is provided, the adapter will loop through each until one provides successful authentication. The above configuration will instruct the adapter to attempt authentication against the OpenLDAP server s0.foo.net first, falling back to the Active Directory server dc1.w.neton failure.

With servers in different domains, this configuration illustrates multi-domain authentication. You can also have multiple servers in the same domain to provide redundancy.

Note that in this case, even though OpenLDAP has no need for the short NetBIOS style domain name used by Windows, we provide it here for name canonicalization purposes (described in the Username Canonicalization section below).

A later section on server options details all available options)

The API

The Laminas\Authentication\Adapter\Ldap constructor accepts three parameters.

The $options parameter is required and must be an array containing one or more sets of options. Note that it is an array of arrays, with each sub-array providing laminas-ldap options. Even if you will be using only one LDAP server, the options must still be within a sub-array.

Referring back to the example in the previous section, the information provided in each set of options is different mainly because Active Directory does not require a username be in DN form when binding (see the bindRequiresDn option in the Server Options section below), which means we can omit a number of options associated with retrieving the DN for a username being authenticated.

What is a Distinguished Name?

A DN or "distinguished name" is a string that represents the path to an object within the LDAP directory. Each comma-separated component is an attribute and value representing a node. The components are evaluated in reverse. For example, the user account CN=Bob Carter,CN=Users,DC=w,DC=net is located directly within the CN=Users,DC=w,DC=net container. This structure is best explored with an LDAP browser like the ADSI Edit MMC snap-in for Active Directory or phpLDAPadmin.

The names of servers (e.g. 'server1' and 'server2' shown above) are largely arbitrary and only used for informational purposes by the adapter. We recommend using string identifiers that omit any HTML/XML entity references to ensure they do not break any logging displays.

With multiple sets of server options, the adapter can authenticate users in multiple domains and provide failover so that if one server is not available, another will be queried.

The Gory Details: What Happens in the Authenticate Method?

When the authenticate() method is called, the adapter iterates over each set of server options, passes them to the internal Laminas\Ldap\Ldap instance, and calls the Laminas\Ldap\Ldap::bind() method with the username and password being authenticated.

Laminas\Ldap\Ldap checks to see if the username is qualified with a domain (e.g., has a domain component like alice@foo.net or FOO\alice). If a domain is present, but does not match either of the server's domain names (e.g., foo.net or FOO), a special exception is thrown and caught by Laminas\Authentication\Adapter\Ldap that causes that server to be ignored, and progression to the next server configured.

If a domain matches, or if the user did not supply a qualified username, Laminas\Ldap\Ldap proceeds to try to bind with the supplied credentials. if the bind is unsuccessful, Laminas\Ldap\Ldap throws a Laminas\Ldap\Exception\LdapException which is caught by Laminas\Authentication\Adapter\Ldap and, again, the adapter progresses to the next configured server.

If the bind is successful, server iteration stops, and the adapter's authenticate() method returns a successful result.

If all configured servers fail to authenticate, authenticate() returns a failure result with error messages from the last server consulted.

The username and password parameters of the Laminas\Authentication\Adapter\Ldap constructor represent the credentials being authenticated (i.e., the credentials supplied by the user through your HTML login form). Alternatively, they may also be set with the setUsername() and setPassword() methods.

Server Options

Each set of server options in the context of Laminas\Authentication\Adapter\Ldap consists of the following options, which are passed, largely unmodified, to Laminas\Ldap\Ldap::setOptions():

TLS and SSL

If you enable useStartTls = TRUE or useSsl = TRUE you may find that the LDAP client generates an error claiming that it cannot validate the server's certificate. Assuming the PHP LDAP extension is ultimately linked to the OpenLDAP client libraries, to resolve this issue you can set TLS_REQCERT never in the OpenLDAP client ldap.conf (and restart the web server) to indicate to the OpenLDAP client library that you trust the server. Alternately, if you are concerned that the server could be spoofed, you can export the LDAP server's root certificate and put it on the web server so that the OpenLDAP client can validate the server's identity.

Collecting Debugging Messages

Laminas\Authentication\Adapter\Ldap collects debugging information within its authenticate() method. This information is stored in the Laminas\Authentication\Result object as messages. The array returned by Laminas\Authentication\Result::getMessages() is described as follows:

In practice, index 0 should be displayed to the user (e.g., using the FlashMessenger helper), index 1 should be logged and, if debugging information is being collected, indexes 2 and higher could be logged as well (although the final message always includes the string from index 1).

Common Options for Specific Servers

Options for Active Directory

For AD*, the following options are noteworthy:

Use qualified account names

Technically there should be no danger of accidental cross-domain authentication with the current Laminas\Authentication\Adapter\Ldap implementation, since server domains are explicitly checked, but this may not be true of a future implementation that discovers the domain at runtime, or if an alternative adapter is used (e.g., Kerberos). In general, account name ambiguity is known to be the source of security issues, so always try to use qualified account names.

Options for OpenLDAP

For OpenLDAP or a generic LDAP server using a typical posixAccount style schema, the following options are noteworthy: