View Javadoc

1   /* Copyright 2004, 2005 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.acegisecurity.ui.rememberme;
17  
18  import org.acegisecurity.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   * Acegi Security filters (namely {@link
29   * org.acegisecurity.ui.AbstractProcessingFilter} and {@link
30   * org.acegisecurity.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
37   * href="http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice">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 Acegi Security.
48   * </p>
49   *
50   * @author Ben Alex
51   * @version $Id: RememberMeServices.java,v 1.4 2005/11/17 00:56:09 benalex Exp $
52   */
53  public interface RememberMeServices {
54      //~ Methods ================================================================
55  
56      /***
57       * This method will be called whenever the <code>SecurityContextHolder</code> does
58       * not contain an <code>Authentication</code> and the Acegi Security
59       * system wishes to provide an implementation with an opportunity to
60       * authenticate the request using remember-me capabilities. Acegi Security
61       * makes no attempt whatsoever to determine whether the browser has
62       * requested remember-me services or presented a valid cookie. Such
63       * determinations are left to the implementation. If a browser has
64       * presented an unauthorised cookie for whatever reason, it should be
65       * silently ignored and invalidated using the
66       * <code>HttpServletResponse</code> object.
67       * 
68       * <p>
69       * The returned <code>Authentication</code> must be acceptable to  {@link
70       * org.acegisecurity.AuthenticationManager} or {@link
71       * org.acegisecurity.providers.AuthenticationProvider} defined by the
72       * web application. It is recommended {@link
73       * org.acegisecurity.providers.rememberme.RememberMeAuthenticationToken}
74       * be used in most cases, as it has a corresponding authentication
75       * provider.
76       * </p>
77       *
78       * @param request to look for a remember-me token within
79       * @param response to change, cancel or modify the remember-me token
80       *
81       * @return a valid authentication object, or <code>null</code> if the
82       *         request should not be authenticated
83       */
84      public Authentication autoLogin(HttpServletRequest request,
85          HttpServletResponse response);
86  
87      /***
88       * Called whenever an interactive authentication attempt was made, but the
89       * credentials supplied by the user were missing or otherwise invalid.
90       * Implementations should invalidate any and all remember-me tokens
91       * indicated in the <code>HttpServletRequest</code>.
92       *
93       * @param request that contained an invalid authentication request
94       * @param response to change, cancel or modify the remember-me token
95       */
96      public void loginFail(HttpServletRequest request,
97          HttpServletResponse response);
98  
99      /***
100      * Called whenever an interactive authentication attempt is successful. An
101      * implementation may automatically set a remember-me token in the
102      * <code>HttpServletResponse</code>, although this is not recommended.
103      * Instead, implementations should typically look for a request parameter
104      * that indicates the browser has presented an explicit request for
105      * authentication to be remembered, such as the presence of a HTTP POST
106      * parameter.
107      *
108      * @param request that contained the valid authentication request
109      * @param response to change, cancel or modify the remember-me token
110      * @param successfulAuthentication representing the successfully
111      *        authenticated principal
112      */
113     public void loginSuccess(HttpServletRequest request,
114         HttpServletResponse response, Authentication successfulAuthentication);
115 }