KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sslexplorer > security > 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 JavaDoc;
23 import javax.servlet.http.HttpServletResponse JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc request, HttpServletResponse JavaDoc 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
Popular Tags