= Disambiguating user objects

In some instances a user may have objects located in multiple areas of
the LDAP directory.

If when the LDAP module tries to locate a user, more than one entry is
returned, authentication will fail with the following error:

```
ldap: ERROR: Ambiguous search result, returned 2 unsorted entries (should return 1 or 0).  Enable sorting, or specify a more restrictive base_dn, filter or scope
ldap: ERROR: The following entries were returned:
ldap:   ERROR: uid=john,ou=people,dc=example,dc=com
ldap:   ERROR: uid=john,dc=example,dc=com
```

As the error message states, there are multiple ways to resolve this issue:

1. Specify a more restrictive base_dn.  In this example changing `user.base_dn`
   to `ou=people,dc=example,dc=com` would resolve the issue.
2. Specify a more restrictive filter.  For example, if one object represented
   a user's login account, and another represented a Human Resources record,
   the `user.filter` value could be changed to only return objects with an
   object class that indicated the object represented login account
   e.g. `(&(objectClass=posixAccount)(uid=...))`.
3. Change the scope of the search to be more restritive.  If the additional user
   object is located in a child object under the user base_dn, setting `user.scope`
   to 'one' will resolve user object ambiguity by restricting the search to the
   direct children of the user base_dn.
4. As a last resort you can enable the Server Side Sorting extension (if
   supported) on the LDAP server (see below).

== Enabling and configuring Server Side Sorting

Server Side Sorting controls are specified by
https://tools.ietf.org/html/rfc2891[RFC 2891].

SSS controls allow the client to request the server sort results in a specific
and consistent order.  This ensures that in the case where there is an ambiguous
result, the same user object (the first in the result set) will be used by the
LDAP module.

Without SSS which object is used by the LDAP module will be essentially random.

[TIP]
====
If you followed the
xref:modules/ldap/bootstrap_openldap/packages.adoc[Installing OpenLDAP from
packages] section you can enable the Server Side Sorting (SSS) overlay via OLC
using the ldif below.

[source,ldif]
----
cat <<EOF | ldapadd -Y EXTERNAL -H ldapi://%2Fvar%2Frun%2Fslapd%2Fldapi
dn: olcOverlay=sssvlv,olcDatabase={1}mdb,cn=config
objectClass: olcSssVlvConfig
olcOverlay: sssvlv
olcSssVlvMax: 10
olcSssVlvMaxKeys: 5
EOF
----
====

== Editing mods-available/ldap to enable Server Side Sorting

[source,config]
----
ldap {
	user {
		sort_by = '<user_uid_attribute>'             <1>
	}
}
----

<1> The attribute that attributes should be sorted by. It can be difficult to find
    an attribute (or attributes - comma delimited) that disambiguate user objects in
    a meaningful way.  If the LDAP server allows 'dn' to be specified as a sorting
    attribute, it's recommended to use that.
