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 }