AuthenticationModule


1   /*
2    *  SSL-Explorer
3    *
4    *  Copyright (C) 2003-2006 3SP LTD. All Rights Reserved
5    *
6    *  This program is free software; you can redistribute it and/or
7    *  modify it under the terms of the GNU General Public License
8    *  as published by the Free Software Foundation; either version 2 of
9    *  the License, or (at your option) any later version.
10   *  This program is distributed in the hope that it will be useful,
11   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   *  GNU General Public License for more details.
14   *
15   *  You should have received a copy of the GNU General Public
16   *  License along with this program; if not, write to the Free Software
17   *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18   */
19              
20  package com.sslexplorer.security;
21  
22  import javax.servlet.http.HttpServletRequest  ;
23  import javax.servlet.http.HttpServletResponse  ;
24  
25  import org.apache.struts.action.ActionForward;
26  import org.apache.struts.action.ActionMapping;
27  
28  import com.sslexplorer.core.RequestParameterMap;
29  
30  /**
31   * Interface to be implemented to provide a single <i>Authentication Modules</i>.
32   * <p>
33   * Authentication modules provide the logic and the user interface for a single
34   * stage in an <i>Authentication Scheme</i> that a user must complete to 
35   * be able to logon on use SSL-Explorer's services.
36   * <p>
37   * Each module must have an {@link com.sslexplorer.security.AuthenticationModuleDefinition}
38   * that must be registed with the {@link com.sslexplorer.security.AuthenticationModuleManager}.
39   * <p>
40   * When authentication is required by the module, the first thing that happens
41   * is all of the modules in the scheme are initialised by called their {@link #init(AuthenticationScheme)}
42   * methods. 
43   * <p>
44   * When it is this schemes turn, the {@link #authenticate(HttpServletRequest, RequestParameterMap)}
45   * method will be called expecting either a {@link com.sslexplorer.security.Credentials}
46   * object or any exception to be thrown if the authentication failed.
47   * <p>
48   * If applicable, each module must return the page to a JSP page that provides
49   * the web based user interface for the module.
50   * <p>
51   * A module may be capable of supporting the entering of a username, in which
52   * case it is known as a <i>Primary Authentication Modules</i>. If this 
53   * capability is not available, the module is a <i>Secondary Authentication Module</i>
54   * and may only be used after a primary has already been used.
55   * <p>
56   * There is a third type called a <i>System Authentication Module</i> which is
57   * used interally by the SSL-Explorer or its plugins but never presented to
58   * user directly. These are currently used for Webdav and Embedded client
59   * logons. 
60   * 
61   * @author Brett Smith <a HREF="mailto: brett@3sp.com">&lt;brett@3sp.com&gt;</a>
62   * @see com.sslexplorer.security.AuthenticationScheme
63   * @see com.sslexplorer.security.AuthenticationModuleDefinition
64   * @see com.sslexplorer.security.AuthenticationModuleManager
65   */
66  public interface AuthenticationModule {
67      
68      /**
69       * Initialise the authenitcation module
70       * 
71       * @param session authentication scheme 
72       */
73      public void init(AuthenticationScheme session);
74      
75      /**
76       * Get the name of this module. 
77       * 
78       * @return module name
79       */
80      public String   getName();
81      
82      /**
83       * Invokeded when all modules in the scheme are complete and the user
84       * is now logged on.
85       * 
86       * @throws SecurityErrorException on any error
87       */
88      public void authenticationComplete() throws SecurityErrorException ;
89      
90      /**
91       * Invoked when the user submits the authentication information for
92       * this module. If the authentication details supplied are not valid
93       * then a {@link InvalidLoginCredentialsException} should be thrown.
94       * <p>
95       * A {@link Credentials} object may be returned that will be stored in
96       * the session and possibly used to sign on to external other resources
97       * automatically.  
98       * 
99       * @param request request
100      * @param parameters parameters
101      * @return credentials
102      * @throws InvalidLoginCredentialsException if authentication credentials incorrect
103      * @throws AccountLockedException if the account has been lock
104      * @throws SecurityErrorException on any other error
105      * @throws InputRequiredException 
106      */
107     public Credentials authenticate(HttpServletRequest   request, RequestParameterMap parameters) throws 
108         InvalidLoginCredentialsException,
109         AccountLockedException,
110         SecurityErrorException,
111         InputRequiredException;
112     
113     /**
114      * Get the path to the JSP fragment to be used for collecting the 
115      * authentication details from the user. <code>null</code> may be
116      * returned if the module is a <i>System Authentication Module</i>.
117      *   
118      * @return include poage
119      */
120     public String   getInclude();
121     
122     /**
123      * Invoked before authentication for this module begins (i.e. just before
124      * the JSP page is displayed). If a module is returning <code>false</code>
125      * from {@link #isRequired()} then it may return a forward to move onto
126      * instead of going to the authentication JSP page returned by {@link #getInclude()}.
127      * This is to allow modules that may require 'first time configuration'
128      * such as the personal answers module.
129      * 
130      * @param mapping mapping
131      * @param request request
132      * @param response response
133      * @return forward page to forward to or <code>null</code> to continue as normal
134      * @throws SecurityErrorException
135      */
136     public ActionForward startAuthentication(ActionMapping mapping, HttpServletRequest   request, HttpServletResponse   response) throws SecurityErrorException ;
137     
138     /**
139      * Get if this module is required. If it false then it is allowed to forward
140      * to a page other than the one return by {@link #getInclude()}.
141      * This is to allow modules that may require 'first time configuration'
142      * such as the personal answers module.
143      * 
144      * @return required
145      */
146     public boolean isRequired(); 
147 
148 }
149 
150
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags