org.acegisecurity.Authentication Maven / Gradle / Ivy
/* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.acegisecurity;
import java.io.Serializable;
import java.security.Principal;
/**
* Represents an authentication request.
*
*
* An Authentication object is not considered authenticated until
* it is processed by an {@link AuthenticationManager}.
*
*
*
* Stored in a request {@link org.acegisecurity.context.SecurityContext}.
*
*
* @author Ben Alex
* @version $Id: Authentication.java 1519 2006-05-29 15:06:32Z benalex $
*/
public interface Authentication extends Principal, Serializable {
//~ Methods ========================================================================================================
/**
* Set by an AuthenticationManager to indicate the authorities that the principal has been
* granted. Note that classes should not rely on this value as being valid unless it has been set by a trusted
* AuthenticationManager.Implementations should ensure that modifications to the returned
* array do not affect the state of the Authentication object (e.g. by returning an array copy).
*
* @return the authorities granted to the principal, or null if authentication has not been completed
*/
public GrantedAuthority[] getAuthorities();
/**
* The credentials that prove the principal is correct. This is usually a password, but could be anything
* relevant to the AuthenticationManager. Callers are expected to populate the credentials.
*
* @return the credentials that prove the identity of the Principal
*/
public Object getCredentials();
/**
* Stores additional details about the authentication request. These might be an IP address, certificate
* serial number etc.
*
* @return additional details about the authentication request, or null if not used
*/
public Object getDetails();
/**
* The identity of the principal being authenticated. This is usually a username. Callers are expected to
* populate the principal.
*
* @return the Principal being authenticated
*/
public Object getPrincipal();
/**
* Used to indicate to AbstractSecurityInterceptor whether it should present the
* authentication token to the AuthenticationManager. Typically an AuthenticationManager
* (or, more often, one of its AuthenticationProviders) will return an immutable authentication token
* after successful authentication, in which case that token can safely return true to this method.
* Returning true will improve performance, as calling the AuthenticationManager for
* every request will no longer be necessary.For security reasons, implementations of this interface
* should be very careful about returning true to this method unless they are either immutable, or
* have some way of ensuring the properties have not been changed since original creation.
*
* @return true if the token has been authenticated and the AbstractSecurityInterceptor does not need
* to represent the token for re-authentication to the AuthenticationManager
*/
public boolean isAuthenticated();
/**
* See {@link #isAuthenticated()} for a full description.Implementations should always allow this
* method to be called with a false parameter, as this is used by various classes to specify the
* authentication token should not be trusted. If an implementation wishes to reject an invocation with a
* true parameter (which would indicate the authentication token is trusted - a potential security
* risk) the implementation should throw an {@link IllegalArgumentException}.
*
* @param isAuthenticated true if the token should be trusted (which may result in an exception) or
* false if the token should not be trusted
*
* @throws IllegalArgumentException if an attempt to make the authentication token trusted (by passing
* true as the argument) is rejected due to the implementation being immutable or
* implementing its own alternative approach to {@link #isAuthenticated()}
*/
public void setAuthenticated(boolean isAuthenticated)
throws IllegalArgumentException;
}