com.qindesign.servlet
Class AuthenticatedHttpServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          com.qindesign.servlet.AuthenticatedHttpServlet

All Implemented Interfaces:

com.qindesign.snap.http.Authenticator.Authorizer, Servlet, ServletConfig

Direct Known Subclasses:

AuthExampleServlet, ShutdownServlet

public abstract class AuthenticatedHttpServlet
extends HttpServlet
implements com.qindesign.snap.http.Authenticator.Authorizer

This class is provided to enable servlets to perform authentication. It can be extended and used as-is by overriding the getRealm(HttpServletRequest) and getPassword(String, String) methods. If one wishes, the various doUnauthorizedXXX can be overridden to gather or send additional information after it is known that a request is unauthorized.

The design of this class is such that a developer needs only replace the HttpServlet superclass with AuthenticatedHttpServlet. All else is unchanged unless HttpServlet.service(HttpServletRequest, HttpServletResponse) needs to be overridden, in which case please see the authorizedService(HttpServletRequest, HttpServletResponse) and authorizedService(HttpServletRequest, HttpServletResponse) methods.

Subclassers may also wish to determine how their document is cached via the appropriate HTTP headers.

Version:

1.0.4

Author:

Shawn Silverman

See Also:

Authenticator.Authorizer

Constructor Summary

AuthenticatedHttpServlet()

Method Summary

protected void	authorizedService(HttpServletRequest req, HttpServletResponse resp) This method is the authorized equivalent of the HttpServlet.service(HttpServletRequest, HttpServletResponse) method.
protected void	doUnauthorizedDelete(HttpServletRequest req, HttpServletResponse resp) This method is called if the DELETE request was not authenticated.
protected void	doUnauthorizedGet(HttpServletRequest req, HttpServletResponse resp) This method is called if the GET request was not authenticated.
protected void	doUnauthorizedHead(HttpServletRequest req, HttpServletResponse resp) This method is called if the HEAD request was not authenticated.
protected void	doUnauthorizedOptions(HttpServletRequest req, HttpServletResponse resp) This method is called if the OPTIONS request was not authenticated.
protected void	doUnauthorizedPost(HttpServletRequest req, HttpServletResponse resp) This method is called if the POST request was not authenticated.
protected void	doUnauthorizedPut(HttpServletRequest req, HttpServletResponse resp) This method is called if the PUT request was not authenticated.
protected void	doUnauthorizedTrace(HttpServletRequest req, HttpServletResponse resp) This method is called if the TRACE request was not authenticated.
String	getDefaultScheme(HttpServletRequest req) Gets the default authentication scheme.
abstract String	getPassword(String realm, String user) This method must be implemented.
String	getProperty(String name, HttpServletRequest req) Gets a property of the authentication scheme.
abstract String	getRealm(HttpServletRequest req) Users must implement this to find the "realm" of a specific request.
boolean	isAuthExpired(long age, HttpServletRequest req) Checks if the authorization is expired for the given request.
boolean	isSchemeAcceptable(String scheme, HttpServletRequest req) Determines if the specified scheme is acceptable for the given request.
protected void	service(HttpServletRequest req, HttpServletResponse resp) Receives standard HTTP requests from the public service method and dispatches them to the doXXX methods defined in this class.
void	service(ServletRequest req, ServletResponse resp) This method is implemented so that it can be prevented from being overridden.
protected void	unauthorizedService(HttpServletRequest req, HttpServletResponse resp) This method is the unauthorized equivalent of the HttpServlet.service(HttpServletRequest, HttpServletResponse) method.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doOptions, doPost, doPut, doTrace, getLastModified

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init, log, log

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AuthenticatedHttpServlet

public AuthenticatedHttpServlet()

Method Detail

getRealm

public abstract String getRealm(HttpServletRequest req)

Users must implement this to find the "realm" of a specific request.

Specified by:

getRealm in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

req - the request

See Also:

Authenticator.Authorizer

getPassword

public abstract String getPassword(String realm,
                                   String user)

This method must be implemented. A null password indicates that the user is not authorized. The realm value should be treated case-insensitively.

Specified by:

getPassword in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

realm - the protection space, a case-insensitive value

user - the user

Returns:

the password for the specified user in the given realm.

getProperty

public String getProperty(String name,
                          HttpServletRequest req)

Gets a property of the authentication scheme. For example, this method can be used to provide a "domain" or an "opaque" value for digest authentication.

This returns null as the default.

Specified by:

getProperty in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

name - the name of the property whose value is requested

req - the request

Returns:

the value of the specified property or null if the property has no value.

getDefaultScheme

public String getDefaultScheme(HttpServletRequest req)

Gets the default authentication scheme. This should be either "Basic" or "Digest".

This returns "Digest" as the default.

Specified by:

getDefaultScheme in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

req - the request

Returns:

the default authentication scheme.

isSchemeAcceptable

public boolean isSchemeAcceptable(String scheme,
                                  HttpServletRequest req)

Determines if the specified scheme is acceptable for the given request. The scheme value should be checked case-insensitively.

As the default, this returns true only if the scheme is "Digest".

Specified by:

isSchemeAcceptable in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

scheme - the scheme currently being authorized, a case-insensitive value

req - the request

Returns:

whether the given scheme is acceptable for the given request.

isAuthExpired

public boolean isAuthExpired(long age,
                             HttpServletRequest req)

Checks if the authorization is expired for the given request. This is called when the authentication is known to be correct. In other words, the client appears to know the correct username and password. This helps protect against some attacks.

This is used by Digest authentication.

This returns false as the default.

Specified by:

isAuthExpired in interface com.qindesign.snap.http.Authenticator.Authorizer

Parameters:

age - the age, in ms, of the authorization

req - the request

Returns:

whether the authorization is expired for the given request.

See Also:

Section 4.3 "Limited Use Nonce Values", RFC 2617, p.21

service

public final void service(ServletRequest req,
                          ServletResponse resp)
                   throws ServletException,
                          IOException

This method is implemented so that it can be prevented from being overridden. This calls the superclass method.

Specified by:

service in interface Servlet

Overrides:

service in class HttpServlet

Throws:

ServletException

IOException

unauthorizedService

protected void unauthorizedService(HttpServletRequest req,
                                   HttpServletResponse resp)
                            throws ServletException,
                                   IOException

This method is the unauthorized equivalent of the HttpServlet.service(HttpServletRequest, HttpServletResponse) method. This is called when it is known that the request was not authorized. It dispatches the request to the appropriate doUnauthorizedXXX method.

One would want to override this method for the same reasons as overriding HttpServlet.service(HttpServletRequest, HttpServletResponse), except only for unauthorized requests.

Parameters:

req - the HTTP request object

resp - the HTTP response object

Throws:

ServletException - if the request cannot be handled.

IOException - if an I/O error occurs while handling the request.

authorizedService

protected void authorizedService(HttpServletRequest req,
                                 HttpServletResponse resp)
                          throws ServletException,
                                 IOException

This method is the authorized equivalent of the HttpServlet.service(HttpServletRequest, HttpServletResponse) method. This is called when it is known that the request is authenticated. It dispatches the request to the appropriate doXXX method.

One would want to override this method for the same reasons as overriding HttpServlet.service(HttpServletRequest, HttpServletResponse), except only for authenticated requests.

Parameters:

req - the HTTP request object

resp - the HTTP response object

Throws:

ServletException - if the request cannot be handled.

IOException - if an I/O error occurs while handling the request.

See Also:

unauthorizedService(HttpServletRequest, HttpServletResponse)

service

protected final void service(HttpServletRequest req,
                             HttpServletResponse resp)
                      throws ServletException,
                             IOException

Receives standard HTTP requests from the public service method and dispatches them to the doXXX methods defined in this class.

This method cannot be overridden because it performs the authentication. To implement similar behaviour, please override authorizedService(HttpServletRequest, HttpServletResponse). The unauthorized equivalent is unauthorizedService(HttpServletRequest, HttpServletResponse).

Overrides:

service in class HttpServlet

Parameters:

req - the HTTP request object

resp - the HTTP response object

Throws:

ServletException - if the request cannot be handled.

IOException - if an I/O error occurs while handling the request.

See Also:

authorizedService(HttpServletRequest, HttpServletResponse), unauthorizedService(HttpServletRequest, HttpServletResponse)

doUnauthorizedGet

protected void doUnauthorizedGet(HttpServletRequest req,
                                 HttpServletResponse resp)
                          throws ServletException,
                                 IOException

This method is called if the GET request was not authenticated. It is identical in purpose to doGet. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

This method also supports unauthorized HEAD requests.

Throws:

ServletException

IOException

doUnauthorizedHead

protected void doUnauthorizedHead(HttpServletRequest req,
                                  HttpServletResponse resp)
                           throws ServletException,
                                  IOException

This method is called if the HEAD request was not authenticated. It is identical in purpose to doHead. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException

doUnauthorizedPost

protected void doUnauthorizedPost(HttpServletRequest req,
                                  HttpServletResponse resp)
                           throws ServletException,
                                  IOException

This method is called if the POST request was not authenticated. It is identical in purpose to doPost. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException

doUnauthorizedPut

protected void doUnauthorizedPut(HttpServletRequest req,
                                 HttpServletResponse resp)
                          throws ServletException,
                                 IOException

This method is called if the PUT request was not authenticated. It is identical in purpose to doPut. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException

doUnauthorizedDelete

protected void doUnauthorizedDelete(HttpServletRequest req,
                                    HttpServletResponse resp)
                             throws ServletException,
                                    IOException

This method is called if the DELETE request was not authenticated. It is identical in purpose to doDelete. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException

doUnauthorizedOptions

protected void doUnauthorizedOptions(HttpServletRequest req,
                                     HttpServletResponse resp)
                              throws ServletException,
                                     IOException

This method is called if the OPTIONS request was not authenticated. It is identical in purpose to doOptions. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException

doUnauthorizedTrace

protected void doUnauthorizedTrace(HttpServletRequest req,
                                   HttpServletResponse resp)
                            throws ServletException,
                                   IOException

This method is called if the TRACE request was not authenticated. It is identical in purpose to doTrace. The response status code is already set appropriately.

This method provides the opportunity to gather or send additional information after it is known that the request was unauthorized.

Throws:

ServletException

IOException