SK.gnome.dwarf.http.servlet
Class LoginServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          SK.gnome.dwarf.http.servlet.ReflectionServlet
              SK.gnome.dwarf.http.servlet.LoginServlet

All Implemented Interfaces:

java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class LoginServlet

extends ReflectionServlet

This servlet handles the form-based authentication.

The servlet can be invoked automatically by the server or manually by the application code.

Automatic invocation

The servlet must be mapped to the "/j_security_check" path. The web application permissions should allow users to access this path without an authentication. Furthemore, all pages which the LoginServlet displays to the user must be accessible without a need to authenticate the user, too.

The servlet accepts two initial parameters:

• "loginPage" - the path to the page containing the login form. The form action must be j_security_check and it must contain two fields named j_username and j_password, according to the Java Servlet Specification.
• "loginErrorPage" - the path to the error page, which will be displayed if the login fails. The message parameter is passed to the page via the query string; it contains the login error description.

All mentioned paths must be absolute, but relative to the current servlet context.

The automatic authentication mechanism works as follows: If a requested URL requires authentication of the remote user, it is stored temporarily by the server and the request is redirected to the LoginServlet, if it is available. The servlet displays the login form to the user and the authentication information provided by the user is then passed back to the servlet which tries to authenticate the user. In the case of success, the client is redirected to the original URL stored by the server previously. If the authentication fails, either the custom error page is displayed or a standard HTML error message is sent to the user.

Manual invocation

The servlet actions can be invoked manually by a special request parameters. Assuming that the servlet is mapped to the "/j_security_check" path, the following list shows the request parameters which can be used to control the authentication:

• action - can be either form, login or logout. The first one displays the login form page, the second one authenticates the user with the username and password provided, and the third one logouts the currently authenticated user.
• loginPage - the path to page containing the login form
• loginErrorPage - the path to the error page to be displayed if the login fails
• j_username - the username provided by the user
• j_password - the password provided by the user
• redirectPage - the page where to redirect the request to in the case of successful authentication
• logoutPage - the path to page to be displayed in the case of successful logout
• loginErrorPage - the path to the error page to be displayed if the logout fails

All mentioned paths must be absolute, but relative to the current servlet context. The message parameter is provided to the error pages via the query string with the error description.

An alternative way how to provide the URL which to redirect the client to in the case of a successful login is to set the "sk.gnome.dwarf.http.redirURL" session attribute just before requesting the servlet's login action.

See Also:

Serialized Form

Constructor Summary

LoginServlet()

Method Summary

void	form(Request request, Response response) Displays the login form.
java.lang.String	getServletInfo()
void	handle(Request request, Response response) The default servlet action.
void	init()
void	logout(Request request, Response response) Logouts the user.

Methods inherited from class SK.gnome.dwarf.http.servlet.ReflectionServlet

doGet, doPost, getMethodName, handleActionNotFound

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

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

Methods inherited from class java.lang.Object

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

Constructor Detail

LoginServlet

public LoginServlet()

Method Detail

init

public void init()
          throws javax.servlet.ServletException

Throws:

javax.servlet.ServletException

getServletInfo

public java.lang.String getServletInfo()

Specified by:

getServletInfo in interface javax.servlet.Servlet

Overrides:

getServletInfo in class ReflectionServlet

form

public void form(Request request,
                 Response response)
          throws java.io.IOException,
                 javax.servlet.ServletException

Displays the login form.

The login form is specified by the loginPage request parameter.

Throws:

java.io.IOException

javax.servlet.ServletException

handle

public void handle(Request request,
                   Response response)
            throws java.io.IOException,
                   javax.servlet.ServletException

The default servlet action.

This action performs the actual authentication via the login(Subject, CallbackHandler) method of the parent Application object. The login error page specified by the loginErrorPage request parameter is displayed to the user in the case of a failed authentication. The message parameter is provided to the error page with the detailed error description.

Specified by:

handle in class ReflectionServlet

Parameters:

request - the request

response - the response

Throws:

javax.servlet.ServletException - general servlet exception

java.io.IOException - in the case of an I/O error

logout

public void logout(Request request,
                   Response response)
            throws java.io.IOException,
                   javax.servlet.ServletException

Logouts the user.

The logout page is specified via the logoutPage request parameter and it is displayed to the user in the case of a successful logout. The logout error page specified by the logoutErrorPage request parameter is displayed to the user in the case of a failed logout. The message parameter is provided to the error page with the detailed error description.

Throws:

java.io.IOException

javax.servlet.ServletException