org.apache.shiro.subject
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:

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

static class

Subject.Builder
Builder design pattern implementation for creating Subject instances in a simplified way without
requiring knowledge of Shiro's construction techniques.

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

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

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:

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.

isPermitted

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.

isPermitted

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.

hasRoles

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.

checkRoles

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

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.

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.

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.

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

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.

execute

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

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

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.

runAs

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.

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