001: /* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
002: *
003: * Licensed under the Apache License, Version 2.0 (the "License");
004: * you may not use this file except in compliance with the License.
005: * You may obtain a copy of the License at
006: *
007: * http://www.apache.org/licenses/LICENSE-2.0
008: *
009: * Unless required by applicable law or agreed to in writing, software
010: * distributed under the License is distributed on an "AS IS" BASIS,
011: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: * See the License for the specific language governing permissions and
013: * limitations under the License.
014: */
015:
016: package org.acegisecurity.ui.rememberme;
017:
018: import org.acegisecurity.Authentication;
019:
020: import javax.servlet.http.HttpServletRequest;
021: import javax.servlet.http.HttpServletResponse;
022:
023: /**
024: * Implement by a class that is capable of providing a remember-me service.
025: *
026: * <p>
027: * Acegi Security filters (namely {@link
028: * org.acegisecurity.ui.AbstractProcessingFilter} and {@link
029: * org.acegisecurity.ui.rememberme.RememberMeProcessingFilter} will call
030: * the methods provided by an implementation of this interface.
031: * </p>
032: *
033: * <p>
034: * Implementations may implement any type of remember-me capability they wish.
035: * Rolling cookies (as per <a href="http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice">
036: * http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice</a>)
037: * can be used, as can simple implementations that don't require a persistent
038: * store. Implementations also determine the validity period of a remember-me
039: * cookie. This interface has been designed to accommodate any of these
040: * remember-me models.
041: * </p>
042: *
043: * <p>
044: * This interface does not define how remember-me services should offer a
045: * "cancel all remember-me tokens" type capability, as this will be
046: * implementation specific and requires no hooks into Acegi Security.
047: * </p>
048: *
049: * @author Ben Alex
050: * @version $Id: RememberMeServices.java 1784 2007-02-24 21:00:24Z luke_t $
051: */
052: public interface RememberMeServices {
053: //~ Methods ========================================================================================================
054:
055: /**
056: * This method will be called whenever the <code>SecurityContextHolder</code> does not contain an
057: * <code>Authentication</code> and the Acegi Security system wishes to provide an implementation with an
058: * opportunity to authenticate the request using remember-me capabilities. Acegi Security makes no attempt
059: * whatsoever to determine whether the browser has requested remember-me services or presented a valid cookie.
060: * Such determinations are left to the implementation. If a browser has presented an unauthorised cookie for
061: * whatever reason, it should be silently ignored and invalidated using the <code>HttpServletResponse</code>
062: * object.<p>The returned <code>Authentication</code> must be acceptable to {@link
063: * org.acegisecurity.AuthenticationManager} or {@link org.acegisecurity.providers.AuthenticationProvider} defined
064: * by the web application. It is recommended {@link
065: * org.acegisecurity.providers.rememberme.RememberMeAuthenticationToken} be used in most cases, as it has a
066: * corresponding authentication provider.</p>
067: *
068: * @param request to look for a remember-me token within
069: * @param response to change, cancel or modify the remember-me token
070: *
071: * @return a valid authentication object, or <code>null</code> if the request should not be authenticated
072: */
073: Authentication autoLogin(HttpServletRequest request,
074: HttpServletResponse response);
075:
076: /**
077: * Called whenever an interactive authentication attempt was made, but the credentials supplied by the user
078: * were missing or otherwise invalid. Implementations should invalidate any and all remember-me tokens indicated
079: * in the <code>HttpServletRequest</code>.
080: *
081: * @param request that contained an invalid authentication request
082: * @param response to change, cancel or modify the remember-me token
083: */
084: void loginFail(HttpServletRequest request,
085: HttpServletResponse response);
086:
087: /**
088: * Called whenever an interactive authentication attempt is successful. An implementation may automatically
089: * set a remember-me token in the <code>HttpServletResponse</code>, although this is not recommended. Instead,
090: * implementations should typically look for a request parameter that indicates the browser has presented an
091: * explicit request for authentication to be remembered, such as the presence of a HTTP POST parameter.
092: *
093: * @param request that contained the valid authentication request
094: * @param response to change, cancel or modify the remember-me token
095: * @param successfulAuthentication representing the successfully authenticated principal
096: */
097: void loginSuccess(HttpServletRequest request,
098: HttpServletResponse response,
099: Authentication successfulAuthentication);
100: }
|