I'd like to propose the addition of login and logout methods to the Servlet 3.0 API. The login methods are intended to allow an application or framework to force a container mediated authentication from within an unconstrained request context. The logout methods are provided to allow an application to reset the authentication state of a request without requiring that authentication be bound to an HttpSession, and without requiring that an HttpSession be destroyed to effect the logout.

The login methods are expected to require access to the corresponding HttpServletResponse message (for example when the response is modified to include a www-authenticate header). The intent is that the required access could be achieved by using the getResponseMessage method proposed for addition to ServletRequest and ServletRequestWrapper. For this to be feasible, the getResponseMessage method should require that the returned type be a subclass of HttpServletResponse when the object on which the method is called is a subclass of HttpServletRequest or HttpServletRequestWrapper.

You will notice that the proposed methods have been declared to throw LoginException. This was done to facilitate alignment with the corresponding JAAS functions. As with the entire proposal, please suggest alternatives as you see fit.

I did not specify the effect on the authentication state of an associated HttpSession when logout is called on a request or wrapper bound to an HttpSession. My inclination is that the effect should be identical to calling logout on the HttpSession.

------

/**
 * Use the container login mechanism configured for the ServletContext
 * to authenticate the user making this request. This method
 * may modify the HttpServletResponse associated with the request.
 *
 * @return true when non-null values were or have been
 * established as the values returned by getUserPrincipal,
 * getRemoteUser, and getAuthType. Return false if authentication
 * is incomplete and when the underlying login mechanism has
 * established the response message and HTTP status code to be
 * returned to the user.
 *
 * @throws LoginException if validation of provided credentials fails.
 * @throws IOException if an error occurs while writing the response.
 */

public boolean HttpServletRequest.login() throws IOException, LoginException;

public boolean HttpServletRequestWrapper.login() throws IOException, LoginException;

/**
 * Establish null as the value returned when getUserPrincipal,
 * getRemoteUser, or getAuthType is called on the request.
 *
 * @throws LoginException if logout fails.
*/

public void HttpServletRequest.logout() throws LoginException;

public void HttpServletRequestWrapper.logout() throws LoginException;

/**
 * Establish null as the value returned when getUserPrincipal,
 * getRemoteUser, or getAuthType is called on any HttpServletRequest
 * that is bound to the session.
 *
 * @throws LoginException if logout fails.
*/

public void HttpSession.logout() throws LoginException;