I'm happy to reconsider throwing IOException. But the core idea is worthwhile: throw GeneralSecurityException (typically LoginException) for a credential failure and some other branch of exception for any other kind of error (e.g. socket exception)  that prevented authentication from occurring. This would allow us to develop a policy in higher components of continuing to next handler on GeneralSecurityException while stopping outright on the other exception type.

It's likely a documentation problem on the point about throwing and returning a result. A result is returned if an only if a credential is successfully validated.