1 /* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.springframework.security.ui.rememberme;
17
18 import org.springframework.security.Authentication;
19
20 import javax.servlet.http.HttpServletRequest;
21 import javax.servlet.http.HttpServletResponse;
22
23
24 /**
25 * Implement by a class that is capable of providing a remember-me service.
26 *
27 * <p>
28 * Spring Security filters (namely {@link
29 * org.springframework.security.ui.AbstractProcessingFilter} and {@link
30 * org.springframework.security.ui.rememberme.RememberMeProcessingFilter} will call
31 * the methods provided by an implementation of this interface.
32 * </p>
33 *
34 * <p>
35 * Implementations may implement any type of remember-me capability they wish.
36 * Rolling cookies (as per <a href="http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice">
37 * http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice</a>)
38 * can be used, as can simple implementations that don't require a persistent
39 * store. Implementations also determine the validity period of a remember-me
40 * cookie. This interface has been designed to accommodate any of these
41 * remember-me models.
42 * </p>
43 *
44 * <p>
45 * This interface does not define how remember-me services should offer a
46 * "cancel all remember-me tokens" type capability, as this will be
47 * implementation specific and requires no hooks into Spring Security.
48 * </p>
49 *
50 * @author Ben Alex
51 * @version $Id: RememberMeServices.java 2217 2007-10-27 00:45:30Z luke_t $
52 */
53 public interface RememberMeServices {
54 //~ Methods ========================================================================================================
55
56 /**
57 * This method will be called whenever the <code>SecurityContextHolder</code> does not contain an
58 * <code>Authentication</code> object and Spring Security wishes to provide an implementation with an
59 * opportunity to authenticate the request using remember-me capabilities. Spring Security makes no attempt
60 * whatsoever to determine whether the browser has requested remember-me services or presented a valid cookie.
61 * Such determinations are left to the implementation. If a browser has presented an unauthorised cookie for
62 * whatever reason, it should be silently ignored and invalidated using the <code>HttpServletResponse</code>
63 * object.<p>The returned <code>Authentication</code> must be acceptable to {@link
64 * org.springframework.security.AuthenticationManager} or
65 * {@link org.springframework.security.providers.AuthenticationProvider} defined by the web application. It is recommended {@link
66 * org.springframework.security.providers.rememberme.RememberMeAuthenticationToken} be used in most cases, as it has a
67 * corresponding authentication provider.</p>
68 *
69 * @param request to look for a remember-me token within
70 * @param response to change, cancel or modify the remember-me token
71 *
72 * @return a valid authentication object, or <code>null</code> if the request should not be authenticated
73 */
74 Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
75
76 /**
77 * Called whenever an interactive authentication attempt was made, but the credentials supplied by the user
78 * were missing or otherwise invalid. Implementations should invalidate any and all remember-me tokens indicated
79 * in the <code>HttpServletRequest</code>.
80 *
81 * @param request that contained an invalid authentication request
82 * @param response to change, cancel or modify the remember-me token
83 */
84 void loginFail(HttpServletRequest request, HttpServletResponse response);
85
86 /**
87 * Called whenever an interactive authentication attempt is successful. An implementation may automatically
88 * set a remember-me token in the <code>HttpServletResponse</code>, although this is not recommended. Instead,
89 * implementations should typically look for a request parameter that indicates the browser has presented an
90 * explicit request for authentication to be remembered, such as the presence of a HTTP POST parameter.
91 *
92 * @param request that contained the valid authentication request
93 * @param response to change, cancel or modify the remember-me token
94 * @param successfulAuthentication representing the successfully authenticated principal
95 */
96 void loginSuccess(HttpServletRequest request, HttpServletResponse response,
97 Authentication successfulAuthentication);
98 }