org.apache.shiro.subject

Interface Subject

  • All Known Implementing Classes:
    DelegatingSubject 

    public interface Subject
    A Subject represents state and security operations for a single application user. These operations include authentication (login/logout), authorization (access control), and session access. It is Shiro's primary mechanism for single-user security functionality.

    Acquiring a Subject

    To acquire the currently-executing Subject, application developers will almost always use SecurityUtils: 
     SecurityUtils.getSubject()
    Almost all security operations should be performed with the Subject returned from this method.

    Permission methods

    Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of Permission instances. They are a convenience allowing the caller to use a String representation of a Permission if desired. The underlying Authorization subsystem implementations will usually simply convert these String values to Permission instances and then just call the corresponding type-safe method. (Shiro's default implementations do String-to-Permission conversion for these methods using PermissionResolvers.)

    These overloaded *Permission methods forgo type-saftey for the benefit of convenience and simplicity, so you should choose which ones to use based on your preferences and needs.
    Since:
    0.1

    • Nested Class Summary

      Nested Classes

      Modifier and Type Interface and Description
      static class  Subject.Builder
      Builder design pattern implementation for creating Subject instances in a simplified way without requiring knowledge of Shiro's construction techniques.

    • Method Summary

      Modifier and Type Method and Description
      <V> Callable<V> associateWith(Callable<V> callable)
      Returns a Callable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
      Runnable associateWith(Runnable runnable)
      Returns a Runnable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
      void checkPermission(Permission permission)
      Ensures this Subject implies the specified Permission.
      void checkPermission(String permission)
      Ensures this Subject implies the specified permission String.
      void checkPermissions(Collection<Permission> permissions)
      Ensures this Subject implies all of the specified permission strings.
      void checkPermissions(String... permissions)
      Ensures this Subject implies all of the specified permission strings.
      void checkRole(String roleIdentifier)
      Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
      void checkRoles(Collection<String> roleIdentifiers)
      Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
      void checkRoles(String... roleIdentifiers)
      Same as checkRoles(Collection roleIdentifiers) but doesn't require a collection as a an argument.
      <V> V execute(Callable<V> callable)
      Associates the specified Callable with this Subject instance and then executes it on the currently running thread.
      void execute(Runnable runnable)
      Associates the specified Runnable with this Subject instance and then executes it on the currently running thread.
      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).
      Object 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).
      Session getSession()
      Returns the application Session associated with this Subject.
      Session getSession(boolean create)
      Returns the application Session associated with this Subject.
      boolean hasAllRoles(Collection<String> roleIdentifiers)
      Returns true if this Subject has all of the specified roles, false otherwise.
      boolean hasRole(String roleIdentifier)
      Returns true if this Subject has the specified role, false otherwise.
      boolean[] hasRoles(List<String> 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[] isPermitted(List<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[] isPermitted(String... permissions)
      Checks if this Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.
      boolean isPermitted(String permission)
      Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission string.
      boolean isPermittedAll(Collection<Permission> permissions)
      Returns true if this Subject implies all of the specified permissions, false otherwise.
      boolean isPermittedAll(String... permissions)
      Returns true if this Subject implies all of the specified permission strings, 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).
      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.

    • Method Detail

      • getPrincipal

        Object 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).

        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 UUID
        • An LDAP Unique ID
        or any other similar suitable unique mechanism valuable to your application.

        Most implementations will simply return getPrincipals().getPrimaryPrincipal()
        Returns:
        this Subject's application-specific unique identity.
        See Also:
        PrincipalCollection.getPrimaryPrincipal()

      • getPrincipals

        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).

        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.
        Returns:
        all of this Subject's principals (identifying attributes).
        See Also:
        getPrincipal(), PrincipalCollection.getPrimaryPrincipal()

      • isPermitted

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

      • isPermitted

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

      • isPermitted

        boolean[] isPermitted(String... permissions)
        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.
        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.
        Since:
        0.9

      • isPermitted

        boolean[] isPermitted(List<Permission> permissions)
        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 isPermitted(java.lang.String) invocations over the wire in client/server systems.
        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

        boolean isPermittedAll(String... permissions)
        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.
        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.
        Since:
        0.9
        See Also:
        isPermittedAll(Collection)

      • isPermittedAll

        boolean isPermittedAll(Collection<Permission> permissions)
        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.
        Parameters:
        permissions - the permissions to check.
        Returns:
        true if this Subject has all of the specified permissions, false otherwise.

      • checkPermission

        void checkPermission(String permission)
              throws AuthorizationException
        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.
        Parameters:
        permission - the String representation of the Permission to check.
        Throws:
        AuthorizationException - if the user does not have the permission.
        Since:
        0.9

      • checkPermissions

        void checkPermissions(String... permissions)
               throws AuthorizationException
        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.
        Parameters:
        permissions - the string representations of Permissions to check.
        Throws:
        AuthorizationException - if this Subject does not have all of the given permissions.
        Since:
        0.9

      • hasRole

        boolean hasRole(String roleIdentifier)
        Returns true if this Subject has the specified role, false otherwise.
        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

        boolean[] hasRoles(List<String> roleIdentifiers)
        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 hasRole(java.lang.String) invocations over the wire in client/server systems.
        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

        boolean hasAllRoles(Collection<String> roleIdentifiers)
        Returns true if this Subject has all of the specified roles, false otherwise.
        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

        void checkRole(String roleIdentifier)
        throws AuthorizationException
        Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
        Parameters:
        roleIdentifier - the application-specific role identifier (usually a role id or role name ).
        Throws:
        AuthorizationException - if this Subject does not have the role.

      • checkRoles

        void checkRoles(Collection<String> roleIdentifiers)
         throws AuthorizationException
        Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
        Parameters:
        roleIdentifiers - 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.

      • checkRoles

        void checkRoles(String... roleIdentifiers)
         throws AuthorizationException
        Same as checkRoles(Collection roleIdentifiers) 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.
        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.
        Since:
        1.1.0

      • login

        void login(AuthenticationToken token)
    throws AuthenticationException
        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.
        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.
        Since:
        0.9

      • isAuthenticated

        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.

        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.
        Returns:
        true if this Subject proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.
        Since:
        0.9

      • isRemembered

        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.

        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 Amazon.com 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.
        Returns:
        true if this Subject's identity (aka principals) is remembered from a successful authentication during a previous session, false otherwise.
        Since:
        1.0

      • getSession

        Session getSession()
        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.
        Returns:
        the application Session associated with this Subject.
        Since:
        0.2
        See Also:
        getSession(boolean)

      • getSession

        Session getSession(boolean create)
        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.
        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.
        Since:
        0.2

      • logout

        void logout()
        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.

      • execute

        <V> V execute(Callable<V> callable)
       throws ExecutionException
        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 associateWith(Callable) method instead.
        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:
        ExecutionException - if the Callable's call method throws an exception.
        Since:
        1.0

      • execute

        void execute(Runnable runnable)
        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 associateWith(Runnable) method instead.

        Note: This method is primarily provided to execute existing/legacy Runnable implementations. It is better for new code to use execute(Callable) since that supports the ability to return values and catch exceptions.
        Parameters:
        runnable - the Runnable to associate with this Subject and then execute.
        Since:
        1.0

      • associateWith

        <V> Callable<V> associateWith(Callable<V> callable)
        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 ExecutorService 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.
        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.
        Since:
        1.0

      • associateWith

        Runnable associateWith(Runnable runnable)
        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 Executor 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.
        Parameters:
        runnable - the runnable to execute as this Subject
        Returns:
        a Runnable that can be run as this Subject on another thread.
        Since:
        1.0
        See Also:
        (java.util.concurrent.Callable)

      • runAs

        void runAs(PrincipalCollection principals)
    throws NullPointerException,
           IllegalStateException
        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.
        Parameters:
        principals - the identity to 'run as', aka the identity to assume indefinitely.
        Throws:
        NullPointerException - if the specified principals collection is null or empty.
        IllegalStateException - if this Subject does not yet have an identity of its own.
        Since:
        1.0

      • isRunAs

        boolean isRunAs()
        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.
        Returns:
        true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state).
        Since:
        1.0
        See Also:
        runAs(org.apache.shiro.subject.PrincipalCollection)

      • getPreviousPrincipals

        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). See the runAs method for more information.
        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).
        Since:
        1.0
        See Also:
        runAs(org.apache.shiro.subject.PrincipalCollection)

      • releaseRunAs

        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.

        This method returne 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity.
        Returns:
        the 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity.
        Since:
        1.0
        See Also:
        runAs(org.apache.shiro.subject.PrincipalCollection)