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;
    17
    18  import java.io.Serializable;
    19
    20  import java.security.Principal;
    21
    22
    23  /***
    24   * Represents an authentication request.
    25   *
    26   * <p>
    27   * An <code>Authentication</code> object is not considered authenticated until
    28   * it is processed by an {@link AuthenticationManager}.
    29   * </p>
    30   *
    31   * <p>
    32   * Stored in a request {@link
    33   * org.acegisecurity.context.security.SecurityContext}.
    34   * </p>
    35   *
    36   * @author Ben Alex
    37   * @version $Id: Authentication.java,v 1.10 2005/11/17 00:55:49 benalex Exp $
    38   */
    39  public interface Authentication extends Principal, Serializable {
    40      //~ Methods ================================================================
    41
    42      /***
    43       * See {@link #isAuthenticated()} for a full description.
    44       *
    45       * <p>
    46       * Implementations should <b>always</b> allow this method to be called with
    47       * a <code>false</code> parameter, as this is used by various classes to
    48       * specify the authentication token should not be trusted. If an
    49       * implementation wishes to reject an invocation with a <code>true</code>
    50       * parameter (which would indicate the authentication token is trusted - a
    51       * potential security risk) the implementation should throw an {@link
    52       * IllegalArgumentException}.
    53       * </p>
    54       *
    55       * @param isAuthenticated <code>true</code> if the token should be trusted
    56       *        (which may result in an exception) or <code>false</code> if the
    57       *        token should not be trusted
    58       *
    59       * @throws IllegalArgumentException if an attempt to make the
    60       *         authentication token trusted (by passing <code>true</code> as
    61       *         the argument) is rejected due to the implementation being
    62       *         immutable or implementing its own alternative approach to
    63       *         {@link #isAuthenticated()}
    64       */
    65      public void setAuthenticated(boolean isAuthenticated)
    66          throws IllegalArgumentException;
    67
    68      /***
    69       * Used to indicate to <code>AbstractSecurityInterceptor</code> whether it
    70       * should present the authentication token to the
    71       * <code>AuthenticationManager</code>. Typically an
    72       * <code>AuthenticationManager</code> (or, more often, one of its
    73       * <code>AuthenticationProvider</code>s) will return an immutable
    74       * authentication token after successful authentication, in which case
    75       * that token can safely return <code>true</code> to this method.
    76       * Returning <code>true</code> will improve performance, as calling the
    77       * <code>AuthenticationManager</code> for every request will no longer be
    78       * necessary.
    79       *
    80       * <p>
    81       * For security reasons, implementations of this interface should be very
    82       * careful about returning <code>true</code> to this method unless they
    83       * are either immutable, or have some way of ensuring the properties have
    84       * not been changed since original creation.
    85       * </p>
    86       *
    87       * @return true if the token has been authenticated and the
    88       *         <code>AbstractSecurityInterceptor</code> does not need to
    89       *         represent the token for re-authentication to the
    90       *         <code>AuthenticationManager</code>
    91       */
    92      public boolean isAuthenticated();
    93
    94      /***
    95       * Set by an <code>AuthenticationManager</code> to indicate the authorities
    96       * that the principal has been granted. Note that classes should not rely
    97       * on this value as being valid unless it has been set by a trusted
    98       * <code>AuthenticationManager</code>.
    99       *
    100      * @return the authorities granted to the principal, or <code>null</code>
    101      *         if authentication has not been completed
    102      */
    103     public GrantedAuthority[] getAuthorities();
    104
    105     /***
    106      * The credentials that prove the principal is correct. This is usually a
    107      * password, but could be anything relevant to the
    108      * <code>AuthenticationManager</code>. Callers are expected to populate
    109      * the credentials.
    110      *
    111      * @return the credentials that prove the identity of the
    112      *         <code>Principal</code>
    113      */
    114     public Object getCredentials();
    115
    116     /***
    117      * Stores additional details about the authentication request. These might
    118      * be an IP address, certificate serial number etc.
    119      *
    120      * @return additional details about the authentication request, or
    121      *         <code>null</code> if not used
    122      */
    123     public Object getDetails();
    124
    125     /***
    126      * The identity of the principal being authenticated. This is usually a
    127      * username. Callers are expected to populate the principal.
    128      *
    129      * @return the <code>Principal</code> being authenticated
    130      */
    131     public Object getPrincipal();
    132 }