org.springframework.security.core.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
*
* https://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.springframework.security.core;
import java.io.Serializable;
import java.security.Principal;
import java.util.Collection;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.core.context.SecurityContextHolder;
/**
* Represents the token for an authentication request or for an authenticated principal
* once the request has been processed by the
* {@link AuthenticationManager#authenticate(Authentication)} method.
*
* Once the request has been authenticated, the Authentication will usually be
* stored in a thread-local SecurityContext managed by the
* {@link SecurityContextHolder} by the authentication mechanism which is being used. An
* explicit authentication can be achieved, without using one of Spring Security's
* authentication mechanisms, by creating an Authentication instance and using
* the code:
*
*
* SecurityContextHolder.getContext().setAuthentication(anAuthentication);
*
*
* Note that unless the Authentication has the authenticated property
* set to true, it will still be authenticated by any security interceptor (for
* method or web invocations) which encounters it.
*
* In most cases, the framework transparently takes care of managing the security context
* and authentication objects for you.
*
* @author Ben Alex
*/
public interface Authentication extends Principal, Serializable {
/**
* 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 collection array
* do not affect the state of the Authentication object, or use an unmodifiable
* instance.
*
* @return the authorities granted to the principal, or an empty collection if the
* token has not been authenticated. Never null.
*/
Collection 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
*/
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
*/
Object getDetails();
/**
* The identity of the principal being authenticated. In the case of an authentication
* request with username and password, this would be the username. Callers are
* expected to populate the principal for an authentication request.
*
* The AuthenticationManager implementation will often return an
* Authentication containing richer information as the principal for use by
* the application. Many of the authentication providers will create a
* {@code UserDetails} object as the principal.
* @return the Principal being authenticated or the authenticated
* principal after authentication.
*/
Object getPrincipal();
/**
* Used to indicate to {@code 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 from 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 present the token to the
* AuthenticationManager again for re-authentication.
*/
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()}
*/
void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException;
}