View Javadoc

1   /* Copyright 2004 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  /***
19   * Processes an {@link Authentication} request.
20   *
21   * @author Ben Alex
22   * @version $Id: AuthenticationManager.java,v 1.3 2005/11/17 00:55:49 benalex Exp $
23   */
24  public interface AuthenticationManager {
25      //~ Methods ================================================================
26  
27      /***
28       * Attempts to authenticate the passed {@link Authentication} object,
29       * returning a fully populated <code>Authentication</code> object
30       * (including granted authorities) if successful.
31       * 
32       * <p>
33       * An <code>AuthenticationManager</code> must honour the following contract
34       * concerning exceptions:
35       * </p>
36       * 
37       * <p>
38       * A {@link DisabledException} must be thrown if an account is disabled and
39       * the <code>AuthenticationManager</code> can test for this state.
40       * </p>
41       * 
42       * <p>
43       * A {@link LockedException} must be thrown if an account is locked and the
44       * <code>AuthenticationManager</code> can test for account locking.
45       * </p>
46       * 
47       * <p>
48       * A {@link BadCredentialsException} must be thrown if incorrect
49       * credentials are presented. Whilst the above exceptions are optional, an
50       * <code>AuthenticationManager</code> must <B>always</B> test credentials.
51       * </p>
52       * 
53       * <p>
54       * Exceptions should be tested for and if applicable thrown in the order
55       * expressed above (ie if an account is disabled or locked, the
56       * authentication request is immediately rejected and the credentials
57       * testing process is not performed). This prevents credentials being
58       * tested against  disabled or locked accounts.
59       * </p>
60       *
61       * @param authentication the authentication request object
62       *
63       * @return a fully authenticated object including credentials
64       *
65       * @throws AuthenticationException if authentication fails
66       */
67      public Authentication authenticate(Authentication authentication)
68          throws AuthenticationException;
69  }