Spring Security Document how to tell BindAuthenticator which attributes to fetch

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

Behaviour

I've explained BindAuthenticator's general behaviour in #8725.

With the search-and-bind strategy, you can tell BindAuthenticator which attributes to return by calling setReturningAttributes on a search which you then pass to BindAuthenticator.setUserSearch.

With the dnPatterns strategy, you can call setUserAttributes on your authenticator to tell it which attributes to return.

(There is no way to tell it which attributes to return -- regardless of strategy -- if you're using LdapAuthenticationProviderConfigurer, aka the AuthenticationProviderManager.ldapAuthentication().and.other.methods way of configuring security. You need to define beans or use an object postprocessor. See #4309.)

The attributes configured on the search are ignored when the dnPatterns strategy is used. To see this, go here, follow the README, and check out the dnpatterns-setattrs-search-searchattrs branch. You'll see the uid attribute, which is what setUserAttributes was called with, but not the cn attribute, which is what the search passed to the authenticator was told to return.

What setReturningAttributes was called with is ignored when the search-and-bind strategy is used. To see this, go to the repository linked above, follow the README, and check out the no-dnpatterns-setattrs-search-searchattrs branch. You'll see the cn attribute, which is what the search passed to the authenticator was told to return, but not the uid attribute, which is what setUserAttributes was called with.

Why document?

This has potential for confusion -- someone might use a search-and-bind strategy but call setUserAttributes on the authenticator (or conversely), and not understand why it doesn't work. So it should be documented.

Document where?

The javadocs for setReturningAttributes and setUserSearch. On setReturningAttributes, you could say that this method is respected only if one has also called setUserDnPatterns, and similar things on setUserSearch. You might also add a sentence or two here.

Comment From: rwinch

This sounds good.