| Clover coverage report - Acegi Security System for Spring - 1.0.0-RC1 |
|
 |
|
|||||||||||||||||||
| Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
| Authentication.java | - | - | - | - |
|
||||||||||||||
| 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 | } |
|
||||||||||
