This document proposes conventions for authentication middlewares to follow in order for applications and authorization middlewares to be able to interact with each other.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
A Stack authentication token represents the user or service driving the user
agent making a request. The token MUST be stored as the
request attribute. The token MUST either be a string or serializable.
A Stack authentication middleware is free to use whatever means necessary to
authenticate a request. The end result of a successfully authenticated request
should be that the
stack.authn.token attribute on the request is set to a
If a request has authentication credentials that are invalid for any reason a Stack authentication middleware MAY either immediately challenge or return another response (for example, a 400 error response).
If a request already has the
stack.authn.token attribute set a Stack
authentication middleware MUST NOT attempt to further authenticate the request.
However, the Stack authentication middleware MAY act further upon inspecting
Stack authentication middlewares SHOULD inspect the response from the wrapped
app to see if it has a status code of
401 and a
header. In this case, the Stack authentication middleware can use its own best
judgement to determine whether or not it should issue a challenge.
Modifying or replacing the response is allowed but a Stack authentication
middleware MUST NOT challenge unless the response is in this state. If a Stack
authentication middleware does not change the
WWW-Authenticate value other
Stack authentication middlewares will be given an opportunity to challenge.