Package org.apache.shiro.subject.support

Class DelegatingSubject

  • All Implemented Interfaces:
    Subject
    public class DelegatingSubject
extends 
implements Subject
    Implementation of the Subject interface that delegates method calls to an underlying SecurityManager instance for security checks. It is essentially a SecurityManager proxy.

    This implementation does not maintain state such as roles and permissions (only Subject principals, such as usernames or user primary keys) for better performance in a stateless architecture. It instead asks the underlying SecurityManager every time to perform the authorization check.

    A common misconception in using this implementation is that an EIS resource (RDBMS, etc) would be "hit" every time a method is called. This is not necessarily the case and is up to the implementation of the underlying SecurityManager instance. If caching of authorization data is desired (to eliminate EIS round trips and therefore improve database performance), it is considered much more elegant to let the underlying SecurityManager implementation or its delegate components manage caching, not this class. A SecurityManager is considered a business-tier component, where caching strategies are better managed.

    Applications from large and clustered to simple and JVM-local all benefit from stateless architectures. This implementation plays a part in the stateless programming paradigm and should be used whenever possible.

    Since:
    0.1

    • Nested Class Summary

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void assertAuthzCheckPossible()  
       runnable)
      Returns a Runnable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
      <V> <V> <V> callable)
      Returns a Callable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
      void  permission)
      Ensures this Subject implies the specified permission String.
      void checkPermission​(Permission permission)
      Ensures this Subject implies the specified Permission.
      void ... permissions)
      Ensures this Subject implies all of the specified permission strings.
      void <Permission> permissions)
      Ensures this Subject implies all of the specified permission strings.
      void  role)
      Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
      void ... roleIdentifiers)
      Same as checkRoles(CollectionroleIdentifiers) but doesn't require a collection as a an argument.
      void <> roles)
      Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
      protected SessionContext createSessionContext()  
      protected Session decorate​(Session session)  
      void  runnable)
      Associates the specified Runnable with this Subject instance and then executes it on the currently running thread.
      <V> V <V> callable)
      Associates the specified Callable with this Subject instance and then executes it on the currently running thread.
      getHost()
      Returns the host name or IP associated with the client who created/is interacting with this Subject.
      PrincipalCollection getPreviousPrincipals()
      Returns the previous 'pre run as' identity of this Subject before assuming the current runAs identity, or null if this Subject is not operating under an assumed identity (normal state).
      getPrincipal()
      Returns this Subject's application-wide uniquely identifying principal, or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
      PrincipalCollection getPrincipals()
      Returns this Subject's principals (identifying attributes) in the form of a PrincipalCollection or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
      SecurityManager getSecurityManager()  
      Session getSession()
      Returns the application Session associated with this Subject.
      Session getSession​(boolean create)
      Returns the application Session associated with this Subject.
      boolean <> roleIdentifiers)
      Returns true if this Subject has all of the specified roles, false otherwise.
      protected boolean hasPrincipals()  
      boolean  roleIdentifier)
      Returns true if this Subject has the specified role, false otherwise.
      boolean[] <> roleIdentifiers)
      Checks if this Subject has the specified roles, returning a boolean array indicating which roles are associated.
      boolean isAuthenticated()
      Returns true if this Subject/user proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.
      boolean  permission)
      Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission string.
      boolean[] ... permissions)
      Checks if this Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.
      boolean[] <Permission> permissions)
      Checks if this Subject implies the given Permissions and returns a boolean array indicating which permissions are implied.
      boolean isPermitted​(Permission permission)
      Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission.
      boolean ... permissions)
      Returns true if this Subject implies all of the specified permission strings, false otherwise.
      boolean <Permission> permissions)
      Returns true if this Subject implies all of the specified permissions, false otherwise.
      boolean isRemembered()
      Returns true if this Subject has an identity (it is not anonymous) and the identity (aka principals) is remembered from a successful authentication during a previous session.
      boolean isRunAs()
      Returns true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state).
      protected boolean isSessionCreationEnabled()
      Returns true if this Subject is allowed to create sessions, false otherwise.
      void login​(AuthenticationToken token)
      Performs a login attempt for this Subject/user.
      void logout()
      Logs out this Subject and invalidates and/or removes any associated entities, such as a Session and authorization data.
      PrincipalCollection releaseRunAs()
      Releases the current 'run as' (assumed) identity and reverts back to the previous 'pre run as' identity that existed before #runAs runAs was called.
      void runAs​(PrincipalCollection principals)
      Allows this subject to 'run as' or 'assume' another identity indefinitely.

      • Methods inherited from class java.lang.

        , , , , , , , , , ,

    • Field Detail

      • authenticated

        protected boolean authenticated

      • host

        protected  host

      • session

        protected Session session

      • sessionCreationEnabled

        protected boolean sessionCreationEnabled
        Since:
        1.2

    • Method Detail

      • hasPrincipals

        protected boolean hasPrincipals()

      • getHost

        public  getHost()
        Returns the host name or IP associated with the client who created/is interacting with this Subject.
        Returns:
        the host name or IP associated with the client who created/is interacting with this Subject.

      • getPrincipal

        public  getPrincipal()
        Description copied from interface: Subject
        Returns this Subject's application-wide uniquely identifying principal, or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).

        The term principal is just a fancy security term for any identifying attribute(s) of an application user, such as a username, or user id, or public key, or anything else you might use in your application to identify a user.

        Uniqueness

        Although given names and family names (first/last) are technically considered principals as well, Shiro expects the object returned from this method to be an identifying attribute unique across your entire application.

        This implies that things like given names and family names are usually poor candidates as return values since they are rarely guaranteed to be unique; Things often used for this value:

        • A long RDBMS surrogate primary key
        • An application-unique username
        • A
        • An LDAP Unique ID
        or any other similar suitable unique mechanism valuable to your application.

        Most implementations will simply return Subject.getPrincipals().getPrimaryPrincipal()

        Specified by:
        getPrincipal in interface Subject
        Returns:
        this Subject's application-specific unique identity.
        See Also:
        Subject.getPrincipal()

      • getPrincipals

        public PrincipalCollection getPrincipals()
        Description copied from interface: Subject
        Returns this Subject's principals (identifying attributes) in the form of a PrincipalCollection or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).

        The word "principals" is nothing more than a fancy security term for identifying attributes associated with a Subject, aka, application user. For example, user id, a surname (family/last name), given (first) name, social security number, nickname, username, etc, are all examples of a principal.

        Specified by:
        getPrincipals in interface Subject
        Returns:
        all of this Subject's principals (identifying attributes).
        See Also:
        Subject.getPrincipal(), PrincipalCollection.getPrimaryPrincipal()

      • isPermitted

        public boolean isPermitted​( permission)
        Description copied from interface: Subject
        Returns true if this Subject 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 Subject
        Parameters:
        permission - the String representation of a Permission that is being checked.
        Returns:
        true if this Subject is permitted, false otherwise.
        See Also:
        Subject.isPermitted(Permission permission)

      • isPermitted

        public boolean isPermitted​(Permission permission)
        Description copied from interface: Subject
        Returns true if this Subject 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 Subject
        Parameters:
        permission - the permission that is being checked.
        Returns:
        true if this Subject is permitted, false otherwise.

      • isPermitted

        public boolean[] isPermitted​(... permissions)
        Description copied from interface: Subject
        Checks if this 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 Subject
        Parameters:
        permissions - the String representations of the Permissions that are being checked.
        Returns:
        a boolean array where indices correspond to the index of the permissions in the given list. A true value at an index indicates this Subject is permitted for for the associated Permission string in the list. A false value at an index indicates otherwise.

      • isPermitted

        public boolean[] isPermitted​(<Permission> permissions)
        Description copied from interface: Subject
        Checks if this Subject 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 Subject.isPermitted(java.lang.String) invocations over the wire in client/server systems.

        Specified by:
        isPermitted in interface Subject
        Parameters:
        permissions - the permissions that are being checked.
        Returns:
        a boolean array where indices correspond to the index of the permissions in the given list. A true value at an index indicates this Subject is permitted for for the associated Permission object in the list. A false value at an index indicates otherwise.

      • isPermittedAll

        public boolean isPermittedAll​(... permissions)
        Description copied from interface: Subject
        Returns true if this Subject 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 Subject
        Parameters:
        permissions - the String representations of the Permissions that are being checked.
        Returns:
        true if this Subject has all of the specified permissions, false otherwise.
        See Also:
        Subject.isPermittedAll(Collection)

      • isPermittedAll

        public boolean isPermittedAll​(<Permission> permissions)
        Description copied from interface: Subject
        Returns true if this Subject 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 this Subject.

        Specified by:
        isPermittedAll in interface Subject
        Parameters:
        permissions - the permissions to check.
        Returns:
        true if this Subject has all of the specified permissions, false otherwise.

      • checkPermission

        public void checkPermission​( permission)
                     throws AuthorizationException
        Description copied from interface: Subject
        Ensures this Subject implies the specified permission String.

        If this 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 Subject
        Parameters:
        permission - the String representation of the Permission to check.
        Throws:
        AuthorizationException - if the user does not have the permission.

      • checkPermissions

        public void checkPermissions​(... permissions)
                      throws AuthorizationException
        Description copied from interface: Subject
        Ensures this Subject implies all of the specified permission strings.

        If this 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 Subject
        Parameters:
        permissions - the string representations of Permissions to check.
        Throws:
        AuthorizationException - if this Subject does not have all of the given permissions.

      • hasRole

        public boolean hasRole​( roleIdentifier)
        Description copied from interface: Subject
        Returns true if this Subject has the specified role, false otherwise.
        Specified by:
        hasRole in interface Subject
        Parameters:
        roleIdentifier - the application-specific role identifier (usually a role id or role name).
        Returns:
        true if this Subject has the specified role, false otherwise.

      • hasRoles

        public boolean[] hasRoles​(<> roleIdentifiers)
        Description copied from interface: Subject
        Checks if this Subject has the specified roles, returning a boolean array indicating which roles are associated.

        This is primarily a performance-enhancing method to help reduce the number of Subject.hasRole(java.lang.String) invocations over the wire in client/server systems.

        Specified by:
        hasRoles in interface Subject
        Parameters:
        roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
        Returns:
        a boolean array where indices correspond to the index of the roles in the given identifiers. A true value indicates this Subject has the role at that index. False indicates this Subject does not have the role at that index.

      • hasAllRoles

        public boolean hasAllRoles​(<> roleIdentifiers)
        Description copied from interface: Subject
        Returns true if this Subject has all of the specified roles, false otherwise.
        Specified by:
        hasAllRoles in interface Subject
        Parameters:
        roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
        Returns:
        true if this Subject has all the roles, false otherwise.

      • checkRole

        public void checkRole​( role)
               throws AuthorizationException
        Description copied from interface: Subject
        Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
        Specified by:
        checkRole in interface Subject
        Parameters:
        role - the application-specific role identifier (usually a role id or role name ).
        Throws:
        AuthorizationException - if this Subject does not have the role.

      • checkRoles

        public void checkRoles​(... roleIdentifiers)
                throws AuthorizationException
        Description copied from interface: Subject
        Same as checkRoles(CollectionroleIdentifiers) but doesn't require a collection as a an argument. Asserts this Subject 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 Subject
        Parameters:
        roleIdentifiers - roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
        Throws:
        AuthorizationException - org.apache.shiro.authz.AuthorizationException if this Subject does not have all of the specified roles.

      • checkRoles

        public void checkRoles​(<> roles)
                throws AuthorizationException
        Description copied from interface: Subject
        Asserts this Subject 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 Subject
        Parameters:
        roles - the application-specific role identifiers to check (usually role ids or role names).
        Throws:
        AuthorizationException - if this Subject does not have all of the specified roles.

      • login

        public void login​(AuthenticationToken token)
           throws AuthenticationException
        Description copied from interface: Subject
        Performs a login attempt for this Subject/user. If unsuccessful, an AuthenticationException is thrown, the subclass of which identifies why the attempt failed. If successful, the account data associated with the submitted principals/credentials will be associated with this Subject and the method will return quietly.

        Upon returning quietly, this Subject instance can be considered authenticated and getPrincipal() will be non-null and isAuthenticated() will be true.

        Specified by:
        login in interface Subject
        Parameters:
        token - the token encapsulating the subject's principals and credentials to be passed to the Authentication subsystem for verification.
        Throws:
        AuthenticationException - if the authentication attempt fails.

      • isAuthenticated

        public boolean isAuthenticated()
        Description copied from interface: Subject
        Returns true if this Subject/user proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.

        Note that even if this Subject's identity has been remembered via 'remember me' services, this method will still return false unless the user has actually logged in with proper credentials during their current session. See the isRemembered() method JavaDoc for more.

        Specified by:
        isAuthenticated in interface Subject
        Returns:
        true if this Subject proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.

      • isRemembered

        public boolean isRemembered()
        Description copied from interface: Subject
        Returns true if this Subject has an identity (it is not anonymous) and the identity (aka principals) is remembered from a successful authentication during a previous session.

        Although the underlying implementation determines exactly how this method functions, most implementations have this method act as the logical equivalent to this code: 

         getPrincipal() != null && !isAuthenticated()

        Note as indicated by the above code example, if a Subject is remembered, they are NOT considered authenticated. A check against isAuthenticated() is a more strict check than that reflected by this method. For example, a check to see if a subject can access financial information should almost always depend on isAuthenticated() to guarantee a verified identity, and not this method.

        Once the subject is authenticated, they are no longer considered only remembered because their identity would have been verified during the current session.

        Remembered vs Authenticated

        Authentication is the process of proving you are who you say you are. When a user is only remembered, the remembered identity gives the system an idea who that user probably is, but in reality, has no way of absolutely guaranteeing if the remembered Subject represents the user currently using the application.

        So although many parts of the application can still perform user-specific logic based on the remembered principals, such as customized views, it should never perform highly-sensitive operations until the user has legitimately verified their identity by executing a successful authentication attempt.

        We see this paradigm all over the web, and we will use as an example:

        When you visit Amazon.com and perform a login and ask it to 'remember me', it will set a cookie with your identity. If you don't log out and your session expires, and you come back, say the next day, Amazon still knows who you probably are: you still see all of your book and movie recommendations and similar user-specific features since these are based on your (remembered) user id.

        BUT, if you try to do something sensitive, such as access your account's billing data, Amazon forces you to do an actual log-in, requiring your username and password.

        This is because although amazon.com assumed your identity from 'remember me', it recognized that you were not actually authenticated. The only way to really guarantee you are who you say you are, and therefore allow you access to sensitive account data, is to force you to perform an actual successful authentication. You can check this guarantee via the isAuthenticated() method and not via this method.

        Specified by:
        isRemembered in interface Subject
        Returns:
        true if this Subject's identity (aka principals) is remembered from a successful authentication during a previous session, false otherwise.

      • isSessionCreationEnabled

        protected boolean isSessionCreationEnabled()
        Returns true if this Subject is allowed to create sessions, false otherwise.
        Returns:
        true if this Subject is allowed to create sessions, false otherwise.
        Since:
        1.2

      • getSession

        public Session getSession()
        Description copied from interface: Subject
        Returns the application Session associated with this Subject. If no session exists when this method is called, a new session will be created, associated with this Subject, and then returned.
        Specified by:
        getSession in interface Subject
        Returns:
        the application Session associated with this Subject.
        See Also:
        Subject.getSession(boolean)

      • getSession

        public Session getSession​(boolean create)
        Description copied from interface: Subject
        Returns the application Session associated with this Subject. Based on the boolean argument, this method functions as follows:
        • If there is already an existing session associated with this Subject, it is returned and the create argument is ignored.
        • If no session exists and create is true, a new session will be created, associated with this Subject and then returned.
        • If no session exists and create is false, null is returned.
        Specified by:
        getSession in interface Subject
        Parameters:
        create - boolean argument determining if a new session should be created or not if there is no existing session.
        Returns:
        the application Session associated with this Subject or null based on the above described logic.

      • createSessionContext

        protected SessionContext createSessionContext()

      • logout

        public void logout()
        Description copied from interface: Subject
        Logs out this Subject and invalidates and/or removes any associated entities, such as a Session and authorization data. After this method is called, the Subject is considered 'anonymous' and may continue to be used for another log-in if desired.

        Web Environment Warning

        Calling this method in web environments will usually remove any associated session cookie as part of session invalidation. Because cookies are part of the HTTP header, and headers can only be set before the response body (html, image, etc) is sent, this method in web environments must be called before any content has been rendered.

        The typical approach most applications use in this scenario is to redirect the user to a different location (e.g. home page) immediately after calling this method. This is an effect of the HTTP protocol itself and not a reflection of Shiro's implementation.

        Non-HTTP environments may of course use a logged-out subject for login again if desired.

        Specified by:
        logout in interface Subject

      • execute

        public <V> V execute​(<V> callable)
              throws ExecutionException
        Description copied from interface: Subject
        Associates the specified Callable with this Subject instance and then executes it on the currently running thread. If you want to execute the Callable on a different thread, it is better to use the Subject.associateWith(Callable) method instead.
        Specified by:
        execute in interface Subject
        Type Parameters:
        V - the type of return value the Callable will return
        Parameters:
        callable - the Callable to associate with this subject and then execute.
        Returns:
        the resulting object returned by the Callable's execution.
        Throws:
        method throws an exception.

      • execute

        public void execute​( runnable)
        Description copied from interface: Subject
        Associates the specified Runnable with this Subject instance and then executes it on the currently running thread. If you want to execute the Runnable on a different thread, it is better to use the Subject.associateWith(Runnable) method instead.

        Note: This method is primarily provided to execute existing/legacy Runnable implementations. It is better for new code to use Subject.execute(Callable) since that supports the ability to return values and catch exceptions.

        Specified by:
        execute in interface Subject
        Parameters:
        runnable - the Runnable to associate with this Subject and then execute.

      • associateWith

        public <V> <V> associateWith​(<V> callable)
        Description copied from interface: Subject
        Returns a Callable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity. The returned object can be used with an to execute as this Subject.

        This will effectively ensure that any calls to SecurityUtils.getSubject() and related functionality will continue to function properly on any thread that executes the returned Callable instance.

        Specified by:
        associateWith in interface Subject
        Type Parameters:
        V - the Callables return value type
        Parameters:
        callable - the callable to execute as this Subject
        Returns:
        a Callable that can be run as this Subject.

      • associateWith

        public  associateWith​( runnable)
        Description copied from interface: Subject
        Returns a Runnable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity. The returned object can be used with an or another thread to execute as this Subject.

        This will effectively ensure that any calls to SecurityUtils.getSubject() and related functionality will continue to function properly on any thread that executes the returned Runnable instance.

        *Note that if you need a return value to be returned as a result of the runnable's execution or if you need to react to any Exceptions, it is highly recommended to use the createCallable method instead of this one.

        Specified by:
        associateWith in interface Subject
        Parameters:
        runnable - the runnable to execute as this Subject
        Returns:
        a Runnable that can be run as this Subject on another thread.
        See Also:
        (java.util.concurrent.Callable)

      • runAs

        public void runAs​(PrincipalCollection principals)
        Description copied from interface: Subject
        Allows this subject to 'run as' or 'assume' another identity indefinitely. This can only be called when the Subject instance already has an identity (i.e. they are remembered from a previous log-in or they have authenticated during their current session).

        Some notes about runAs:

        • You can tell if a Subject is 'running as' another identity by calling the isRunAs() method.
        • If running as another identity, you can determine what the previous 'pre run as' identity was by calling the getPreviousPrincipals() method.
        • When you want a Subject to stop running as another identity, you can return to its previous 'pre run as' identity by calling the releaseRunAs() method.
        Specified by:
        runAs in interface Subject
        Parameters:
        principals - the identity to 'run as', aka the identity to assume indefinitely.

      • isRunAs

        public boolean isRunAs()
        Description copied from interface: Subject
        Returns true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state). See the runAs method for more information.
        Specified by:
        isRunAs in interface Subject
        Returns:
        true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state).
        See Also:
        Subject.runAs(org.apache.shiro.subject.PrincipalCollection)

      • getPreviousPrincipals

        public PrincipalCollection getPreviousPrincipals()
        Description copied from interface: Subject
        Returns the previous 'pre run as' identity of this Subject before assuming the current runAs identity, or null if this Subject is not operating under an assumed identity (normal state). See the runAs method for more information.
        Specified by:
        getPreviousPrincipals in interface Subject
        Returns:
        the previous 'pre run as' identity of this Subject before assuming the current runAs identity, or null if this Subject is not operating under an assumed identity (normal state).
        See Also:
        Subject.runAs(org.apache.shiro.subject.PrincipalCollection)

      • releaseRunAs

        public PrincipalCollection releaseRunAs()
        Description copied from interface: Subject
        Releases the current 'run as' (assumed) identity and reverts back to the previous 'pre run as' identity that existed before #runAs runAs was called.

        This method returns 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity.

        Specified by:
        releaseRunAs in interface Subject
        Returns:
        the 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity.
        See Also:
        Subject.runAs(org.apache.shiro.subject.PrincipalCollection)