org.apache.shiro.authc
Class AbstractAuthenticator

java.lang.Object
  org.apache.shiro.authc.AbstractAuthenticator

All Implemented Interfaces:

Authenticator, LogoutAware

Direct Known Subclasses:

ModularRealmAuthenticator

public abstract class AbstractAuthenticator
extends Object
implements Authenticator, LogoutAware

Superclass for almost all Authenticator implementations that performs the common work around authentication attempts.

This class delegates the actual authentication attempt to subclasses but supports notification for successful and failed logins as well as logouts. Notification is sent to one or more registered AuthenticationListeners to allow for custom processing logic when these conditions occur.

In most cases, the only thing a subclass needs to do (via its doAuthenticate(org.apache.shiro.authc.AuthenticationToken) implementation) is perform the actual principal/credential verification process for the submitted AuthenticationToken.

Since:

0.1

Constructor Summary

AbstractAuthenticator()
Default no-argument constructor.

Method Summary

AuthenticationInfo	authenticate(AuthenticationToken token) Implementation of the Authenticator interface that functions in the following manner: Calls template doAuthenticate method for subclass execution of the actual authentication behavior. If an AuthenticationException is thrown during doAuthenticate, notify any registered AuthenticationListeners of the exception and then propogate the exception for the caller to handle. If no exception is thrown (indicating a successful login), notify any registered AuthenticationListeners of the successful attempt. Return the AuthenticationInfo
protected abstract AuthenticationInfo	doAuthenticate(AuthenticationToken token) Template design pattern hook for subclasses to implement specific authentication behavior.
Collection<AuthenticationListener>	getAuthenticationListeners() Returns the AuthenticationListeners that should be notified during authentication attempts.
protected void	notifyFailure(AuthenticationToken token, AuthenticationException ae) Notifies any registered AuthenticationListeners that authentication failed for the specified token which resulted in the specified ae exception.
protected void	notifyLogout(PrincipalCollection principals) Notifies any registered AuthenticationListeners that a Subject has logged-out.
protected void	notifySuccess(AuthenticationToken token, AuthenticationInfo info) Notifies any registered AuthenticationListeners that authentication was successful for the specified token which resulted in the specified info.
void	onLogout(PrincipalCollection principals) This implementation merely calls notifyLogout to allow any registered listeners to react to the logout.
void	setAuthenticationListeners(Collection<AuthenticationListener> listeners) Sets the AuthenticationListeners that should be notified during authentication attempts.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractAuthenticator

public AbstractAuthenticator()

Default no-argument constructor. Ensures the internal AuthenticationListener collection is a non-null ArrayList.

Method Detail

setAuthenticationListeners

public void setAuthenticationListeners(Collection<AuthenticationListener> listeners)

Sets the AuthenticationListeners that should be notified during authentication attempts.

Parameters:

listeners - one or more AuthenticationListeners that should be notified due to an authentication attempt.

getAuthenticationListeners

public Collection<AuthenticationListener> getAuthenticationListeners()

Returns the AuthenticationListeners that should be notified during authentication attempts.

Returns:

the AuthenticationListeners that should be notified during authentication attempts.

notifySuccess

protected void notifySuccess(AuthenticationToken token,
                             AuthenticationInfo info)

Notifies any registered AuthenticationListeners that authentication was successful for the specified token which resulted in the specified info. This implementation merely iterates over the internal listeners collection and calls onSuccess for each.

Parameters:

token - the submitted AuthenticationToken that resulted in a successful authentication.

info - the returned AuthenticationInfo resulting from the successful authentication.

notifyFailure

protected void notifyFailure(AuthenticationToken token,
                             AuthenticationException ae)

Notifies any registered AuthenticationListeners that authentication failed for the specified token which resulted in the specified ae exception. This implementation merely iterates over the internal listeners collection and calls onFailure for each.

Parameters:

token - the submitted AuthenticationToken that resulted in a failed authentication.

ae - the resulting AuthenticationException that caused the authentication to fail.

notifyLogout

protected void notifyLogout(PrincipalCollection principals)

Notifies any registered AuthenticationListeners that a Subject has logged-out. This implementation merely iterates over the internal listeners collection and calls onLogout for each.

Parameters:

principals - the identifying principals of the Subject/account logging out.

onLogout

public void onLogout(PrincipalCollection principals)

This implementation merely calls notifyLogout to allow any registered listeners to react to the logout.

Specified by:

onLogout in interface LogoutAware

Parameters:

principals - the identifying principals of the Subject/account logging out.

authenticate

public final AuthenticationInfo authenticate(AuthenticationToken token)
                                      throws AuthenticationException

Implementation of the Authenticator interface that functions in the following manner:

1. Calls template doAuthenticate method for subclass execution of the actual authentication behavior.
2. If an AuthenticationException is thrown during doAuthenticate, notify any registered AuthenticationListeners of the exception and then propogate the exception for the caller to handle.
3. If no exception is thrown (indicating a successful login), notify any registered AuthenticationListeners of the successful attempt.
4. Return the AuthenticationInfo

Specified by:

authenticate in interface Authenticator

Parameters:

token - the submitted token representing the subject's (user's) login principals and credentials.

Returns:

the AuthenticationInfo referencing the authenticated user's account data.

Throws:

AuthenticationException - if there is any problem during the authentication process - see the interface's JavaDoc for a more detailed explanation.

See Also:

ExpiredCredentialsException, IncorrectCredentialsException, ExcessiveAttemptsException, LockedAccountException, ConcurrentAccessException, UnknownAccountException

doAuthenticate

protected abstract AuthenticationInfo doAuthenticate(AuthenticationToken token)
                                              throws AuthenticationException

Template design pattern hook for subclasses to implement specific authentication behavior.

Common behavior for most authentication attempts is encapsulated in the authenticate(org.apache.shiro.authc.AuthenticationToken) method and that method invokes this one for custom behavior.

N.B. Subclasses should throw some kind of AuthenticationException if there is a problem during authentication instead of returning null. A null return value indicates a configuration or programming error, since AuthenticationExceptions should indicate any expected problem (such as an unknown account or username, or invalid password, etc).

Parameters:

token - the authentication token encapsulating the user's login information.

Returns:

an AuthenticationInfo object encapsulating the user's account information important to Shiro.

Throws:

AuthenticationException - if there is a problem logging in the user.