Package org.apache.shiro.realm

Class AuthenticatingRealm

  • All Implemented Interfaces:
    LogoutAware, CacheManagerAware, Realm, Initializable, Nameable
    Direct Known Subclasses:
    AuthorizingRealm
    public abstract class AuthenticatingRealm
extends CachingRealm
implements Initializable
    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.

    Authentication Caching

    For applications that perform frequent repeated authentication of the same accounts (e.g. as is often done in REST or Soap applications that authenticate on every request), it might be prudent to enable authentication caching to alleviate constant load on any back-end data sources.

    This feature is disabled by default to retain backwards-compatibility with Shiro 1.1 and earlier. It may be enabled by setting authenticationCachingEnabled = true (and configuring Shiro with a CacheManager of course), but NOTE:

    ONLY enable authentication caching if either of the following is true for your realm implementation:

    • The doGetAuthenticationInfo implementation returns AuthenticationInfo instances where the credentials are securely obfuscated and NOT plaintext (raw) credentials. For example, if your realm references accounts with passwords, that the AuthenticationInfo's credentials are safely hashed and salted or otherwise fully encrypted.

    • The doGetAuthenticationInfo implementation returns AuthenticationInfo instances where the credentials are plaintext (raw) AND the cache region storing the AuthenticationInfo instances WILL NOT overflow to disk and WILL NOT transmit cache entries over an unprotected (non TLS/SSL) network (as might be the case with a networked/distributed enterprise cache). This should be the case even in private/trusted/corporate networks.

    These points are very important because if authentication caching is enabled, this abstract class implementation will place AuthenticationInfo instances returned from the subclass implementations directly into the cache, for example: 

     cache.put(cacheKey, subclassAuthenticationInfoInstance);

    Enabling authentication caching is ONLY safe to do if the above two scenarios apply. It is NOT safe to enable under any other scenario.

    When possible, always represent and store credentials in a safe form (hash+salt or encrypted) to eliminate plaintext visibility.

    Authentication Cache Invalidation on Logout

    If authentication caching is enabled, this implementation will attempt to evict (remove) cached authentication data for an account during logout. This can only occur if the getAuthenticationCacheKey(org.apache.shiro.authc.AuthenticationToken) and getAuthenticationCacheKey(org.apache.shiro.subject.PrincipalCollection) methods return the exact same value.

    The default implementations of these methods expect that the AuthenticationToken.getPrincipal() (what the user submits during login) and getAvailablePrincipal (what is returned by the realm after account lookup) return the same exact value. For example, the user submitted username is also the primary account identifier.

    However, if your application uses, say, a username for end-user login, but returns a primary key ID as the primary principal after authentication, then you will need to override either getAuthenticationCacheKey(token) or getAuthenticationCacheKey(principals) (or both) to ensure that the same cache key can be used for either object.

    This guarantees that the same cache key used to cache the data during authentication (derived from the AuthenticationToken) will be used to remove the cached data during logout (derived from the PrincipalCollection).

    Unmatching Cache Key Values

    If the return values from getAuthenticationCacheKey(org.apache.shiro.authc.AuthenticationToken) and getAuthenticationCacheKey(org.apache.shiro.subject.PrincipalCollection) are not identical, cached authentication data removal is at the mercy of your cache provider settings. For example, often cache implementations will evict cache entries based on a timeToIdle or timeToLive (TTL) value.

    If this lazy eviction capability of the cache product is not sufficient and you want discrete behavior (highly recommended for authentication data), ensure that the return values from those two methods are identical in the subclass implementation.

    Since:
    0.2