Clarified information about authenticators

[edjiang]

This PR may require a bit more discussion, but when writing #75, I realized that the authenticators document wasn't clear at all, and did not reflect what's in production on Express. While express should not be the reference implementation, I think what's implemented in there should be something we can expect in all frameworks.

I clarified information about the authentication helpers we should be providing, and the responses they should be giving.

I named the authenticators based on the latest discussion in https://github.com/stormpath/express-stormpath/issues/173

[nbarbettini]

Awesome, this should go a long way toward clearing up the vagueness in this document. Looking forward to @robertjd's feedback.

[robertjd]

This is moving in the right direction, here is my feedback:

• "User Authentication Gatekeepers" should be called "Authentication Filters".
• "requireUser" should be called "requireAuthentication"

The "User Resolvers" needs a hint at why it's there. Here is the developer story that prompted the creation of getUser in Express:

I have a home page on my site, I need to render the menu bar differently if the user is logged in.

• When authentication can't be achieved, we don't render an error page for HTML responses. Instead we redirect to the login page, as defined by stormpath.web.login.uri.

[lhazlewood]

FWIW, we don't use 'user' nomenclature in the Java SDK or integrations. I'd like to keep it that way because we match the Stormpath data model so things are clear and understood as to what is going on. Also, FWIW, in the security world a potentially more accurate term for user is Subject since 'user' usually implies a human being to most people, whereas Subject means more or less 'anyone or anything (e.g. client) that is interacting with the software'

[edjiang]

Awesome, updated as per feedback.

@robertjd I've renamed getUser to getAccount as per @lhazlewood 's feedback.

[robertjd]

This is looking awesome, I added some more comments.

[edjiang]

Awesome, updated!

[omgitstom]

@edjiang @robertjd

The Authentication Filters section needs the implementation details removed to made a little more vague so that an engineering can make a decision to either a) create the behavior in the integration b) delegate to another authorization framework

[edjiang]

Takeaways from discussion with @robertjd just now, we are going to propose the following solution:

• Modify account resolver to return method of authentication
• Remove filters
• Loosen response type for next parameter