Document how BindAuthenticator fetches attributes

[ghost]

As requested, I am splitting the long and unclear #8560 into several issues. This issue is about documenting how BindAuthenticator fetches attributes.

Behaviour

There are two ways to use BindAuthenticator. Way one: call setUserDnPatterns. Way two: call setUserSearch.

If you choose the first way, BindAuthenticator will attempt to bind with the dnPatterns you gave it. It will not, as far as I can tell, perform any search. If the bind succeeds, it will fetch the user's attributes with the user's permissions.

If you choose the second way, BindAuthenticator will perform a search for the user with the app user's permissions. Probably, this search will fetch some attributes -- again, with the app user's permissions. Then, it will bind as the user -- but it will not fetch attributes again.

In summary: if you choose the first way, you get all of the user's attributes that the user can see. If you choose the second way, you get all of the user's attributes that the app user can see. In some LDAP configurations, those two things are not the same.

To see this in action, go to this repository and follow the README. Having done that, first check out one of the only-dnpatterns-* branches. Log in and observe that you can see (in the logs) the sn attribute. Then, check out one of the only-search-* branches. Log in and observe that you can't see the sn attribute. (The access controls of the server are configured so that the user can read the sn attribute, but the anonymous user -- which the application binds as -- can't.)

Why this merits documentation

I spent a couple of hours trying to figure out why changing my bind strategy changed which attributes got fetched. I don't think I'm unusual in not expecting that to happen. It's worth thinking about not making it happen, but that's a separate issue (#8727); whether or not you decide to change the API, documenting the current behaviour seems sensible.

Where to document it

Here, or in the section immediately after ("Using Bind Authentication"). I think just adding the information in my "in summary" paragraph from above is enough.

[rwinch]

The suggested location sounds good to me. We can always refactor things as needed.