Better document what the authentication handler should return

[jobevers]

The current docs specify that the authentication handler "should return an object representing an authenticated identity." but its not clear what exactly that means. Digging into the source I can see that the only thing that is important is the id property/key.

I think it would be useful to note that in the docs.