Clears out the AuthorizationInfo 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 authorization data (add/remove roles or permissions) during runtime. Because an account's AuthorizationInfo can be cached, there needs to be a way to invalidate the cache for only that account so that subsequent authorization operations don't used the (old) cached value if account data changes. <p/> After this method is called, the next authorization check for that same account will result in a call to {@link #getAuthorizationInfo(hunt.shiro.subject.PrincipalCollection) getAuthorizationInfo}, and the resulting return value will be cached before being returned so it can be reused for later authorization checks. <p/> If you wish to clear out all associated cached data (and not just authorization data), use the {@link #clearCache(hunt.shiro.subject.PrincipalCollection)} method instead (which will in turn call this method by default).
Calls {@code super.doClearCache} to ensure any cached authentication data is removed and then calls {@link #clearCachedAuthorizationInfo(hunt.shiro.subject.PrincipalCollection)} to remove any cached authorization data. <p/> If overriding in a subclass, be sure to call {@code super.doClearCache} to ensure this behavior is maintained.
Retrieves the AuthorizationInfo for the given principals from the underlying data store. When returning an instance from this method, you might want to consider using an instance of {@link hunt.shiro.authz.SimpleAuthorizationInfo SimpleAuthorizationInfo}, as it is suitable in most cases.
Returns an account's authorization-specific information for the specified {@code principals}, or {@code null} if no account could be found. The resulting {@code AuthorizationInfo} object is used by the other method implementations in this class to automatically perform access control checks for the corresponding {@code Subject}. <p/> This implementation obtains the actual {@code AuthorizationInfo} object from the subclass's implementation of {@link #doGetAuthorizationInfo(hunt.shiro.subject.PrincipalCollection) doGetAuthorizationInfo}, and then caches it for efficient reuse if caching is enabled (see below). <p/> Invocations of this method should be thought of as completely orthogonal to acquiring {@link #getAuthenticationInfo(hunt.shiro.authc.AuthenticationToken) authenticationInfo}, since either could occur in any order. <p/> For example, in "Remember Me" scenarios, the user identity is remembered (and assumed) for their current session and an authentication attempt during that session might never occur. But because their identity would be remembered, that is sufficient enough information to call this method to execute any necessary authorization checks. For this reason, authentication and authorization should be loosely coupled and not depend on each other. <h3>Caching</h3> The {@code AuthorizationInfo} values returned from this method are cached for efficient reuse if caching is enabled. Caching is enabled automatically when an {@link #setAuthorizationCache authorizationCache} instance has been explicitly configured, or if a {@link #setCacheManager cacheManager} has been configured, which will be used to lazily create the {@code authorizationCache} as needed. <p/> If caching is enabled, the authorization cache will be checked first and if found, will return the cached {@code AuthorizationInfo} immediately. If caching is disabled, or there is a cache miss, the authorization info will be looked up from the underlying data store via the {@link #doGetAuthorizationInfo(hunt.shiro.subject.PrincipalCollection)} method, which must be implemented by subclasses. <h4>Changed Data</h4> If caching is enabled and if any authorization data for an account is changed at runtime, such as adding or removing roles and/or permissions, the subclass implementation should clear the cached AuthorizationInfo for that account via the {@link #clearCachedAuthorizationInfo(hunt.shiro.subject.PrincipalCollection) clearCachedAuthorizationInfo} method. This ensures that the next call to {@code getAuthorizationInfo(PrincipalCollection)} will acquire the account's fresh authorization data, where it will then be cached for efficient reuse. This ensures that stale authorization data will not be reused.
Returns {@code true} if authorization 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}.
Initializes this realm and potentially enables a cache, depending on configuration. <p/> When this method is called, the following logic is executed: <ol> <li>If the {@link #setAuthorizationCache cache} property has been set, it will be used to cache the AuthorizationInfo objects returned from {@link #getAuthorizationInfo} method invocations. All future calls to {@code getAuthorizationInfo} will attempt to use this cache first to alleviate any potentially unnecessary calls to an underlying data store.</li> <li>If the {@link #setAuthorizationCache 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 create an authorization {@code cache}, and this newly created cache which will be used as specified in #1.</li> <li>If neither the {@link #setAuthorizationCache (hunt.shiro.cache.Cache) cache} or {@link #setCacheManager(hunt.shiro.cache.CacheManager) cacheManager} properties are set, caching will be disabled and authorization look-ups will be delegated to subclass implementations for each authorization check.</li> </ol>
Sets whether or not authorization 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 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.
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.
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.
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 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.
Returns a {@link Cache} instance to use for authentication caching, or {@code null} if no cache has been set.
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.
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}.
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}.
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.
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.
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.
Template method for subclasses to implement any initialization logic. Called from {@link #init()}.
This implementation attempts to acquire an authentication cache if one is not already configured.
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.
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>
Asserts that the submitted {@code AuthenticationToken}'s credentials match the stored account {@code AuthenticationInfo}'s credentials, and if not,{@link AuthenticationException}.
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!
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.
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).
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.
An {@code AuthorizingRealm} extends the {@code AuthenticatingRealm}'s capabilities by adding Authorization (access control) support. <p/> This implementation will perform all role and permission checks automatically (and subclasses do not have to write this logic) as long as the {@link #getAuthorizationInfo(hunt.shiro.subject.PrincipalCollection)} method returns an {@link AuthorizationInfo}. Please see that method's JavaDoc for an in-depth explanation. <p/> If you find that you do not want to utilize the {@link AuthorizationInfo AuthorizationInfo} construct, you are of course free to subclass the {@link AuthenticatingRealm AuthenticatingRealm} directly instead and implement the remaining Realm interface methods directly. You might do this if you want have better control over how the Role and Permission checks occur for your specific data source. However, using AuthorizationInfo (and its default implementation {@link hunt.shiro.authz.SimpleAuthorizationInfo SimpleAuthorizationInfo}) is sufficient in the large majority of Realm cases.
@see hunt.shiro.authz.SimpleAuthorizationInfo