AuthenticationMethod


1   /*
2    * AuthenticationMethod.java
3    *
4    * Version: $Revision: 1.1 $
5    *
6    * Date: $Date: 2005/10/17 03:35:45 $
7    *
8    * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
9    * Institute of Technology.  All rights reserved.
10   *
11   * Redistribution and use in source and binary forms, with or without
12   * modification, are permitted provided that the following conditions are
13   * met:
14   *
15   * - Redistributions of source code must retain the above copyright
16   * notice, this list of conditions and the following disclaimer.
17   *
18   * - Redistributions in binary form must reproduce the above copyright
19   * notice, this list of conditions and the following disclaimer in the
20   * documentation and/or other materials provided with the distribution.
21   *
22   * - Neither the name of the Hewlett-Packard Company nor the name of the
23   * Massachusetts Institute of Technology nor the names of their
24   * contributors may be used to endorse or promote products derived from
25   * this software without specific prior written permission.
26   *
27   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28   * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31   * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
32   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
33   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
34   * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
35   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
36   * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
37   * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
38   * DAMAGE.
39   */
40  package org.dspace.eperson;
41  
42  import javax.servlet.ServletException  ;
43  import javax.servlet.http.HttpServletRequest  ;
44  import javax.servlet.http.HttpServletResponse  ;
45  import javax.servlet.jsp.PageContext  ;
46  import java.sql.SQLException  ;
47  
48  import org.apache.log4j.Logger;
49  import org.dspace.core.Context;
50  import org.dspace.eperson.EPerson;
51  
52  
53  /**
54   * Implement this interface to participate in the stackable
55   * authentication mechanism.  See the <code>AuthenticationManager</code>
56   * class for details about configuring authentication handlers.
57   * <p>
58   * Each <em>authentication method</em> provides a way to map
59   * "credentials" supplied by the client into a DSpace e-person.
60   * "Authentication" is when the credentials are compared against some
61   * sort of registry or other test of authenticity.
62   * <p>
63   * The DSpace instance may configure many authentication methods, in a
64   * "stack".  The same credentials are passed to each method in turn
65   * until one accepts them, so each method need only attempt to interpret
66   * and validate the credentials and fail gracefully if they are not
67   * appropriate for it.  The next method in the stack is then called.
68   *
69   * @see AuthenticationManager
70   *
71   * @author Larry Stone
72   * @version $Revision: 1.1 $
73   */
74  public interface AuthenticationMethod {
75  
76      /**
77       * Symbolic return values for authenticate() method:
78       */
79  
80      /** Authenticated OK, EPerson has been set. */
81      public static final int SUCCESS = 1;
82  
83      /** User exists, but credentials (<em>e.g.</em> passwd) don't match. */
84      public static final int BAD_CREDENTIALS = 2;
85  
86      /** Not allowed to login this way without X.509 certificate. */
87      public static final int CERT_REQUIRED = 3;
88  
89      /** User not found using this method. */
90      public static final int NO_SUCH_USER = 4;
91  
92      /** User or password is not appropriate for this method. */
93      public static final int BAD_ARGS = 5;
94  
95  
96      /**
97       * Predicate, whether to allow new EPerson to be created.
98       * The answer determines whether a new user is created when
99       * the credentials describe a valid entity but there is no
100      * corresponding EPerson in DSpace yet.
101      * The EPerson is only created if authentication succeeds.
102      *
103      * @param context
104      *            DSpace context
105      * @param request
106      *            HTTP request, in case it's needed. May be null.
107      * @param username
108      *            Username, if available.  May be null.
109      * @return true if new ePerson should be created.
110      */
111     public boolean canSelfRegister(Context   context,
112                                    HttpServletRequest   request,
113                                    String   username)
114         throws SQLException  ;
115 
116     /**
117      * Initialize a new EPerson record for a self-registered new user.
118      * Set any data in the EPerson that is specific to this authentication
119      * method.
120      *
121      * @param context
122      *            DSpace context
123      * @param request
124      *            HTTP request, in case it's needed. May be null.
125      * @param eperson
126      *            newly created EPerson record - email + information from the
127      *            registration form will have been filled out.
128      */
129     public void initEPerson(Context   context,
130                             HttpServletRequest   request,
131                             EPerson eperson)
132         throws SQLException  ;
133 
134     /**
135      * Should (or can) we allow the user to change their password.
136      * Note that this means the password stored in the EPerson record, so if
137      * <em>any</em> method in the stack returns true, the user is
138      * allowed to change it.
139      *
140      * @param context
141      *            DSpace context
142      * @param request
143      *            HTTP request, in case it's needed. May be null.
144      * @param username
145      *            Username, if available.  May be null.
146      * @return true if this method allows user to change ePerson password.
147      */
148     public boolean allowSetPassword(Context   context,
149                                     HttpServletRequest   request,
150                                     String   username)
151         throws SQLException  ;
152 
153     /**
154      * Predicate, is this an implicit authentication method.
155      * An implicit method gets credentials from the environment (such as
156      * an HTTP request or even Java system properties) rather than the
157      * explicit username and password.  For example, a method that reads
158      * the X.509 certificates in an HTTPS request is implicit.
159      *
160      * @return true if this method uses implicit authentication.
161      */
162     public boolean isImplicit();
163 
164     /**
165      * Get list of extra groups that user implicitly belongs to.
166      * Returns IDs of any EPerson-groups that the user authenticated by
167      * this request is <em>implicitly</em> a member of -- e.g.
168      * a group that depends on the client network-address.
169      * <p>
170      * It might make sense to implement this method by itself in a separate
171      * authentication method that just adds special groups, if the
172      * code doesn't belong with any existing auth method.
173      * The stackable authentication system was designed expressly to
174      * separate functions into "stacked" methods to keep your
175      * site-specific code  modular and tidy.
176      *
177      * @param context
178      *  A valid DSpace context.
179      *
180      * @param request
181      *  The request that started this operation, or null if not applicable.
182      *
183      * @return array of EPerson-group IDs, possibly 0-length, but
184      * never <code>null</code>.
185      */
186     public int[] getSpecialGroups(Context   context, HttpServletRequest   request);
187 
188     /**
189      * Authenticate the given or implicit credentials.
190      * This is the heart of the authentication method: test the
191      * credentials for authenticity, and if accepted, attempt to match
192      * (or optionally, create) an <code>EPerson</code>.  If an <code>EPerson</code> is found it is
193      * set in the <code>Context</code> that was passed.
194      *
195      * @param context
196      *  DSpace context, will be modified (ePerson set) upon success.
197      *
198      * @param username
199      *  Username (or email address) when method is explicit. Use null for
200      *  implicit method.
201      *
202      * @param password
203      *  Password for explicit auth, or null for implicit method.
204      *
205      * @param realm
206      *  Realm is an extra parameter used by some authentication methods, leave null if
207      *  not applicable.
208      *
209      * @param request
210      *  The HTTP request that started this operation, or null if not applicable.
211      *
212      * @return One of:
213      *   SUCCESS, BAD_CREDENTIALS, CERT_REQUIRED, NO_SUCH_USER, BAD_ARGS
214      * <p>Meaning:
215      * <br>SUCCESS         - authenticated OK.
216      * <br>BAD_CREDENTIALS - user exists, but credentials (e.g. passwd) don't match
217      * <br>CERT_REQUIRED   - not allowed to login this way without X.509 cert.
218      * <br>NO_SUCH_USER    - user not found using this method.
219      * <br>BAD_ARGS        - user/pw not appropriate for this method
220      */
221 
222     public int authenticate(Context   context,
223                             String   username,
224                             String   password,
225                             String   realm,
226                             HttpServletRequest   request)
227         throws SQLException  ;
228 
229     /**
230      * Get login page to which to redirect.
231      * Returns URL (as string) to which to redirect to obtain
232      * credentials (either password prompt or e.g. HTTPS port for client
233      * cert.); null means no redirect.
234      *
235      * @param context
236      *  DSpace context, will be modified (ePerson set) upon success.
237      *
238      * @param request
239      *  The HTTP request that started this operation, or null if not applicable.
240      *
241      * @param response
242      *  The HTTP response from the servlet method.
243      *
244      * @return fully-qualified URL or null
245      */
246     public String   loginPageURL(Context   context,
247                             HttpServletRequest   request,
248                             HttpServletResponse   response);
249 
250     /**
251      * Get title of login page to which to redirect.
252      * Returns a <i>message key</i> that gets translated into the title
253      * or label for "login page" (or null, if not implemented) This
254      * title may be used to identify the link to the login page in a
255      * selection menu, when there are multiple ways to login.
256      *
257      * @param context
258      *  DSpace context, will be modified (ePerson set) upon success.
259      *
260      * @return title text.
261      */
262     public String   loginPageTitle(Context   context);
263 }
264
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags