Improve documentation of the authentication infrastructure.

Some implementations, e.g. SSO implementations, don't, but I guess a note along the lines of

> Implementations may also authenticate users. New code should call the Authenticator interface which use the _authenticate()_ method below."

What do you think?