The UserManager interface documentation should be a form of contract between the implementor and the user of the interface.
After reading the documentation the implementor still has these question:
- when I should throw a AuthenticationFailedException?
- when I should return a null as a result?
- if the object receive two subsequent calls withe the same arguments the objects returned should be the same (same reference), only equals, or they can be different?