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 }