org.apache.shiro.realm
Class AuthenticatingRealm

java.lang.Object
  org.apache.shiro.realm.CachingRealm
      org.apache.shiro.realm.AuthenticatingRealm

All Implemented Interfaces:

LogoutAware, Authorizer, CacheManagerAware, Realm, Nameable

Direct Known Subclasses:

AuthorizingRealm

public abstract class AuthenticatingRealm
extends CachingRealm
implements LogoutAware

A top-level abstract implementation of the Realm interface that only implements authentication support (log-in) operations and leaves authorization (access control) behavior to subclasses.

Since a Realm provides both authentication and authorization operations, the implementation approach for this class could have been reversed. That is, authorization support could have been implemented here and authentication support left to subclasses.

The reason the existing implementation is in place though (authentication support) is that most authentication operations are fairly common across the large majority of applications, whereas authorization operations are more so heavily dependent upon the application's data model, which can vary widely.

By providing the most common authentication operations here and leaving data-model specific authorization checks to subclasses, a top-level abstract class for most common authentication behavior is more useful as an extension point for most applications.

Since:

0.2

Author:

Les Hazlewood, Jeremy Haile

Constructor Summary

AuthenticatingRealm()

AuthenticatingRealm(CacheManager cacheManager)

AuthenticatingRealm(CacheManager cacheManager, CredentialsMatcher matcher)

AuthenticatingRealm(CredentialsMatcher matcher)

Method Summary

protected abstract AuthenticationInfo	doGetAuthenticationInfo(AuthenticationToken token) Retrieves authentication data from an implementation-specific datasource (RDBMS, LDAP, etc) for the given authentication token.
AuthenticationInfo	getAuthenticationInfo(AuthenticationToken token) Returns an account's authentication-specific information for the specified token, or null if no account could be found based on the token.
Class	getAuthenticationTokenClass() Returns the authenticationToken class supported by this realm.
CredentialsMatcher	getCredentialsMatcher() Returns the CredentialsMatcher used during an authentication attempt to verify submitted credentials with those stored in the system.
void	onLogout(PrincipalCollection principals) Default implementation that does nothing (no-op) and exists as a convenience mechanism in case subclasses wish to override it to implement realm-specific logout logic for the given user account logging out.
void	setAuthenticationTokenClass(Class<? extends AuthenticationToken> authenticationTokenClass) Sets the authenticationToken class supported by this realm.
void	setCredentialsMatcher(CredentialsMatcher credentialsMatcher) Sets the CrendialsMatcher used during an authentication attempt to verify submitted credentials with those stored in the system.
boolean	supports(AuthenticationToken token) Convenience implementation that returns getAuthenticationTokenClass().isAssignableFrom( token.getClass() );.

Methods inherited from class org.apache.shiro.realm.CachingRealm

afterCacheManagerSet, getCacheManager, getName, isCachingEnabled, setCacheManager, setCachingEnabled, setName

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.shiro.authz.Authorizer

checkPermission, checkPermission, checkPermissions, checkPermissions, checkRole, checkRoles, hasAllRoles, hasRole, hasRoles, isPermitted, isPermitted, isPermitted, isPermitted, isPermittedAll, isPermittedAll

Constructor Detail

AuthenticatingRealm

public AuthenticatingRealm()

AuthenticatingRealm

public AuthenticatingRealm(CacheManager cacheManager)

AuthenticatingRealm

public AuthenticatingRealm(CredentialsMatcher matcher)

AuthenticatingRealm

public AuthenticatingRealm(CacheManager cacheManager,
                           CredentialsMatcher matcher)

Method Detail

getCredentialsMatcher

public CredentialsMatcher getCredentialsMatcher()

Returns the CredentialsMatcher used during an authentication attempt to verify submitted credentials with those stored in the system.

Unless overridden by the setCredentialsMatcher method, the default value is a SimpleCredentialsMatcher instance.

Returns:

the CredentialsMatcher used during an authentication attempt to verify submitted credentials with those stored in the system.

setCredentialsMatcher

public void setCredentialsMatcher(CredentialsMatcher credentialsMatcher)

Sets the CrendialsMatcher used during an authentication attempt to verify submitted credentials with those stored in the system. The implementation of this matcher can be switched via configuration to support any number of schemes, including plain text comparisons, hashing comparisons, and others.

Unless overridden by this method, the default value is a SimpleCredentialsMatcher instance.

Parameters:

credentialsMatcher - the matcher to use.

getAuthenticationTokenClass

public Class getAuthenticationTokenClass()

Returns the authenticationToken class supported by this realm.

The default value is UsernamePasswordToken.class, since about 90% of realms use username/password authentication, regardless of their protocol (e.g. over jdbc, ldap, kerberos, http, etc).

If subclasses haven't already overridden the Realm.supports(AuthenticationToken) method, they must set a new class if they won't support UsernamePasswordToken authentication token submissions.

Returns:

the authenticationToken class supported by this realm.

See Also:

setAuthenticationTokenClass(java.lang.Class)

setAuthenticationTokenClass

public void setAuthenticationTokenClass(Class<? extends AuthenticationToken> authenticationTokenClass)

Sets the authenticationToken class supported by this realm.

Unless overridden by this method, the default value is UsernamePasswordToken.class to support the majority of applications.

Parameters:

authenticationTokenClass - the class of authentication token instances supported by this realm.

See Also:

getAuthenticationTokenClass() for more explanation.

supports

public boolean supports(AuthenticationToken token)

Convenience implementation that returns getAuthenticationTokenClass().isAssignableFrom( token.getClass() );. Can be overridden by subclasses for more complex token checking.

Most configurations will only need to set a different class via setAuthenticationTokenClass(java.lang.Class), as opposed to overriding this method.

Specified by:

supports in interface Realm

Parameters:

token - the token being submitted for authentication.

Returns:

true if this authentication realm can process the submitted token instance of the class, false otherwise.

getAuthenticationInfo

public final AuthenticationInfo getAuthenticationInfo(AuthenticationToken token)
                                               throws AuthenticationException

Description copied from interface: Realm

Returns an account's authentication-specific information for the specified token, or null if no account could be found based on the token.

This method effectively represents a login attempt for the corresponding user with the underlying EIS datasource. Most implementations merely just need to lookup and return the account data only (as the method name implies) and let Shiro do the rest, but implementations may of course perform eis specific login operations if so desired.

Specified by:

getAuthenticationInfo in interface Realm

Parameters:

token - the application-specific representation of an account principal and credentials.

Returns:

the authentication information for the account associated with the specified token, or null if no account could be found.

Throws:

AuthenticationException - if there is an error obtaining or constructing an AuthenticationInfo object based on the specified token or implementation-specifc login behavior fails.

doGetAuthenticationInfo

protected abstract AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token)
                                                       throws AuthenticationException

Retrieves authentication data from an implementation-specific datasource (RDBMS, LDAP, etc) for the given authentication token.

For most datasources, this means just 'pulling' authentication data for an associated subject/user and nothing more and letting Shiro do the rest. But in some systems, this method could actually perform EIS specific log-in logic in addition to just retrieving data - it is up to the Realm implementation.

A null return value means that no account could be associated with the specified token.

Parameters:

token - the authentication token containing the user's principal and credentials.

Returns:

an AuthenticationInfo object containing account data resulting from the authentication ONLY if the lookup is successful (i.e. account exists and is valid, etc.)

Throws:

AuthenticationException - if there is an error acquiring data or performing realm-specific authentication logic for the specified token

onLogout

public void onLogout(PrincipalCollection principals)

Default implementation that does nothing (no-op) and exists as a convenience mechanism in case subclasses wish to override it to implement realm-specific logout logic for the given user account logging out.

In a single-realm Shiro configuration (most applications), the principals method argument will be the same as that which is contained in the AuthenticationInfo object returned by the doGetAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken) method (that is, info.getPrincipals()).

In a multi-realm Shiro configuration, the given principals method argument could contain principals returned by many realms. Therefore the subclass implementation would need to know how to extract the principal(s) relevant to only itself and ignore other realms' principals. This is usually done by calling principals.fromRealm(name), using the realm's own name.

Specified by:

onLogout in interface LogoutAware

Parameters:

principals - the application-specific Subject/user identifier that is logging out.