001: /*
002: * AuthenticationMethod.java
003: *
004: * Version: $Revision: 2168 $
005: *
006: * Date: $Date: 2007-08-27 17:40:09 -0500 (Mon, 27 Aug 2007) $
007: *
008: * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
009: * Institute of Technology. All rights reserved.
010: *
011: * Redistribution and use in source and binary forms, with or without
012: * modification, are permitted provided that the following conditions are
013: * met:
014: *
015: * - Redistributions of source code must retain the above copyright
016: * notice, this list of conditions and the following disclaimer.
017: *
018: * - Redistributions in binary form must reproduce the above copyright
019: * notice, this list of conditions and the following disclaimer in the
020: * documentation and/or other materials provided with the distribution.
021: *
022: * - Neither the name of the Hewlett-Packard Company nor the name of the
023: * Massachusetts Institute of Technology nor the names of their
024: * contributors may be used to endorse or promote products derived from
025: * this software without specific prior written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
028: * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
029: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
030: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
031: * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
032: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
033: * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
034: * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
035: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
036: * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
037: * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
038: * DAMAGE.
039: */
040: package org.dspace.authenticate;
041:
042: import javax.servlet.ServletException;
043: import javax.servlet.http.HttpServletRequest;
044: import javax.servlet.http.HttpServletResponse;
045: import javax.servlet.jsp.PageContext;
046: import java.sql.SQLException;
047:
048: import org.apache.log4j.Logger;
049: import org.dspace.core.Context;
050: import org.dspace.eperson.EPerson;
051:
052: /**
053: * Implement this interface to participate in the stackable
054: * authentication mechanism. See the <code>AuthenticationManager</code>
055: * class for details about configuring authentication handlers.
056: * <p>
057: * Each <em>authentication method</em> provides a way to map
058: * "credentials" supplied by the client into a DSpace e-person.
059: * "Authentication" is when the credentials are compared against some
060: * sort of registry or other test of authenticity.
061: * <p>
062: * The DSpace instance may configure many authentication methods, in a
063: * "stack". The same credentials are passed to each method in turn
064: * until one accepts them, so each method need only attempt to interpret
065: * and validate the credentials and fail gracefully if they are not
066: * appropriate for it. The next method in the stack is then called.
067: *
068: * @see AuthenticationManager
069: *
070: * @author Larry Stone
071: * @version $Revision: 2168 $
072: */
073: public interface AuthenticationMethod {
074:
075: /**
076: * Symbolic return values for authenticate() method:
077: */
078:
079: /** Authenticated OK, EPerson has been set. */
080: public static final int SUCCESS = 1;
081:
082: /** User exists, but credentials (<em>e.g.</em> passwd) don't match. */
083: public static final int BAD_CREDENTIALS = 2;
084:
085: /** Not allowed to login this way without X.509 certificate. */
086: public static final int CERT_REQUIRED = 3;
087:
088: /** User not found using this method. */
089: public static final int NO_SUCH_USER = 4;
090:
091: /** User or password is not appropriate for this method. */
092: public static final int BAD_ARGS = 5;
093:
094: /**
095: * Predicate, whether to allow new EPerson to be created.
096: * The answer determines whether a new user is created when
097: * the credentials describe a valid entity but there is no
098: * corresponding EPerson in DSpace yet.
099: * The EPerson is only created if authentication succeeds.
100: *
101: * @param context
102: * DSpace context
103: * @param request
104: * HTTP request, in case it's needed. May be null.
105: * @param username
106: * Username, if available. May be null.
107: * @return true if new ePerson should be created.
108: */
109: public boolean canSelfRegister(Context context,
110: HttpServletRequest request, String username)
111: throws SQLException;
112:
113: /**
114: * Initialize a new EPerson record for a self-registered new user.
115: * Set any data in the EPerson that is specific to this authentication
116: * method.
117: *
118: * @param context
119: * DSpace context
120: * @param request
121: * HTTP request, in case it's needed. May be null.
122: * @param eperson
123: * newly created EPerson record - email + information from the
124: * registration form will have been filled out.
125: */
126: public void initEPerson(Context context,
127: HttpServletRequest request, EPerson eperson)
128: throws SQLException;
129:
130: /**
131: * Should (or can) we allow the user to change their password.
132: * Note that this means the password stored in the EPerson record, so if
133: * <em>any</em> method in the stack returns true, the user is
134: * allowed to change it.
135: *
136: * @param context
137: * DSpace context
138: * @param request
139: * HTTP request, in case it's needed. May be null.
140: * @param username
141: * Username, if available. May be null.
142: * @return true if this method allows user to change ePerson password.
143: */
144: public boolean allowSetPassword(Context context,
145: HttpServletRequest request, String username)
146: throws SQLException;
147:
148: /**
149: * Predicate, is this an implicit authentication method.
150: * An implicit method gets credentials from the environment (such as
151: * an HTTP request or even Java system properties) rather than the
152: * explicit username and password. For example, a method that reads
153: * the X.509 certificates in an HTTPS request is implicit.
154: *
155: * @return true if this method uses implicit authentication.
156: */
157: public boolean isImplicit();
158:
159: /**
160: * Get list of extra groups that user implicitly belongs to.
161: * Returns IDs of any EPerson-groups that the user authenticated by
162: * this request is <em>implicitly</em> a member of -- e.g.
163: * a group that depends on the client network-address.
164: * <p>
165: * It might make sense to implement this method by itself in a separate
166: * authentication method that just adds special groups, if the
167: * code doesn't belong with any existing auth method.
168: * The stackable authentication system was designed expressly to
169: * separate functions into "stacked" methods to keep your
170: * site-specific code modular and tidy.
171: *
172: * @param context
173: * A valid DSpace context.
174: *
175: * @param request
176: * The request that started this operation, or null if not applicable.
177: *
178: * @return array of EPerson-group IDs, possibly 0-length, but
179: * never <code>null</code>.
180: */
181: public int[] getSpecialGroups(Context context,
182: HttpServletRequest request) throws SQLException;
183:
184: /**
185: * Authenticate the given or implicit credentials.
186: * This is the heart of the authentication method: test the
187: * credentials for authenticity, and if accepted, attempt to match
188: * (or optionally, create) an <code>EPerson</code>. If an <code>EPerson</code> is found it is
189: * set in the <code>Context</code> that was passed.
190: *
191: * @param context
192: * DSpace context, will be modified (ePerson set) upon success.
193: *
194: * @param username
195: * Username (or email address) when method is explicit. Use null for
196: * implicit method.
197: *
198: * @param password
199: * Password for explicit auth, or null for implicit method.
200: *
201: * @param realm
202: * Realm is an extra parameter used by some authentication methods, leave null if
203: * not applicable.
204: *
205: * @param request
206: * The HTTP request that started this operation, or null if not applicable.
207: *
208: * @return One of:
209: * SUCCESS, BAD_CREDENTIALS, CERT_REQUIRED, NO_SUCH_USER, BAD_ARGS
210: * <p>Meaning:
211: * <br>SUCCESS - authenticated OK.
212: * <br>BAD_CREDENTIALS - user exists, but credentials (e.g. passwd) don't match
213: * <br>CERT_REQUIRED - not allowed to login this way without X.509 cert.
214: * <br>NO_SUCH_USER - user not found using this method.
215: * <br>BAD_ARGS - user/pw not appropriate for this method
216: */
217:
218: public int authenticate(Context context, String username,
219: String password, String realm, HttpServletRequest request)
220: throws SQLException;
221:
222: /**
223: * Get login page to which to redirect.
224: * Returns URL (as string) to which to redirect to obtain
225: * credentials (either password prompt or e.g. HTTPS port for client
226: * cert.); null means no redirect.
227: *
228: * @param context
229: * DSpace context, will be modified (ePerson set) upon success.
230: *
231: * @param request
232: * The HTTP request that started this operation, or null if not applicable.
233: *
234: * @param response
235: * The HTTP response from the servlet method.
236: *
237: * @return fully-qualified URL or null
238: */
239: public String loginPageURL(Context context,
240: HttpServletRequest request, HttpServletResponse response);
241:
242: /**
243: * Get title of login page to which to redirect.
244: * Returns a <i>message key</i> that gets translated into the title
245: * or label for "login page" (or null, if not implemented) This
246: * title may be used to identify the link to the login page in a
247: * selection menu, when there are multiple ways to login.
248: *
249: * @param context
250: * DSpace context, will be modified (ePerson set) upon success.
251: *
252: * @return title text.
253: */
254: public String loginPageTitle(Context context);
255: }
|