public interface Subject
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.
Subject
, application developers will almost always use
SecurityUtils
:
Almost all security operations should be performed with theSecurityUtils
.getSubject()
Subject
returned from this method.
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
PermissionResolver
s.)
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.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. |
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 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.
|
Object getPrincipal()
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.
long
RDBMS surrogate primary keyUUID
getPrincipals()
.getPrimaryPrincipal()
PrincipalCollection.getPrimaryPrincipal()
PrincipalCollection getPrincipals()
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.getPrincipal()
,
PrincipalCollection.getPrimaryPrincipal()
boolean isPermitted(String permission)
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.permission
- the String representation of a Permission that is being checked.isPermitted(Permission permission)
boolean isPermitted(Permission permission)
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 Permission
s associated
with the subject imply
the specified permission.permission
- the permission that is being checked.boolean[] isPermitted(String... permissions)
Permission
variant.
Please see the class-level JavaDoc for more information on these String-based permission methods.permissions
- the String representations of the Permissions that are being checked.Permission
string in the list. A false value at an index
indicates otherwise.boolean[] isPermitted(List<Permission> permissions)
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.permissions
- the permissions that are being checked.Permission
object in the list. A false value at an index
indicates otherwise.boolean isPermittedAll(String... permissions)
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.permissions
- the String representations of the Permissions that are being checked.isPermittedAll(Collection)
boolean isPermittedAll(Collection<Permission> permissions)
true
if this Subject implies all of the specified permissions, false
otherwise.
More specifically, this method determines if all of the given Permission
s are
implied by
permissions already associated with this Subject.permissions
- the permissions to check.void checkPermission(String permission) throws AuthorizationException
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.permission
- the String representation of the Permission to check.AuthorizationException
- if the user does not have the permission.void checkPermission(Permission permission) throws AuthorizationException
implies
the specified Permission
.
If this subject's existing associated permissions do not imply
the given permission, an AuthorizationException
will be thrown.permission
- the Permission to check.AuthorizationException
- if this Subject does not have the permission.void checkPermissions(String... permissions) throws AuthorizationException
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.permissions
- the string representations of Permissions to check.AuthorizationException
- if this Subject does not have all of the given permissions.void checkPermissions(Collection<Permission> permissions) throws AuthorizationException
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.permissions
- the Permissions to check.AuthorizationException
- if this Subject does not have all of the given permissions.boolean hasRole(String roleIdentifier)
true
if this Subject has the specified role, false
otherwise.roleIdentifier
- the application-specific role identifier (usually a role id or role name).true
if this Subject has the specified role, false
otherwise.boolean[] hasRoles(List<String> roleIdentifiers)
hasRole(java.lang.String)
invocations over the wire in client/server systems.roleIdentifiers
- the application-specific role identifiers to check (usually role ids or role names).boolean hasAllRoles(Collection<String> roleIdentifiers)
true
if this Subject has all of the specified roles, false
otherwise.roleIdentifiers
- the application-specific role identifiers to check (usually role ids or role names).void checkRole(String roleIdentifier) throws AuthorizationException
AuthorizationException
if they do not.roleIdentifier
- the application-specific role identifier (usually a role id or role name ).AuthorizationException
- if this Subject does not have the role.void checkRoles(Collection<String> roleIdentifiers) throws AuthorizationException
AuthorizationException
if they do not.roleIdentifiers
- the application-specific role identifiers to check (usually role ids or role names).AuthorizationException
- if this Subject does not have all of the specified roles.void checkRoles(String... roleIdentifiers) throws AuthorizationException
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.roleIdentifiers
- roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).AuthorizationException
- org.apache.shiro.authz.AuthorizationException
if this Subject does not have all of the specified roles.void login(AuthenticationToken token) throws AuthenticationException
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
.token
- the token encapsulating the subject's principals and credentials to be passed to the
Authentication subsystem for verification.AuthenticationException
- if the authentication attempt fails.boolean isAuthenticated()
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.true
if this Subject proved their identity during their current session
by providing valid credentials matching those known to the system, false
otherwise.boolean isRemembered()
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:
Note as indicated by the above code example, if agetPrincipal()
!= null && !isAuthenticated()
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.
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.true
if this Subject
's identity (aka principals
) is
remembered from a successful authentication during a previous session, false
otherwise.Session getSession()
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.Session
associated with this Subject.getSession(boolean)
Session getSession(boolean create)
Session
associated with this Subject. Based on the boolean argument,
this method functions as follows:
Subject
, it is returned and
the create
argument is ignored.create
is true
, a new session will be created, associated with
this Subject
and then returned.create
is false
, null
is returned.create
- boolean argument determining if a new session should be created or not if there is no existing session.Session
associated with this Subject
or null
based
on the above described logic.void logout()
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.
<V> V execute(Callable<V> callable) throws ExecutionException
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.V
- the type of return value the Callable
will returncallable
- the Callable to associate with this subject and then execute.Callable
's execution.ExecutionException
- if the Callable
's call
method throws an exception.void execute(Runnable runnable)
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.runnable
- the Runnable
to associate with this Subject
and then execute.<V> Callable<V> associateWith(Callable<V> callable)
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.V
- the Callable
s return value typecallable
- the callable to execute as this Subject
Callable
that can be run as this Subject
.Runnable associateWith(Runnable runnable)
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.runnable
- the runnable to execute as this Subject
Runnable
that can be run as this Subject
on another thread.(java.util.concurrent.Callable)
void runAs(PrincipalCollection principals) throws NullPointerException, IllegalStateException
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
:
Subject
is 'running as' another identity by calling the
isRunAs()
method.getPreviousPrincipals()
method.Subject
to stop running as another identity, you can return to its previous
'pre run as' identity by calling the releaseRunAs()
method.principals
- the identity to 'run as', aka the identity to assume indefinitely.NullPointerException
- if the specified principals collection is null
or empty.IllegalStateException
- if this Subject
does not yet have an identity of its own.boolean isRunAs()
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.true
if this Subject
is 'running as' another identity other than its original one or
false
otherwise (normal Subject
state).runAs(org.apache.shiro.subject.PrincipalCollection)
PrincipalCollection getPreviousPrincipals()
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.Subject
before assuming the current
runAs
identity, or null
if this Subject
is not operating under an assumed
identity (normal state).runAs(org.apache.shiro.subject.PrincipalCollection)
PrincipalCollection releaseRunAs()
#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.null
if this Subject
is not operating
under an assumed identity.runAs(org.apache.shiro.subject.PrincipalCollection)
Copyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.