Class AuthorizingRealm

java.lang.Object
org.apache.shiro.realm.CachingRealm
org.apache.shiro.realm.AuthenticatingRealm
org.apache.shiro.realm.AuthorizingRealm
All Implemented Interfaces:
LogoutAware, Authorizer, PermissionResolverAware, RolePermissionResolverAware, org.apache.shiro.cache.CacheManagerAware, org.apache.shiro.lang.util.Initializable, org.apache.shiro.lang.util.Nameable, Realm
Direct Known Subclasses:
AbstractLdapRealm, DefaultLdapRealm, JdbcRealm, SimpleAccountRealm
public abstract class AuthorizingRealm extends AuthenticatingRealm implements Authorizer, org.apache.shiro.lang.util.Initializable, PermissionResolverAware, RolePermissionResolverAware
An AuthorizingRealm extends the AuthenticatingRealm's capabilities by adding Authorization (access control) support.

This implementation will perform all role and permission checks automatically (and subclasses do not have to write this logic) as long as the getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) method returns an AuthorizationInfo. Please see that method's JavaDoc for an in-depth explanation.

If you find that you do not want to utilize the AuthorizationInfo construct, you are of course free to subclass the AuthenticatingRealm directly instead and implement the remaining Realm interface methods directly. You might do this if you want to have better control over how the Role and Permission checks occur for your specific data source. However, using AuthorizationInfo (and its default implementation SimpleAuthorizationInfo) is sufficient in the large majority of Realm cases.

Since:
0.2
See Also:

  • Constructor Details

  • Method Details

    • setName

      public void setName(String name)
      Specified by:
      setName in interface org.apache.shiro.lang.util.Nameable
      Overrides:
      setName in class AuthenticatingRealm

    • setAuthorizationCache

      public void setAuthorizationCache(org.apache.shiro.cache.Cache<Object,AuthorizationInfo> authorizationCache)

    • getAuthorizationCache

      public org.apache.shiro.cache.Cache<Object,AuthorizationInfo> getAuthorizationCache()

    • getAuthorizationCacheName

      public String getAuthorizationCacheName()

    • setAuthorizationCacheName

      public void setAuthorizationCacheName(String authorizationCacheName)

    • isAuthorizationCachingEnabled

      public boolean isAuthorizationCachingEnabled()
      Returns true if authorization caching should be utilized if a CacheManager has been configured, false otherwise.

      The default value is true.

      Returns:
      true if authorization caching should be utilized, false otherwise.

    • setAuthorizationCachingEnabled

      public void setAuthorizationCachingEnabled(boolean authorizationCachingEnabled)
      Sets whether or not authorization caching should be utilized if a CacheManager has been configured, false otherwise.

      The default value is true.

      Parameters:
      authorizationCachingEnabled - the value to set

    • getPermissionResolver

      public PermissionResolver getPermissionResolver()

    • setPermissionResolver

      public void setPermissionResolver(PermissionResolver permissionResolver)
      Description copied from interface: PermissionResolverAware
      Sets the specified PermissionResolver on this instance.
      Specified by:
      setPermissionResolver in interface PermissionResolverAware
      Parameters:
      permissionResolver - the PermissionResolver being set.

    • getRolePermissionResolver

      public RolePermissionResolver getRolePermissionResolver()

    • setRolePermissionResolver

      public void setRolePermissionResolver(RolePermissionResolver permissionRoleResolver)
      Description copied from interface: RolePermissionResolverAware
      Sets the specified RolePermissionResolver on this instance.
      Specified by:
      setRolePermissionResolver in interface RolePermissionResolverAware
      Parameters:
      permissionRoleResolver - the RolePermissionResolver being set.

    • onInit

      protected void onInit()
      Initializes this realm and potentially enables a cache, depending on configuration.

      When this method is called, the following logic is executed:

      1. If the cache property has been set, it will be used to cache the AuthorizationInfo objects returned from getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) method invocations. All future calls to getAuthorizationInfo will attempt to use this cache first to alleviate any potentially unnecessary calls to an underlying data store.
      2. If the cache property has not been set, the cacheManager property will be checked. If a cacheManager has been set, it will be used to create an authorization cache, and this newly created cache which will be used as specified in #1.
      3. If neither the (org.apache.shiro.cache.Cache) cache or cacheManager properties are set, caching will be disabled and authorization look-ups will be delegated to subclass implementations for each authorization check.
      Overrides:
      onInit in class AuthenticatingRealm

    • afterCacheManagerSet

      protected void afterCacheManagerSet()
      Description copied from class: AuthenticatingRealm
      This implementation attempts to acquire an authentication cache if one is not already configured.
      Overrides:
      afterCacheManagerSet in class AuthenticatingRealm

    • getAuthorizationInfo

      protected AuthorizationInfo getAuthorizationInfo(PrincipalCollection principals)
      Returns an account's authorization-specific information for the specified principals, or null if no account could be found. The resulting AuthorizationInfo object is used by the other method implementations in this class to automatically perform access control checks for the corresponding Subject.

      This implementation obtains the actual AuthorizationInfo object from the subclass's implementation of doGetAuthorizationInfo, and then caches it for efficient reuse if caching is enabled (see below).

      Invocations of this method should be thought of as completely orthogonal to acquiring authenticationInfo, since either could occur in any order.

      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.

      Caching

      The AuthorizationInfo values returned from this method are cached for efficient reuse if caching is enabled. Caching is enabled automatically when an authorizationCache instance has been explicitly configured, or if a cacheManager has been configured, which will be used to lazily create the authorizationCache as needed.

      If caching is enabled, the authorization cache will be checked first and if found, will return the cached 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 doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) method, which must be implemented by subclasses.

      Changed Data

      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 clearCachedAuthorizationInfo method. This ensures that the next call to 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.
      Parameters:
      principals - the corresponding Subject's identifying principals with which to look up the Subject's AuthorizationInfo.
      Returns:
      the authorization information for the account associated with the specified principals, or null if no account could be found.

    • getAuthorizationCacheKey

      protected Object getAuthorizationCacheKey(PrincipalCollection principals)

    • clearCachedAuthorizationInfo

      protected void clearCachedAuthorizationInfo(PrincipalCollection principals)
      Clears out the AuthorizationInfo cache entry for the specified account.

      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.

      After this method is called, the next authorization check for that same account will result in a call to getAuthorizationInfo, and the resulting return value will be cached before being returned so it can be reused for later authorization checks.

      If you wish to clear out all associated cached data (and not just authorization data), use the CachingRealm.clearCache(org.apache.shiro.subject.PrincipalCollection) method instead (which will in turn call this method by default).

      Parameters:
      principals - the principals of the account for which to clear the cached AuthorizationInfo.

    • doGetAuthorizationInfo

      protected abstract AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals)
      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 SimpleAuthorizationInfo, as it is suitable in most cases.
      Parameters:
      principals - the primary identifying principals of the AuthorizationInfo that should be retrieved.
      Returns:
      the AuthorizationInfo associated with this principals.
      See Also:

    • getPermissions

      protected Collection<Permission> getPermissions(AuthorizationInfo info)

    • isPermitted

      public boolean isPermitted(PrincipalCollection principals, String permission)
      Description copied from interface: Authorizer
      Returns true if the corresponding subject/user is permitted to perform an action or access a resource summarized by the specified permission string.

      This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.

      Specified by:
      isPermitted in interface Authorizer
      Parameters:
      principals - the application-specific subject/user identifier.
      permission - the String representation of a Permission that is being checked.
      Returns:
      true if the corresponding Subject/user is permitted, false otherwise.
      See Also:

    • isPermitted

      public boolean isPermitted(PrincipalCollection principals, Permission permission)
      Description copied from interface: Authorizer
      Returns true if the corresponding subject/user is permitted to perform an action or access a resource summarized by the specified permission.

      More specifically, this method determines if any Permissions associated with the subject imply the specified permission.

      Specified by:
      isPermitted in interface Authorizer
      Parameters:
      principals - the application-specific subject/user identifier.
      permission - the permission that is being checked.
      Returns:
      true if the corresponding Subject/user is permitted, false otherwise.

    • isPermitted

      protected boolean isPermitted(Permission permission, AuthorizationInfo info)

    • isPermitted

      public boolean[] isPermitted(PrincipalCollection subjectIdentifier, String... permissions)
      Description copied from interface: Authorizer
      Checks if the corresponding Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.

      This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.

      Specified by:
      isPermitted in interface Authorizer
      Parameters:
      subjectIdentifier - the application-specific subject/user identifier.
      permissions - the String representations of the Permissions that are being checked.
      Returns:
      an array of booleans whose indices correspond to the index of the permissions in the given list. A true value at an index indicates the user is permitted for for the associated Permission string in the list. A false value at an index indicates otherwise.

    • isPermitted

      public boolean[] isPermitted(PrincipalCollection principals, List<Permission> permissions)
      Description copied from interface: Authorizer
      Checks if the corresponding Subject/user implies the given Permissions and returns a boolean array indicating which permissions are implied.

      More specifically, this method should determine if each Permission in the array is implied by permissions already associated with the subject.

      This is primarily a performance-enhancing method to help reduce the number of Authorizer.isPermitted(org.apache.shiro.subject.PrincipalCollection, java.lang.String) invocations over the wire in client/server systems.

      Specified by:
      isPermitted in interface Authorizer
      Parameters:
      principals - the application-specific subject/user identifier.
      permissions - the permissions that are being checked.
      Returns:
      an array of booleans whose indices correspond to the index of the permissions in the given list. A true value at an index indicates the user is permitted for for the associated Permission object in the list. A false value at an index indicates otherwise.

    • isPermitted

      protected boolean[] isPermitted(List<Permission> permissions, AuthorizationInfo info)

    • isPermittedAll

      public boolean isPermittedAll(PrincipalCollection subjectIdentifier, String... permissions)
      Description copied from interface: Authorizer
      Returns true if the corresponding Subject/user implies all of the specified permission strings, false otherwise.

      This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.

      Specified by:
      isPermittedAll in interface Authorizer
      Parameters:
      subjectIdentifier - the application-specific subject/user identifier.
      permissions - the String representations of the Permissions that are being checked.
      Returns:
      true if the user has all of the specified permissions, false otherwise.
      See Also:

    • isPermittedAll

      public boolean isPermittedAll(PrincipalCollection principal, Collection<Permission> permissions)
      Description copied from interface: Authorizer
      Returns true if the corresponding Subject/user implies all of the specified permissions, false otherwise.

      More specifically, this method determines if all of the given Permissions are implied by permissions already associated with the subject.

      Specified by:
      isPermittedAll in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      permissions - the permissions to check.
      Returns:
      true if the user has all of the specified permissions, false otherwise.

    • isPermittedAll

      protected boolean isPermittedAll(Collection<Permission> permissions, AuthorizationInfo info)

    • checkPermission

      public void checkPermission(PrincipalCollection subjectIdentifier, String permission) throws AuthorizationException
      Description copied from interface: Authorizer
      Ensures the corresponding Subject/user implies the specified permission String.

      If the subject's existing associated permissions do not Permission.implies(Permission) imply} the given permission, an AuthorizationException will be thrown.

      This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.

      Specified by:
      checkPermission in interface Authorizer
      Parameters:
      subjectIdentifier - the application-specific subject/user identifier.
      permission - the String representation of the Permission to check.
      Throws:
      AuthorizationException - if the user does not have the permission.

    • checkPermission

      public void checkPermission(PrincipalCollection principal, Permission permission) throws AuthorizationException
      Description copied from interface: Authorizer
      Ensures a subject/user Permission.implies(Permission) implies} the specified Permission. If the subject's existing associated permissions do not Permission.implies(Permission) imply} the given permission, an AuthorizationException will be thrown.
      Specified by:
      checkPermission in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      permission - the Permission to check.
      Throws:
      AuthorizationException - if the user does not have the permission.

    • checkPermission

      protected void checkPermission(Permission permission, AuthorizationInfo info)

    • checkPermissions

      public void checkPermissions(PrincipalCollection subjectIdentifier, String... permissions) throws AuthorizationException
      Description copied from interface: Authorizer
      Ensures the corresponding Subject/user implies all of the specified permission strings.

      If the subject's existing associated permissions do not imply all of the given permissions, an AuthorizationException will be thrown.

      This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.

      Specified by:
      checkPermissions in interface Authorizer
      Parameters:
      subjectIdentifier - the application-specific subject/user identifier.
      permissions - the string representations of Permissions to check.
      Throws:
      AuthorizationException - if the user does not have all of the given permissions.

    • checkPermissions

      public void checkPermissions(PrincipalCollection principal, Collection<Permission> permissions) throws AuthorizationException
      Description copied from interface: Authorizer
      Ensures the corresponding Subject/user implies all of the specified permission strings.

      If the subject's existing associated permissions do not imply all of the given permissions, an AuthorizationException will be thrown.

      Specified by:
      checkPermissions in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      permissions - the Permissions to check.
      Throws:
      AuthorizationException - if the user does not have all of the given permissions.

    • checkPermissions

      protected void checkPermissions(Collection<Permission> permissions, AuthorizationInfo info)

    • hasRole

      public boolean hasRole(PrincipalCollection principal, String roleIdentifier)
      Description copied from interface: Authorizer
      Returns true if the corresponding Subject/user has the specified role, false otherwise.
      Specified by:
      hasRole in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      roleIdentifier - the application-specific role identifier (usually a role id or role name).
      Returns:
      true if the corresponding subject has the specified role, false otherwise.

    • hasRole

      protected boolean hasRole(String roleIdentifier, AuthorizationInfo info)

    • hasRoles

      public boolean[] hasRoles(PrincipalCollection principal, List<String> roleIdentifiers)
      Description copied from interface: Authorizer
      Checks if the corresponding Subject/user has the specified roles, returning a boolean array indicating which roles are associated with the given subject.

      This is primarily a performance-enhancing method to help reduce the number of Authorizer.hasRole(org.apache.shiro.subject.PrincipalCollection, java.lang.String) invocations over the wire in client/server systems.

      Specified by:
      hasRoles in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
      Returns:
      an array of booleans whose indices correspond to the index of the roles in the given identifiers. A true value indicates the user has the role at that index. False indicates the user does not have the role at that index.

    • hasRoles

      protected boolean[] hasRoles(List<String> roleIdentifiers, AuthorizationInfo info)

    • hasAllRoles

      public boolean hasAllRoles(PrincipalCollection principal, Collection<String> roleIdentifiers)
      Description copied from interface: Authorizer
      Returns true if the corresponding Subject/user has all of the specified roles, false otherwise.
      Specified by:
      hasAllRoles in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
      Returns:
      true if the user has all the roles, false otherwise.

    • checkRole

      public void checkRole(PrincipalCollection principal, String role) throws AuthorizationException
      Description copied from interface: Authorizer
      Asserts the corresponding Subject/user has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
      Specified by:
      checkRole in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      role - the application-specific role identifier (usually a role id or role name ).
      Throws:
      AuthorizationException - if the user does not have the role.

    • checkRole

      protected void checkRole(String role, AuthorizationInfo info)

    • checkRoles

      public void checkRoles(PrincipalCollection principal, Collection<String> roles) throws AuthorizationException
      Description copied from interface: Authorizer
      Asserts the corresponding Subject/user has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
      Specified by:
      checkRoles in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      roles - the application-specific role identifiers to check (usually role ids or role names).
      Throws:
      AuthorizationException - if the user does not have all of the specified roles.

    • checkRoles

      public void checkRoles(PrincipalCollection principal, String... roles) throws AuthorizationException
      Description copied from interface: Authorizer
      Same as checkRoles(PrincipalCollection subjectPrincipal, Collection<String> roleIdentifiers) but doesn't require a collection as an argument. Asserts the corresponding Subject/user has all the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
      Specified by:
      checkRoles in interface Authorizer
      Parameters:
      principal - the application-specific subject/user identifier.
      roles - the application-specific role identifiers to check (usually role ids or role names).
      Throws:
      AuthorizationException - if the user does not have all the specified roles.

    • checkRoles

      protected void checkRoles(Collection<String> roles, AuthorizationInfo info)

    • doClearCache

      protected void doClearCache(PrincipalCollection principals)
      Calls super.doClearCache to ensure any cached authentication data is removed and then calls clearCachedAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) to remove any cached authorization data.

      If overriding in a subclass, be sure to call super.doClearCache to ensure this behavior is maintained.

      Overrides:
      doClearCache in class AuthenticatingRealm
      Parameters:
      principals - the principals of the account for which to clear any cached AuthorizationInfo
      Since:
      1.2