This implementation attempts to acquire an authentication cache if one is not already configured.
Asserts that the submitted {@code AuthenticationToken}'s credentials match the stored account {@code AuthenticationInfo}'s credentials, and if not,{@link AuthenticationException}.
Clears out the AuthenticationInfo cache entry for the specified account. <p/> This method is provided as a convenience to subclasses so they can invalidate a cache entry when they change an account's authentication data (e.g. reset password) during runtime. Because an account's AuthenticationInfo can be cached, there needs to be a way to invalidate the cache for only that account so that subsequent authentication operations don't used the (old) cached value if account data changes. <p/> After this method is called, the next authentication for that same account will result in a call to {@link #doGetAuthenticationInfo(hunt.shiro.authc.AuthenticationToken) doGetAuthenticationInfo}, and the resulting return value will be cached before being returned so it can be reused for later authentications. <p/> If you wish to clear out all associated cached data (and not just authentication data), use the {@link #clearCache(hunt.shiro.subject.PrincipalCollection)} method instead (which will in turn call this method by default).
This implementation clears out any cached authentication data by calling {@link #clearCachedAuthenticationInfo(hunt.shiro.subject.PrincipalCollection)}. If overriding in a subclass, be sure to call {@code super.doClearCache} to ensure this behavior is maintained.
Retrieves authentication data from an implementation-specific datasource (RDBMS, LDAP, etc) for the given authentication token. <p/> 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. <p/> A {@code null} return value means that no account could be associated with the specified token.
Returns a {@link Cache} instance to use for authentication caching, or {@code null} if no cache has been set.
Returns the key under which {@link AuthenticationInfo} instances are cached if authentication caching is enabled. This implementation defaults to returning the token's {@link hunt.shiro.authc.AuthenticationToken#getPrincipal() principal}, which is usually a username in most applications. <h3>Cache Invalidation on Logout</h3> <b>NOTE:</b> If you want to be able to invalidate an account's cached {@code AuthenticationInfo} on logout, you must ensure the {@link #getAuthenticationCacheKey(hunt.shiro.subject.PrincipalCollection)} method returns the same value as this method.
Returns the key under which {@link AuthenticationInfo} instances are cached if authentication caching is enabled. This implementation delegates to {@link #getAvailablePrincipal(hunt.shiro.subject.PrincipalCollection)}, which returns the primary principal associated with this particular Realm. <h3>Cache Invalidation on Logout</h3> <b>NOTE:</b> If you want to be able to invalidate an account's cached {@code AuthenticationInfo} on logout, you must ensure that this method returns the same value as the {@link #getAuthenticationCacheKey(hunt.shiro.authc.AuthenticationToken)} method!
Returns the name of a {@link Cache} to lookup from any available {@link #getCacheManager() cacheManager} if a cache is not explicitly configured via {@link #setAuthenticationCache(hunt.shiro.cache.Cache)}. <p/> This name will only be used to look up a cache if authentication caching is {@link #isAuthenticationCachingEnabled() enabled}. <p/> <b>WARNING:</b> Only set this property if safe caching conditions apply, as documented at the top of this page in the class-level JavaDoc.
This implementation functions as follows: <ol> <li>It attempts to acquire any cached {@link AuthenticationInfo} corresponding to the specified {@link AuthenticationToken} argument. If a cached value is found, it will be used for credentials matching, alleviating the need to perform any lookups with a data source.</li> <li>If there is no cached {@link AuthenticationInfo} found, delegate to the {@link #doGetAuthenticationInfo(hunt.shiro.authc.AuthenticationToken)} method to perform the actual lookup. If authentication caching is enabled and possible, any returned info object will be {@link #cacheAuthenticationInfoIfPossible(hunt.shiro.authc.AuthenticationToken, hunt.shiro.authc.AuthenticationInfo) cached} to be used in future authentication attempts.</li> <li>If an AuthenticationInfo instance is not found in the cache or by lookup, {@code null} is returned to indicate an account cannot be found.</li> <li>If an AuthenticationInfo instance is found (either cached or via lookup), ensure the submitted AuthenticationToken's credentials match the expected {@code AuthenticationInfo}'s credentials using the {@link #getCredentialsMatcher() credentialsMatcher}. This means that credentials are always verified for an authentication attempt.</li> </ol>
Returns the authenticationToken class supported by this realm. <p/> <p>The default value is <tt>{@link hunt.shiro.authc.UsernamePasswordToken UsernamePasswordToken.class}</tt>, since about 90% of realms use username/password authentication, regardless of their protocol (e.g. over jdbc, ldap, kerberos, http, etc). <p/> <p>If subclasses haven't already overridden the {@link Realm#supports Realm.supports(AuthenticationToken)} method, they must {@link #setAuthenticationTokenClass(Class) set a new class} if they won't support <tt>UsernamePasswordToken</tt> authentication token submissions.
Returns the <code>CredentialsMatcher</code> used during an authentication attempt to verify submitted credentials with those stored in the system. <p/> <p>Unless overridden by the {@link #setCredentialsMatcher setCredentialsMatcher} method, the default value is a {@link hunt.shiro.authc.credential.SimpleCredentialsMatcher SimpleCredentialsMatcher} instance.
Initializes this realm and potentially enables an authentication cache, depending on configuration. Based on the availability of an authentication cache, this class functions as follows: <ol> <li>If the {@link #setAuthenticationCache cache} property has been set, it will be used to cache the AuthenticationInfo objects returned from {@link #getAuthenticationInfo} method invocations. All future calls to {@link #getAuthenticationInfo} will attempt to use this cache first to alleviate any potentially unnecessary calls to an underlying data store.</li> <li>If the {@link #setAuthenticationCache cache} property has <b>not</b> been set, the {@link #setCacheManager cacheManager} property will be checked. If a {@code cacheManager} has been set, it will be used to eagerly acquire an authentication {@code cache}, and this cache which will be used as specified in #1.</li> <li>If neither the {@link #setAuthenticationCache (hunt.shiro.cache.Cache) authenticationCache} or {@link #setCacheManager(hunt.shiro.cache.CacheManager) cacheManager} properties are set, caching will not be utilized and authentication look-ups will be delegated to subclass implementations for each authentication attempt.</li> </ol> <p/> This method finishes by calling {@link #onInit()} is to allow subclasses to perform any init behavior desired.
Returns {@code true} if authentication caching should be utilized if a {@link CacheManager} has been {@link #setCacheManager(hunt.shiro.cache.CacheManager) configured}, {@code false} otherwise. <p/> The default value is {@code true}.
Returns {@code true} if authentication caching should be utilized based on the specified {@link AuthenticationToken} and/or {@link AuthenticationInfo}, {@code false} otherwise. <p/> The default implementation simply delegates to {@link #isAuthenticationCachingEnabled()}, the general-case authentication caching setting. Subclasses can override this to turn on or off caching at runtime based on the specific submitted runtime values.
Template method for subclasses to implement any initialization logic. Called from {@link #init()}.
Sets an explicit {@link Cache} instance to use for authentication caching. If not set and authentication caching is {@link #isAuthenticationCachingEnabled() enabled}, any available {@link #getCacheManager() cacheManager} will be used to acquire the cache instance if available. <p/> <b>WARNING:</b> Only set this property if safe caching conditions apply, as documented at the top of this page in the class-level JavaDoc.
Sets the name of a {@link Cache} to lookup from any available {@link #getCacheManager() cacheManager} if a cache is not explicitly configured via {@link #setAuthenticationCache(hunt.shiro.cache.Cache)}. <p/> This name will only be used to look up a cache if authentication caching is {@link #isAuthenticationCachingEnabled() enabled}.
Sets whether or not authentication caching should be utilized if a {@link CacheManager} has been {@link #setCacheManager(hunt.shiro.cache.CacheManager) configured}, {@code false} otherwise. <p/> The default value is {@code false} to retain backwards compatibility with Shiro 1.1 and earlier. <p/> <b>WARNING:</b> Only set this property to {@code true} if safe caching conditions apply, as documented at the top of this page in the class-level JavaDoc.
Sets the authenticationToken class supported by this realm. <p/> <p>Unless overridden by this method, the default value is {@link hunt.shiro.authc.UsernamePasswordToken UsernamePasswordToken.class} to support the majority of applications.
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. <p/> <p>Unless overridden by this method, the default value is a {@link hunt.shiro.authc.credential.SimpleCredentialsMatcher} instance.
Convenience implementation that returns <tt>getAuthenticationTokenClass().isAssignableFrom( token.getClass() );</tt>. Can be overridden by subclasses for more complex token checking. <p>Most configurations will only need to set a different class via {@link #setAuthenticationTokenClass}, as opposed to overriding this method.
Returns the <tt>CacheManager</tt> used for data caching to reduce EIS round trips, or <tt>null</tt> if caching is disabled.
Sets the <tt>CacheManager</tt> to be used for data caching to reduce EIS round trips. <p/> This property is <tt>null</tt> by default, indicating that caching is turned off.
Returns {@code true} if caching should be used if a {@link CacheManager} has been {@link #setCacheManager(hunt.shiro.cache.CacheManager) configured}, {@code false} otherwise. <p/> The default value is {@code true} since the large majority of Realms will benefit from caching if a CacheManager has been configured. However, memory-only realms should set this value to {@code false} since they would manage account data in memory already lookups would already be as efficient as possible.
Sets whether or not caching should be used if a {@link CacheManager} has been {@link #setCacheManager(hunt.shiro.cache.CacheManager) configured}.
Template method that may be implemented by subclasses should they wish to react to a {@link CacheManager} instance being set on the realm instance via the {@link #setCacheManager(hunt.shiro.cache.CacheManager)} mutator.
If caching is enabled, this will clear any cached data associated with the specified account identity. Subclasses are free to override for additional behavior, but be sure to call {@code super.onLogout} first. <p/> This default implementation merely calls {@link #clearCache(hunt.shiro.subject.PrincipalCollection)}.
Clears out any cached data associated with the specified account identity/identities. <p/> This implementation will return quietly if the principals argument is null or empty. Otherwise it delegates to {@link #doClearCache(hunt.shiro.subject.PrincipalCollection)}.
This implementation does nothing - it is a template to be overridden by subclasses if necessary.
A utility method for subclasses that returns the first available principal of interest to this particular realm. The heuristic used to acquire the principal is as follows: <ul> <li>Attempt to get <em>this particular Realm's</em> 'primary' principal in the {@code PrincipalCollection} via a <code>principals.{@link PrincipalCollection#fromRealm(string) fromRealm}({@link #getName() getName()})</code> call.</li> <li>If the previous call does not result in any principals, attempt to get the overall 'primary' principal from the PrincipalCollection via {@link hunt.shiro.subject.PrincipalCollection#getPrimaryPrincipal()}.</li> <li>If there are no principals from that call (or the PrincipalCollection argument was null to begin with), return {@code null}</li> </ul>
Initializes this object.
<pre> cache.put(cacheKey, subclassAuthenticationInfoInstance); </pre> <p/> Enabling authentication caching is ONLY safe to do if the above two scenarios apply. It is NOT safe to enable under any other scenario. <p/> When possible, always represent and store credentials in a safe form (hash+salt or encrypted) to eliminate plaintext visibility. <h3>Authentication Cache Invalidation on Logout</h3> 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 {@link #getAuthenticationCacheKey(hunt.shiro.authc.AuthenticationToken)} and {@link #getAuthenticationCacheKey(hunt.shiro.subject.PrincipalCollection)} methods return the exact same value. <p/> The default implementations of these methods expect that the {@link hunt.shiro.authc.AuthenticationToken#getPrincipal()} (what the user submits during login) and {@link #getAvailablePrincipal(hunt.shiro.subject.PrincipalCollection) 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. <p/> 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 {@link #getAuthenticationCacheKey(hunt.shiro.authc.AuthenticationToken) getAuthenticationCacheKey(token)} or {@link #getAuthenticationCacheKey(hunt.shiro.subject.PrincipalCollection) getAuthenticationCacheKey(principals)} (or both) to ensure that the same cache key can be used for either object. <p/> This guarantees that the same cache key used to cache the data during authentication (derived from the {@code AuthenticationToken}) will be used to remove the cached data during logout (derived from the {@code PrincipalCollection}). <h4>Unmatching Cache Key Values</h4> If the return values from {@link #getAuthenticationCacheKey(hunt.shiro.authc.AuthenticationToken)} and {@link #getAuthenticationCacheKey(hunt.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. <p/> 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.
A top-level abstract implementation of the <tt>Realm</tt> interface that only implements authentication support (log-in) operations and leaves authorization (access control) behavior to subclasses. <h2>Authentication Caching</h2> 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. <p/> This feature is disabled by default to retain backwards-compatibility with Shiro 1.1 and earlier. It may be enabled by setting {@link #setAuthenticationCachingEnabled(bool) authenticationCachingEnabled} = {@code true} (and configuring Shiro with a {@link CacheManager} of course), but <b>NOTE:</b> <p/> <b>ONLY enable authentication caching if either of the following is true for your realm implementation:</b> <ul> <li>The {@link #doGetAuthenticationInfo(hunt.shiro.authc.AuthenticationToken) doGetAuthenticationInfo} implementation returns {@code AuthenticationInfo} instances where the {@link hunt.shiro.authc.AuthenticationInfo#getCredentials() credentials} are securely obfuscated and NOT plaintext (raw) credentials. For example, if your realm references accounts with passwords, that the {@code AuthenticationInfo}'s {@link hunt.shiro.authc.AuthenticationInfo#getCredentials() credentials} are safely hashed and salted or otherwise fully encrypted.<br/><br/></li> <li>The {@link #doGetAuthenticationInfo(hunt.shiro.authc.AuthenticationToken) doGetAuthenticationInfo} implementation returns {@code AuthenticationInfo} instances where the {@link hunt.shiro.authc.AuthenticationInfo#getCredentials() credentials} are plaintext (raw) <b>AND</b> the cache region storing the {@code 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.</li> </ul> <p/> 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