|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
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.
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
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.
| 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. |
| Method Summary | ||
|---|---|---|
|
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. |
|
|
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 |
|---|
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 keyUUIDgetPrincipals().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 Permissions 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 Permissions 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 Callables 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)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||