org.apache.shiro.authc.pam
Interface AuthenticationStrategy

All Known Implementing Classes:
AbstractAuthenticationStrategy, AllSuccessfulStrategy, AtLeastOneSuccessfulStrategy, FirstSuccessfulStrategy

public interface AuthenticationStrategy

A AuthenticationStrategy implementation assists the ModularRealmAuthenticator during the log-in process in a pluggable realm (PAM) environment.

The ModularRealmAuthenticator will consult implementations of this interface on what to do during each interaction with the configured Realms. This allows a pluggable strategy of whether or not an authentication attempt must be successful for all realms, only 1 or more realms, no realms, etc.

Since:
0.2
See Also:
AllSuccessfulStrategy, AtLeastOneSuccessfulStrategy, FirstSuccessfulStrategy

Method Summary
 AuthenticationInfo afterAllAttempts(AuthenticationToken token, AuthenticationInfo aggregate)
          Method invoked by the ModularAuthenticator signifying that all of its configured Realms have been consulted for account data, allowing post-proccessing after all realms have completed.
 AuthenticationInfo afterAttempt(Realm realm, AuthenticationToken token, AuthenticationInfo singleRealmInfo, AuthenticationInfo aggregateInfo, Throwable t)
          Method invoked by the ModularAuthenticator just after the given realm has been consulted for authentication, allowing post-authentication-attempt logic for that realm only.
 AuthenticationInfo beforeAllAttempts(Collection<? extends Realm> realms, AuthenticationToken token)
          Method invoked by the ModularAuthenticator signifying that the authentication process is about to begin for the specified token - called before any Realm is actually invoked.
 AuthenticationInfo beforeAttempt(Realm realm, AuthenticationToken token, AuthenticationInfo aggregate)
          Method invoked by the ModularAuthenticator just prior to the realm being consulted for account data, allowing pre-authentication-attempt logic for that realm only.
 

Method Detail

beforeAllAttempts

AuthenticationInfo beforeAllAttempts(Collection<? extends Realm> realms,
                                     AuthenticationToken token)
                                     throws AuthenticationException
Method invoked by the ModularAuthenticator signifying that the authentication process is about to begin for the specified token - called before any Realm is actually invoked.

The AuthenticationInfo object returned from this method is essentially an empty place holder for aggregating account data across multiple realms. It should be populated by the strategy implementation over the course of authentication attempts across the multiple realms. It will be passed into the beforeAttempt(org.apache.shiro.realm.Realm, org.apache.shiro.authc.AuthenticationToken, org.apache.shiro.authc.AuthenticationInfo) calls, allowing inspection of the aggregated account data up to that point in the multi-realm authentication, allowing any logic to be executed accordingly.

Parameters:
realms - the Realms that will be consulted during the authentication process for the specified token.
token - the Principal/Credential representation to be used during authentication for a corresponding subject.
Returns:
an empty AuthenticationInfo object that will populated with data from multiple realms.
Throws:
AuthenticationException - if the strategy implementation does not wish the Authentication attempt to execute.

beforeAttempt

AuthenticationInfo beforeAttempt(Realm realm,
                                 AuthenticationToken token,
                                 AuthenticationInfo aggregate)
                                 throws AuthenticationException
Method invoked by the ModularAuthenticator just prior to the realm being consulted for account data, allowing pre-authentication-attempt logic for that realm only.

This method returns an AuthenticationInfo object that will be used for further interaction with realms. Most implementations will merely return the aggregate method argument if they don't have a need to manipulate it.

Parameters:
realm - the realm that will be consulted for AuthenticationInfo for the specified token.
token - the AuthenticationToken submitted for the subject attempting system log-in.
aggregate - the aggregated AuthenticationInfo object being used across the multi-realm authentication attempt
Returns:
the AuthenticationInfo object that will be presented to further realms in the authentication process - returning the aggregate method argument is the normal case if no special action needs to be taken.
Throws:
AuthenticationException - an exception thrown by the Strategy implementation if it wishes the login process for the associated subject (user) to stop immediately.

afterAttempt

AuthenticationInfo afterAttempt(Realm realm,
                                AuthenticationToken token,
                                AuthenticationInfo singleRealmInfo,
                                AuthenticationInfo aggregateInfo,
                                Throwable t)
                                throws AuthenticationException
Method invoked by the ModularAuthenticator just after the given realm has been consulted for authentication, allowing post-authentication-attempt logic for that realm only.

This method returns an AuthenticationInfo object that will be used for further interaction with realms. Most implementations will merge the singleRealmInfo into the aggregateInfo and just return the aggregateInfo for continued use throughout the authentication process.

Parameters:
realm - the realm that was just consulted for AuthenticationInfo for the given token.
token - the AuthenticationToken submitted for the subject attempting system log-in.
singleRealmInfo - the info returned from a single realm.
aggregateInfo - the aggregate info representing all realms in a multi-realm environment.
t - the Throwable thrown by the Realm during the attempt, or null if the method returned normally.
Returns:
the AuthenticationInfo object that will be presented to further realms in the authentication process - returning the aggregateAccount method argument is the normal case if no special action needs to be taken.
Throws:
AuthenticationException - an exception thrown by the Strategy implementation if it wishes the login process for the associated subject (user) to stop immediately.

afterAllAttempts

AuthenticationInfo afterAllAttempts(AuthenticationToken token,
                                    AuthenticationInfo aggregate)
                                    throws AuthenticationException
Method invoked by the ModularAuthenticator signifying that all of its configured Realms have been consulted for account data, allowing post-proccessing after all realms have completed.

Returns the final AuthenticationInfo object that will be returned from the Authenticator to the authenticate() caller. This is most likely the aggregate AuthenticationInfo object that has been populated by many realms, but the actual return value is always up to the implementation.

Parameters:
token - the AuthenticationToken submitted for the subject attempting system log-in.
aggregate - the aggregate AuthenticationInfo instance populated by all realms during the log-in attempt.
Returns:
the final AuthenticationInfo object to return to the Authenticator.authenticate() caller.
Throws:
AuthenticationException - if the Strategy implementation wishes to fail the authentication attempt.


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.