http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/realm.html.vtl ---------------------------------------------------------------------- diff --git a/realm.html.vtl b/realm.html.vtl new file mode 100644 index 0000000..c9191b6 --- /dev/null +++ b/realm.html.vtl @@ -0,0 +1,218 @@ +<h1><a name="Realm-ApacheShiroRealms"></a>Apache Shiro Realms</h1> + +<div class="toc"> +<ul><li><a href="#Realm-RealmConfiguration">Realm Configuration</a></li><ul><li><a href="#Realm-ExplicitAssignment">Explicit Assignment</a></li><li><a href="#Realm-ImplicitAssignment">Implicit Assignment</a></li></ul><li><a href="#Realm-RealmAuthentication">Realm Authentication</a></li><ul><li><a href="#Realm-Supporting%7B%7BAuthenticationTokens%7D%7D">Supporting <tt>AuthenticationTokens</tt></a></li><li><a href="#Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D">Handling supported <tt>AuthenticationTokens</tt></a></li><li><a href="#Realm-CredentialsMatching">Credentials Matching</a></li><ul><li><a href="#Realm-SimpleEqualityCheck">Simple Equality Check</a></li><li><a href="#Realm-HashingCredentials">Hashing Credentials</a></li><ul><li><a href="#Realm-HashingandCorrespondingMatchers">Hashing and Corresponding Matchers</a></li><ul><li><a href="#Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"> <tt>SaltedAuthenticationInfo</tt></a></li></ul></ul></ul><li><a href="#Realm-DisablingAut hentication">Disabling Authentication</a></li></ul><li><a href="#Realm-RealmAuthorization">Realm Authorization</a></li><li><a href="#Realm-Lendahandwithdocumentation">Lend a hand with documentation</a></li></ul></div> + +<p>A <tt>Realm</tt> is a component that can access application-specific security data such as users, roles, and permissions. The <tt>Realm</tt> translates this application-specific data into a format that Shiro understands so Shiro can in turn provide a single easy-to-understand <a href="subject.html" title="Subject">Subject</a> programming API no matter how many data sources exist or how application-specific your data might be.</p> + +<p>Realms usually have a 1-to-1 correlation with a data source such as a relational database, LDAP directory, file system, or other similar resource. As such, implementations of the <tt>Realm</tt> interface use data source-specific APIs to discover authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API. </p> + +#tip('Tip', 'A Realm is essentially a security-specific <a class="external-link" href="http://en.wikipedia.org/wiki/Data_Access_Object"; rel="nofollow">DAO</a>') + +<p>Because most of these data sources usually store both authentication data (credentials such as passwords) as well as authorization data (such as roles or permissions), every Shiro <tt>Realm</tt> can perform <em>both</em> authentication and authorization operations.</p> + +<h2><a name="Realm-RealmConfiguration"></a>Realm Configuration</h2> + +<p>If using Shiro's INI configuration, you define and reference <tt>Realms</tt> like any other object in the <tt>[main]</tt> section, but they are configured on the <tt>securityManager</tt> in one of two ways: explicitly or implicitly.</p> + +<h3><a name="Realm-ExplicitAssignment"></a>Explicit Assignment</h3> + +<p>Based on knowledge of INI configuration thus far, this is an obvious configuration approach. After defining one or more Realms, you set them as a collection property on the <tt>securityManager</tt> object.</p> + +<p>For example:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +fooRealm = com.company.foo.Realm +barRealm = com.company.another.Realm +bazRealm = com.company.baz.Realm + +securityManager.realms = $fooRealm, $barRealm, $bazRealm +</pre> +</div></div> + +<p>Explicit assignment is deterministic - you control exactly which realms are used as well as <em>the order</em> that they will be used for authentication and authorization. Realm ordering effects are described in detail in the Authentication chapter's <a href="authentication.html\#Authentication-sequence">Authentication Sequence</a> section. </p> + +<h3><a name="Realm-ImplicitAssignment"></a>Implicit Assignment</h3> + +#danger('Not Preferred', 'Implicit assignment can cause unexpected behavior if you change the order in which realms are defined. It is recommended that you avoid this approach and use Explicit Assignment, which has deterministic behavior. It is likely Implicit Assignment will be deprecated/removed from a future Shiro release.') + +<p>If for some reason you don't want to explicitly configure the <tt>securityManager.realms</tt> property, you can allow Shiro to detect all configured realms and assign them to the <tt>securityManager</tt> directly.</p> + +<p>Using this approach, realms are assigned to the <tt>securityManager</tt> instance in the <em>order that they are defined</em>.</p> + +<p>That is, for the following <tt>shiro.ini</tt> example:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +blahRealm = com.company.blah.Realm +fooRealm = com.company.foo.Realm +barRealm = com.company.another.Realm + +# no securityManager.realms assignment here +</pre> +</div></div> + +<p>basically has the same effect as if the following line were appended:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +securityManager.realms = $blahRealm, $fooRealm, $barRealm +</pre> +</div></div> + +<p>However, realize that with implicit assignment, just the order that the realms are defined directly affects how they are consulted during authentication and authorization attempts. If you change their definition order, you will change how the master <tt>Authenticator</tt>'s <a href="authentication.html\#Authentication-sequence">Authentication Sequence</a> functions.</p> + +<p>For this reason, and to ensure deterministic behavior, we recommend using Explicit Assignment instead of Implicit Assignment. <br clear="none"> +<a name="Realm-authentication"></a></p> +<h2><a name="Realm-RealmAuthentication"></a>Realm Authentication</h2> + +<p>Once you understand Shiro's master <a href="authentication.html\#Authentication-sequence">Authentication workflow</a>, it is important to know exactly what happens when the <tt>Authenticator</tt> interacts with a <tt>Realm</tt> during an authentication attempt.</p> + +<h3><a name="Realm-Supporting%7B%7BAuthenticationTokens%7D%7D"></a>Supporting <tt>AuthenticationTokens</tt></h3> + +<p>As mentioned in the <a href="authentication.html\#Authentication-sequence">authentication sequence</a>, just before a <tt>Realm</tt> is consulted to perform an authentication attempt, its <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html\#supports(org.apache.shiro.authc.AuthenticationToken)">supports</a></tt> method is called. If the return value is <tt>true</tt>, only then will its <tt>getAuthenticationInfo(token)</tt> method be invoked.</p> + +<p>Typically a realm will check the type (interface or class) of the submitted token to see if it can process it. For example, a Realm that processes biometric data may not understand <tt>UsernamePasswordTokens</tt> at all, in which case it would return <tt>false</tt> from the <tt>supports</tt> method.</p> + +<h3><a name="Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D"></a>Handling supported <tt>AuthenticationTokens</tt></h3> + +<p>If a <tt>Realm</tt> <tt>supports</tt> a submitted <tt>AuthenticationToken</tt>, the <tt>Authenticator</tt> will call the Realm's <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html\#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)">getAuthenticationInfo(token)</a> method. This effectively represents an authentication attempt with the <tt>Realm's</tt> backing data source. The method, in order:</p> + +<ol><li>Inspects the <tt>token</tt> for the identifying principal (account identifying information)</li><li>Based on the <tt>principal</tt>, looks up corresponding account data in the data source</li><li>Ensures that the token's supplied <tt>credentials</tt> matches those stored in the data store</li><li>If the credentials match, an <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html">AuthenticationInfo</a> instance is returned that encapsulates the account data in a format Shiro understands</li><li>If the credentials DO NOT match, an <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException</a> is thrown</li></ol> + + +<p>This is the highest-level workflow for all Realm <tt>getAuthenticationInfo</tt> implementations. Realms are free to do whatever they want during this method, such as record the attempt in an audit log, update data records, or anything else that makes sense for the authentication attempt for that data store.</p> + +<p>The only thing required is that, if the credentials match for the given principal(s), that a non-null <tt>AuthenticationInfo</tt> instance is returned that represents Subject account information from that data source.</p> + +#info('Save Time', 'Implementing <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html">Realm</a></tt> interface directly might be time consuming and error prone. Most people choose to subclass the <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthorizingRealm.html">AuthorizingRealm</a> abstract class instead of starting from scratch. This class implements common authentication and authorization workflow to save you time and effort.') + +<h3><a name="Realm-CredentialsMatching"></a>Credentials Matching</h3> + +<p>In the above realm authentication workflow, a Realm has to verify that the <a href="subject.html" title="Subject">Subject</a>'s submitted credentials (e.g. password) must match the credentials stored in the data store. If they match, authentication is considered successful, and the system has verified the end-user's identity.</p> + +#warning('Realm Credentials Matching', 'It is each Realm''s responsibility to match submitted credentials with those stored in the Realm''s backing data store, and not the <tt>Authenticator''s</tt> responsibility. Each <tt>Realm</tt> has intimate knowledge of credentials format and storage and can perform detailed credentials matching, whereas the <tt>Authenticator</tt> is a generic workflow component.') + +<p>The credentials matching process is nearly identical in all applications and usually only differs by the data compared. To ensure this process is pluggable and customizable if necessary, the <a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html">AuthenticatingRealm</a> and its subclasses support the concept of a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/CredentialsMatcher.html">CredentialsMatcher</a> to perform the credentials comparison.</p> + +<p>After discovering account data, it and the submitted <tt>AuthenticationToken</tt> are presented to a <tt>CredentialsMatcher</tt> to see if what was submitted matches what is stored in the data store. </p> + +<p>Shiro has some <tt>CredentialsMatcher</tt> implementations to get you started out of the box, such as the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a> and <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher</a> implementations, but if you wanted to configure a custom implementation for custom matching logic, you could do so directly:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +Realm myRealm = <span class="code-keyword">new</span> com.company.shiro.realm.MyRealm(); +CredentialsMatcher customMatcher = <span class="code-keyword">new</span> com.company.shiro.realm.CustomCredentialsMatcher(); +myRealm.setCredentialsMatcher(customMatcher); +</pre> +</div></div> + +<p>Or, if using Shiro's INI <a href="configuration.html" title="Configuration">configuration</a>:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +[main] +... +customMatcher = com.company.shiro.realm.CustomCredentialsMatcher +myRealm = com.company.shiro.realm.MyRealm +myRealm.credentialsMatcher = $customMatcher +... +</pre> +</div></div> + + +<h4><a name="Realm-SimpleEqualityCheck"></a>Simple Equality Check</h4> + +<p>All of Shiro's out-of-the-box <tt>Realm</tt> implementations default to using a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a>. The <tt>SimpleCredentialsMatcher</tt> performs a plain direct equality check of the stored account credentials with what was submitted in the <tt>AuthenticationToken</tt>.</p> + +<p>For example, if a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a> was submitted, the <tt>SimpleCredentialsMatcher</tt> verifies that the password submitted is exactly equal to the password stored in the database.</p> + +<p>The <tt>SimpleCredentialsMatcher</tt> performs direct equality comparisons for more than just Strings though. It can work with most common byte sources, such as Strings, character arrays, byte arrays, Files and InputStreams. See its JavaDoc for more.</p> + +<h4><a name="Realm-HashingCredentials"></a>Hashing Credentials</h4> + +<p>Instead of storing credentials in their raw form and performing raw/plain comparisons, a much more secure way of storing end-user's credentials (e.g. passwords) is to one-way hash them first before storing them in the data store. </p> + +<p>This ensures that end-users' credentials are never stored in their raw form and that no one can know the original/raw value. This is a much more secure mechanism than plain-text or raw comparisons, and all security-conscious applications should favor this approach over non-hashed storage.</p> + +<p>To support these preferred cryptographic hashing strategies, Shiro provides <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher</a> implementations to be configured on realms instead of the aforementioned <tt>SimpleCredentialsMatcher</tt>.</p> + +<p>Hashing credentials and the benefits of salting and multiple hash iterations are outside the scope of this <tt>Realm</tt> documentation, but definitely read the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher JavaDoc</a> which covers these principles in detail.</p> + +<h5><a name="Realm-HashingandCorrespondingMatchers"></a>Hashing and Corresponding Matchers</h5> + +<p>So how do you configure a Shiro-enabled application to do this easily?</p> + +<p>Shiro provides multiple <tt>HashedCredentialsMatcher</tt> subclass implementations. You must configure the specific implementation on your realm to match the hashing algorithm you use to hash your users' credentials.</p> + +<p>For example, let's say your application uses username/password pairs for authentication. And due to the benefits of hashing credentials described above, let's say you want to one-way hash a user's password using the <a class="external-link" href="http://en.wikipedia.org/wiki/SHA_hash_functions"; rel="nofollow">SHA-256</a> algorithm when you create a user account. You would hash the user's entered plain-text password and save that value:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-keyword">import</span> org.apache.shiro.crypto.hash.Sha256Hash; +<span class="code-keyword">import</span> org.apache.shiro.crypto.RandomNumberGenerator; +<span class="code-keyword">import</span> org.apache.shiro.crypto.SecureRandomNumberGenerator; +... + +<span class="code-comment">//We'll use a Random <span class="code-object">Number</span> Generator to generate salts. This +</span><span class="code-comment">//is much more secure than using a username as a salt or not +</span><span class="code-comment">//having a salt at all. Shiro makes <span class="code-keyword">this</span> easy. +</span><span class="code-comment">// +</span><span class="code-comment">//Note that a normal app would reference an attribute rather +</span><span class="code-comment">//than create a <span class="code-keyword">new</span> RNG every time: +</span>RandomNumberGenerator rng = <span class="code-keyword">new</span> SecureRandomNumberGenerator(); +<span class="code-object">Object</span> salt = rng.nextBytes(); + +<span class="code-comment">//Now hash the plain-text password with the random salt and multiple +</span><span class="code-comment">//iterations and then Base64-encode the value (requires less space than Hex): +</span><span class="code-object">String</span> hashedPasswordBase64 = <span class="code-keyword">new</span> Sha256Hash(plainTextPassword, salt, 1024).toBase64(); + +User user = <span class="code-keyword">new</span> User(username, hashedPasswordBase64); +<span class="code-comment">//save the salt with the <span class="code-keyword">new</span> account. The HashedCredentialsMatcher +</span><span class="code-comment">//will need it later when handling login attempts: +</span>user.setPasswordSalt(salt); +userDAO.create(user); +</pre> +</div></div> + +<p>Since you're <tt>SHA-256</tt> hashing your user's passwords, you need to tell Shiro to use the appropriate <tt>HashedCredentialsMatcher</tt> to match your hashing preferences. In this example, we create a random salt and perform 1024 hash iterations for strong security (see the <tt>HashedCredentialsMatcher</tt> JavaDoc for why). Here is the Shiro INI configuration to make this work:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +[main] +... +credentialsMatcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher +# base64 encoding, not hex in <span class="code-keyword">this</span> example: +credentialsMatcher.storedCredentialsHexEncoded = <span class="code-keyword">false</span> +credentialsMatcher.hashIterations = 1024 +# This next property is only needed in Shiro 1.0. Remove it in 1.1 and later: +credentialsMatcher.hashSalted = <span class="code-keyword">true</span> + +... +myRealm = com.company..... +myRealm.credentialsMatcher = $credentialsMatcher +... +</pre> +</div></div> + +<h6><a name="Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"></a><tt>SaltedAuthenticationInfo</tt></h6> + +<p>The last thing to do to ensure this works is that your <tt>Realm</tt> implementation must return a <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/SaltedAuthenticationInfo.html">SaltedAuthenticationInfo</a> instance instead of a normal <tt>AuthenticationInfo</tt> one. The <tt>SaltedAuthenticationInfo</tt> interface ensures that the salt that you used when you created the user account (e.g. the <tt>user.setPasswordSalt(salt);</tt> call above) can be referenced by the <tt>HashedCredentialsMatcher</tt>.</p> + +<p>The <tt>HashedCredentialsMatcher</tt> needs the salt in order to perform the same hashing technique on the submitted <tt>AuthenticationToken</tt> to see if the token matches what you saved in the data store. So if you use salting for user passwords (and you should!!!), ensure your <tt>Realm</tt> implementation represents that by returning <tt>SaltedAuthenticationInfo</tt> instances.</p> + +<h3><a name="Realm-DisablingAuthentication"></a>Disabling Authentication</h3> + +<p>If for some reason, you don't want a Realm to perform authentication for a data source (maybe because you only want the Realm to perform authorization), you can disable a Realm's support for authentication entirely by always returning <tt>false</tt> from the Realm's <tt>supports</tt> method. Then your realm will never be consulted during an authentication attempt. </p> + +<p>Of course at least one configured <tt>Realm</tt> needs to be able to support AuthenticationTokens if you want to authenticate Subjects. </p> + +<h2><a name="Realm-RealmAuthorization"></a>Realm Authorization</h2> +<p>TBD</p> + +<h2><a name="Realm-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> + +<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> + +<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/securitymanager.html ---------------------------------------------------------------------- diff --git a/securitymanager.html b/securitymanager.html deleted file mode 100644 index 1f3c719..0000000 --- a/securitymanager.html +++ /dev/null @@ -1,77 +0,0 @@ -<h1><a name="SecurityManager-UnderstandingtheSecurityManagerinApacheShiro"></a>Understanding the SecurityManager in Apache Shiro</h1> - -<p>The <a class="external-link" href="static/current/apidocs/org/apache/shiro/mgt/SecurityManager.html">SecurityManager</a> lies at the heart of Shiro's architecture. While the <a href="subject.html" title="Subject">Subject</a> represents security functionality and state for a <em>single</em> application user, the <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users.</p> - -<p>Because Shiro's API encourages a <tt>Subject</tt>-centric programming approach, most application developers will rarely, if ever, interact with the <tt>SecurityManager</tt> directly (framework developers however might sometimes find it useful). Even so, it is still important to know how the <tt>SecurityManager</tt> functions, especially when configuring one for an application.</p> - -<h2><a name="SecurityManager-Design"></a>Design</h2> - -<p>As stated previously, the application's <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users. In Shiro's default <tt>SecurityManager</tt> implementations, this includes:</p> - -<ul> - <li>Authentication</li> - <li>Authorization</li> - <li>Session Management</li> - <li>Cache Management</li> - <li><a href="realm.html" title="Realm">Realm</a> coordination</li> - <li>Event propagation</li> - <li>"Remember Me" Services</li> - <li>Subject creation</li> - <li>Logout<br clear="none">and more.</li></ul> - -<p>But this is a lot of functionality to try to manage in a single component. And, making these things flexible and customizable would be very difficult if everything were lumped into a single implementation class. </p> - -<p>To simplify configuration and enable flexible configuration/pluggability, Shiro's implementations are all highly modular in design - so modular in fact, that the SecurityManager implementation (and its class-hierarchy) does not do much at all. Instead, the <tt>SecurityManager</tt> implementations mostly act as a lightweight 'container' component, delegating almost all behavior to nested/wrapped components.</p> - -<h3><a name="SecurityManager-Modularity"></a>Modularity</h3> - -<p>To simplify the <tt>SecurityManager</tt> implementation complexity and allow for pluggable behavior, the Shiro <tt>SecurityManager</tt> implementations delegate almost all logic to a nested set of modular components that actually perform the necessary functionality. While the components actually execute the logic, the <tt>SecurityManager</tt> implementation knows how and when to coordinate the components for the correct behavior.</p> - -<p>The nested components that the <tt>SecurityManager</tt> coordinates and delegates to are:</p> - -<ul> - <li>Authenticator (<tt>org.apache.shiro.authc.Authenticator</tt>)</li> - <li>Authorizer (<tt>org.apache.shiro.authz.Authorizer</tt>)</li> - <li>SessionManager (<tt>org.apache.shiro.session.mgt.SessionManager</tt>)</li> - <li><a href="cachemanager.html" title="CacheManager">CacheManager</a> (<tt>org.apache.shiro.cache.CacheManager</tt>)</li> - <li>RememberMeManager (<tt>org.apache.shiro.mgt.RememberMeManager</tt>)</li> - <li>SubjectFactory(<tt>org.apache.shiro.mgt.SubjectFactory</tt>)</li></ul> - - -<p>The <tt>SecurityManager</tt> implementations and are also JavaBeans compatible, which allows you (or a configuration mechanism) to easily customize the pluggable components via standard JavaBeans accessor/mutator methods (get*/set*). This means the Shiro's architectural modularity can translate into very easy configuration for custom behavior.</p> - -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Easy Configuration</b><br clear="none">Because of JavaBeans compatibility, it is very easy to configure the <tt>SecurityManager</tt> with custom components via any mechanism that supports JavaBeans-style configuration, such as <a href="spring.html" title="Spring">Spring</a>, Guice, JBoss, etc.</td></tr></table></div> - -<h3><a name="SecurityManager-ProgrammaticConfiguration"></a>Programmatic Configuration</h3> - -<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create a <tt>org.apache.shiro.mgt.DefaultSecurityManager</tt> and wire it up in code:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Realm realm = <span class="code-comment">//instantiate or acquire a Realm instance. We'll discuss Realms later. -</span><span class="code-object">SecurityManager</span> securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm); -<span class="code-comment">//Make the <span class="code-object">SecurityManager</span> instance available to the entire application: -</span>SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<p>Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for most applications. How easy was that!?</p> - -<p>You could additionally call any of the <tt>SecurityManager</tt> instance's setter methods with custom implementations of the nested components listed above to fully customize its behavior.</p> - -<p>But, as simple as programmatic customization is, these 3 lines of code do not represent the ideal configuration for most real world applications. There are a few reasons why programmatic configuration may not be suitable for your application:</p> - -<ol><li>It requires you to know about and instantiate a direct implementation. It would be nicer if you didn't have to know about concrete implementations and where to find them.</li><li>The <tt>SecurityUtils.setSecurityManager</tt> method call makes the instantiated <tt>SecurityManager</tt> instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM. It could be better if the instance was an application singleton, but not a static memory reference.</li><li>It requires you to recompile your application every time you want to make a Shiro configuration change.</li></ol> - - -<p>Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs. </p> - -<h3><a name="SecurityManager-TextConfiguration"></a>Text Configuration</h3> - -<p>Shiro provides a simple INI-based <a href="configuration.html" title="Configuration">configuration</a> that can be used out of the box, but any other JavaBeans-compatible mechanism can be used as well. For example, Shiro has excellent <a href="spring.html" title="Spring">Spring support</a> too. Other similar frameworks (Guice, JBoss, etc) could also be used.</p> - -<h2><a name="SecurityManager-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/securitymanager.html.vtl ---------------------------------------------------------------------- diff --git a/securitymanager.html.vtl b/securitymanager.html.vtl new file mode 100644 index 0000000..b98eff5 --- /dev/null +++ b/securitymanager.html.vtl @@ -0,0 +1,77 @@ +<h1><a name="SecurityManager-UnderstandingtheSecurityManagerinApacheShiro"></a>Understanding the SecurityManager in Apache Shiro</h1> + +<p>The <a class="external-link" href="static/current/apidocs/org/apache/shiro/mgt/SecurityManager.html">SecurityManager</a> lies at the heart of Shiro's architecture. While the <a href="subject.html" title="Subject">Subject</a> represents security functionality and state for a <em>single</em> application user, the <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users.</p> + +<p>Because Shiro's API encourages a <tt>Subject</tt>-centric programming approach, most application developers will rarely, if ever, interact with the <tt>SecurityManager</tt> directly (framework developers however might sometimes find it useful). Even so, it is still important to know how the <tt>SecurityManager</tt> functions, especially when configuring one for an application.</p> + +<h2><a name="SecurityManager-Design"></a>Design</h2> + +<p>As stated previously, the application's <tt>SecurityManager</tt> performs security operations and manages state for <em>all</em> application users. In Shiro's default <tt>SecurityManager</tt> implementations, this includes:</p> + +<ul> + <li>Authentication</li> + <li>Authorization</li> + <li>Session Management</li> + <li>Cache Management</li> + <li><a href="realm.html" title="Realm">Realm</a> coordination</li> + <li>Event propagation</li> + <li>"Remember Me" Services</li> + <li>Subject creation</li> + <li>Logout<br clear="none">and more.</li></ul> + +<p>But this is a lot of functionality to try to manage in a single component. And, making these things flexible and customizable would be very difficult if everything were lumped into a single implementation class. </p> + +<p>To simplify configuration and enable flexible configuration/pluggability, Shiro's implementations are all highly modular in design - so modular in fact, that the SecurityManager implementation (and its class-hierarchy) does not do much at all. Instead, the <tt>SecurityManager</tt> implementations mostly act as a lightweight 'container' component, delegating almost all behavior to nested/wrapped components.</p> + +<h3><a name="SecurityManager-Modularity"></a>Modularity</h3> + +<p>To simplify the <tt>SecurityManager</tt> implementation complexity and allow for pluggable behavior, the Shiro <tt>SecurityManager</tt> implementations delegate almost all logic to a nested set of modular components that actually perform the necessary functionality. While the components actually execute the logic, the <tt>SecurityManager</tt> implementation knows how and when to coordinate the components for the correct behavior.</p> + +<p>The nested components that the <tt>SecurityManager</tt> coordinates and delegates to are:</p> + +<ul> + <li>Authenticator (<tt>org.apache.shiro.authc.Authenticator</tt>)</li> + <li>Authorizer (<tt>org.apache.shiro.authz.Authorizer</tt>)</li> + <li>SessionManager (<tt>org.apache.shiro.session.mgt.SessionManager</tt>)</li> + <li><a href="cachemanager.html" title="CacheManager">CacheManager</a> (<tt>org.apache.shiro.cache.CacheManager</tt>)</li> + <li>RememberMeManager (<tt>org.apache.shiro.mgt.RememberMeManager</tt>)</li> + <li>SubjectFactory(<tt>org.apache.shiro.mgt.SubjectFactory</tt>)</li></ul> + + +<p>The <tt>SecurityManager</tt> implementations and are also JavaBeans compatible, which allows you (or a configuration mechanism) to easily customize the pluggable components via standard JavaBeans accessor/mutator methods (get*/set*). This means the Shiro's architectural modularity can translate into very easy configuration for custom behavior.</p> + +#tip('Easy Configuration', 'Because of JavaBeans compatibility, it is very easy to configure the <tt>SecurityManager</tt> with custom components via any mechanism that supports JavaBeans-style configuration, such as <a href="spring.html" title="Spring">Spring</a>, Guice, JBoss, etc.') + +<h3><a name="SecurityManager-ProgrammaticConfiguration"></a>Programmatic Configuration</h3> + +<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create a <tt>org.apache.shiro.mgt.DefaultSecurityManager</tt> and wire it up in code:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +Realm realm = <span class="code-comment">//instantiate or acquire a Realm instance. We'll discuss Realms later. +</span><span class="code-object">SecurityManager</span> securityManager = <span class="code-keyword">new</span> DefaultSecurityManager(realm); +<span class="code-comment">//Make the <span class="code-object">SecurityManager</span> instance available to the entire application: +</span>SecurityUtils.setSecurityManager(securityManager); +</pre> +</div></div> + +<p>Surprisingly, after only 3 lines of code, you now have a fully functional Shiro environment suitable for most applications. How easy was that!?</p> + +<p>You could additionally call any of the <tt>SecurityManager</tt> instance's setter methods with custom implementations of the nested components listed above to fully customize its behavior.</p> + +<p>But, as simple as programmatic customization is, these 3 lines of code do not represent the ideal configuration for most real world applications. There are a few reasons why programmatic configuration may not be suitable for your application:</p> + +<ol><li>It requires you to know about and instantiate a direct implementation. It would be nicer if you didn't have to know about concrete implementations and where to find them.</li><li>The <tt>SecurityUtils.setSecurityManager</tt> method call makes the instantiated <tt>SecurityManager</tt> instance a VM static singleton, which, while fine for many applications, would cause problems if more than one Shiro-enabled application was running on the same JVM. It could be better if the instance was an application singleton, but not a static memory reference.</li><li>It requires you to recompile your application every time you want to make a Shiro configuration change.</li></ol> + + +<p>Most applications instead benefit from text-based configuration that could be modified independently of source code and even make things easier to understand for those not intimately familiar with Shiro's APIs. </p> + +<h3><a name="SecurityManager-TextConfiguration"></a>Text Configuration</h3> + +<p>Shiro provides a simple INI-based <a href="configuration.html" title="Configuration">configuration</a> that can be used out of the box, but any other JavaBeans-compatible mechanism can be used as well. For example, Shiro has excellent <a href="spring.html" title="Spring">Spring support</a> too. Other similar frameworks (Guice, JBoss, etc) could also be used.</p> + +<h2><a name="SecurityManager-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> + +<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> + +<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/session-management.html ---------------------------------------------------------------------- diff --git a/session-management.html b/session-management.html index 8ba199b..63fd65c 100644 --- a/session-management.html +++ b/session-management.html @@ -84,7 +84,7 @@ session.setAttribute( <span class="code-quote">"someKey"</span>, someValue); <ul><li>If the <tt>Subject</tt> already has a <tt>Session</tt>, the boolean argument is ignored and the <tt>Session</tt> is returned immediately</li><li>If the <tt>Subject</tt> does not yet have a <tt>Session</tt> and the <tt>create</tt> boolean argument is <tt>true</tt>, a new session will be created and returned.</li><li>If the <tt>Subject</tt> does not yet have a <tt>Session</tt> and the <tt>create</tt> boolean argument is <tt>false</tt>, a new session will not be created and <tt>null</tt> is returned.</li></ul> -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Any Application</b><br clear="none"><tt>getSession</tt> calls work in any application, even non-web applications.</td></tr></table></div> +#tip('Any Application', '<tt>getSession</tt> calls work in any application, even non-web applications.') <p><tt>subject.getSession(false)</tt> can be used to good effect when developing framework code to ensure a Session isn't created unnecessarily.</p> @@ -96,7 +96,7 @@ session.setAttribute( <span class="code-quote">"someKey"</span>, someValue); <p>The default <tt>SecurityManager</tt> implementation defaults to using a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/mgt/DefaultSecurityManager.html">DefaultSessionManager</a></tt> out of the box. The <tt>DefaultSessionManager</tt> implementation provides all of the enterprise-grade session management features needed for an application, like Session validation, orphan cleanup, etc. This can be used in any application.</p> -<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web Applications</b><br clear="none">Web applications use different <tt>SessionManager</tt> implementations. Please see the <a href="web.html" title="Web">Web</a> documentation for web-specific Session Management information.</td></tr></table></div> +#info('Web Applications', 'Web applications use different <tt>SessionManager</tt> implementations. Please see the <a href="web.html" title="Web">Web</a> documentation for web-specific Session Management information.') <p>Like all other components managed by the <tt>SecurityManager</tt>, the <tt>SessionManager</tt> can be acquired or set via JavaBeans-style getter/setter methods on all of Shiro's default <tt>SecurityManager</tt> implementations (<tt>getSessionManager()</tt>/<tt>setSessionManager()</tt>). Or for example, if using <tt>shiro.ini</tt> <a href="configuration.html" title="Configuration">Configuration</a>:</p> @@ -149,7 +149,7 @@ securityManager.sessionManager.sessionListeners = $aSessionListener, $anotherSes </pre> </div></div> -<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>All Session Events</b><br clear="none"><tt>SessionListeners</tt> are notified when an event occurs for <em>any</em> session - not just for a particular session.</td></tr></table></div> +#info('All Session Events', '<tt>SessionListeners</tt> are notified when an event occurs for <em>any</em> session - not just for a particular session.') <p><a name="SessionManagement-sessionstorage"></a></p> <h3><a name="SessionManagement-SessionStorage"></a>Session Storage</h3> @@ -172,7 +172,7 @@ securityManager.sessionManager.sessionDAO = $sessionDAO <p>However, as you might expect, Shiro already has some good <tt>SessionDAO</tt> implementations that you can use out of the box or subclass for your own needs.<br clear="none"> <a name="SessionManagement-websessionmanagersessiondao"></a></p> -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web Applications</b><br clear="none">The above <tt>securityManager.sessionManager.sessionDAO = $sessionDAO</tt> assignment only works when using a Shiro native session manager. Web applications by default do not use a native session manager and instead retain the Servlet Container's default session manager which does not support a SessionDAO. If you would like to enable a SessionDAO in a web-based application for custom session storage or session clustering, you will have to first configure a native web session manager. For example: +#warning('Web Applications', 'The above <tt>securityManager.sessionManager.sessionDAO = $sessionDAO</tt> assignment only works when using a Shiro native session manager. Web applications by default do not use a native session manager and instead retain the Servlet Container's default session manager which does not support a SessionDAO. If you would like to enable a SessionDAO in a web-based application for custom session storage or session clustering, you will have to first configure a native web session manager. For example: <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> <pre class="code-java"> @@ -184,19 +184,18 @@ securityManager.sessionManager = $sessionManager # Configure a SessionDAO and then set it: securityManager.sessionManager.sessionDAO = $sessionDAO </pre> -</div></div></td></tr></table></div> +</div></div>') -<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Configure a SessionDAO!</b><br clear="none">Shiro's default configuration native SessionManagers use <b><em>in-memory-only</em></b> Session storage. This is unsuitable for most production applications. Most production applications will want to either configure the provided EHCache support (see below) or provide their own <tt>SessionDAO</tt> implementation. - -<p>Note that web applications use a servlet-container-based SessionManager by default and do not have this issue. This is only an issue when using a Shiro native SessionManager.</p></td></tr></table></div> +#danger('Configure a SessionDAO!', 'Shiro''s default configuration native SessionManagers use <b><em>in-memory-only</em></b> Session storage. This is unsuitable for most production applications. Most production applications will want to either configure the provided EHCache support (see below) or provide their own <tt>SessionDAO</tt> implementation. +<p>Note that web applications use a servlet-container-based SessionManager by default and do not have this issue. This is only an issue when using a Shiro native SessionManager.</p>') <p><a name="SessionManagement-ehcachesessiondao"></a></p> <h4><a name="SessionManagement-EHCacheSessionDAO"></a>EHCache SessionDAO</h4> <p>EHCache is not enabled by default, but if you do not plan on implementing your own <tt>SessionDAO</tt>, it is <b>highly</b> recommended that you enable the EHCache support for Shiro's SessionManagement. The EHCache SessionDAO will store sessions in memory and support overflow to disk if memory becomes constrained. This is highly desirable for production applications to ensure that you don't randomly 'lose' sessions at runtime.</p> -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Use EHCache as your default</b><br clear="none">If you're not writing a custom <tt>SessionDAO</tt>, definitely enable EHCache in your Shiro configuration. EHCache can also be beneficial beyond Sessions, caching authentication and authorization data as well. See the <a href="caching.html" title="Caching">Caching</a> documentation for more information.</td></tr></table></div> -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Container-Independent Session Clustering</b><br clear="none">EHCache is also a nice choice if you quickly need container-independent session clustering. You can transparently plug in <a class="external-link" href="http://www.terracotta.org/"; rel="nofollow">TerraCotta</a> behind EHCache and have a container-independent clustered session cache. No more worrying about Tomcat, JBoss, Jetty, WebSphere or WebLogic specific session clustering ever again!</td></tr></table></div> +#tip('Use EHCache as your default', 'If you're not writing a custom <tt>SessionDAO</tt>, definitely enable EHCache in your Shiro configuration. EHCache can also be beneficial beyond Sessions, caching authentication and authorization data as well. See the <a href="caching.html" title="Caching">Caching</a> documentation for more information.') +#tip('Container-Independent Session Clustering', 'EHCache is also a nice choice if you quickly need container-independent session clustering. You can transparently plug in <a class="external-link" href="http://www.terracotta.org/"; rel="nofollow">TerraCotta</a> behind EHCache and have a container-independent clustered session cache. No more worrying about Tomcat, JBoss, Jetty, WebSphere or WebLogic specific session clustering ever again!') <p>Enabling EHCache for sessions is very easy. First, ensure that you have the <tt>shiro-ehcache-<version>.jar</tt> file in your classpath (see the <a href="download.html" title="Download">Download</a> page or use Maven or Ant+Ivy). </p> <p>Once in the classpath, this first <tt>shiro.ini</tt> example shows you how to use EHCache for all of Shiro's caching needs (not just Session support):</p> @@ -218,7 +217,7 @@ securityManager.cacheManager = $cacheManager <p>Then, when the <tt>SessionManager</tt> asks the <tt>EnterpriseCacheSessionDAO</tt> to persist a <tt>Session</tt>, it will use an EHCache-backed <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/cache/Cache.html">Cache</a></tt> implementation to store the Session data.</p> -<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web Applications</b><br clear="none">Don't forget that assigning a <tt>SessionDAO</tt> is a feature when using Shiro native SessionManager implementations. Web applications by default use a Servlet container-based SessionManager which does not support a <tt>SessionDAO</tt>. Configure a native web SessionManager as <a href="#SessionManagement-websessionmanagersessiondao">explained above</a> if you want to use Ehcache-based session storage in a web application.</td></tr></table></div> +#info('Web Applications', 'Don't forget that assigning a <tt>SessionDAO</tt> is a feature when using Shiro native SessionManager implementations. Web applications by default use a Servlet container-based SessionManager which does not support a <tt>SessionDAO</tt>. Configure a native web SessionManager as <a href="#SessionManagement-websessionmanagersessiondao">explained above</a> if you want to use Ehcache-based session storage in a web application.') <p><a name="SessionManagement-ehcachesessioncacheconfiguration"></a></p> <h5><a name="SessionManagement-EHCacheSessionCacheConfiguration"></a>EHCache Session Cache Configuration</h5> @@ -342,7 +341,7 @@ securityManager.sessionManager.sessionValidationSchedulerEnabled = <span class=" <p>Sessions will still be validated when they are retrieved from the session data store, but this will disable Shiro's periodic validation.</p> -<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Enable Session Validation <em>somewhere</em></b><br clear="none">If you turn off Shiro's session validation scheduler, you <em>MUST</em> perform periodic session validation via some other mechanism (cron job, etc.). This is the only way to guarantee Session orphans do not fill up the data store.</td></tr></table></div> +#danger('Enable Session Validation <em>somewhere</em>', 'If you turn off Shiro's session validation scheduler, you <em>MUST</em> perform periodic session validation via some other mechanism (cron job, etc.). This is the only way to guarantee Session orphans do not fill up the data store.') <h4><a name="SessionManagement-InvalidSessionDeletion"></a>Invalid Session Deletion</h4> @@ -384,10 +383,10 @@ securityManager.sessionManager.deleteInvalidSessions = <span class="code-keyword <p>This gives you the flexibility of choosing the exact clustering mechanism that is suitable for <em>your</em> environment.</p> -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Cache Memory</b><br clear="none">Note that when enabling a distributed/enterprise cache to be your session clustering data store, one of the following two cases must be true: +#warning('Cache Memory', 'Note that when enabling a distributed/enterprise cache to be your session clustering data store, one of the following two cases must be true: <ul><li>The distributed cache has enough cluster-wide memory to retain <em>all</em> active/current sessions</li><li>If the distributed cache does not have enough cluster-wide memory to retain all active sessions, it must support disk overflow so sessions are not lost.<br clear="none"> Failure for the cache to support either of the two cases will result in sessions being randomly lost, which would likely be frustrating to end-users.</li></ul> -</td></tr></table></div> +') <h3><a name="SessionManagement-%7B%7BEnterpriseCacheSessionDAO%7D%7D"></a><tt>EnterpriseCacheSessionDAO</tt></h3> @@ -553,7 +552,7 @@ securityManager.subjectDAO.sessionStorageEvaluator.sessionStorageEnabled = <span <p>This will prevent Shiro from using a Subject's session to store that Subject's state across requests/invocations/messages <em>for all Subjects</em>. Just be sure that you authenticate on every request so Shiro will know who the Subject is for any given request/invocation/message.</p> -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Shiro's Needs vs. Your Needs</b><br clear="none">This will disable Shiro's own implementations from using Sessions as a storage strategy. It <b>DOES NOT</b> disable Sessions entirely. A session will still be created if any of your own code explicitly calls <tt>subject.getSession()</tt> or <tt>subject.getSession(true)</tt>.</td></tr></table></div> +#warning('Shiro's Needs vs. Your Needs', 'This will disable Shiro's own implementations from using Sessions as a storage strategy. It <b>DOES NOT</b> disable Sessions entirely. A session will still be created if any of your own code explicitly calls <tt>subject.getSession()</tt> or <tt>subject.getSession(true)</tt>.') <h3><a name="SessionManagement-AHybridApproach"></a>A Hybrid Approach</h3> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/static/.htaccess ---------------------------------------------------------------------- diff --git a/static/.htaccess b/static/.htaccess deleted file mode 100644 index c8e627a..0000000 --- a/static/.htaccess +++ /dev/null @@ -1 +0,0 @@ -RedirectMatch 1.1.0(.*) 1.3.2/$1 \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/subject.html ---------------------------------------------------------------------- diff --git a/subject.html b/subject.html deleted file mode 100644 index dfaab4b..0000000 --- a/subject.html +++ /dev/null @@ -1,356 +0,0 @@ -<h1><a name="Subject-UnderstandingSubjectsinApacheShiro"></a>Understanding Subjects in Apache Shiro</h1> - -<p>Without question, the most important concept in Apache Shiro is the <tt>Subject</tt>. 'Subject' is just a security term that means a security-specific 'view' of an application user. A Shiro <tt>Subject</tt> instance represents both security state and operations for a <em>single</em> application user.</p> - -<p>These operations include:</p> -<ul><li>authentication (login)</li><li>authorization (access control)</li><li>session access</li><li>logout</li></ul> - - -<p>We originally wanted to call it 'User' since that "just makes sense", but we decided against it: too many applications have existing APIs that already have their own User classes/frameworks, and we didn't want to conflict with those. Also, in the security world, the term 'Subject' is actually the recognized nomenclature.</p> - -<p>Shiro's API encourages a <tt>Subject</tt>-centric programming paradigm for applications. When coding application logic, most application developers want to know who the <em>currently executing</em> user is. While the application can usually look up any user via their own mechanisms (UserService, etc), when it comes to security, the most important question is <b>"Who is the <em>current</em> user?"</b></p> - -<p>While any Subject can be acquired by using the <tt>SecurityManager</tt>, application code based on only the current user/<tt>Subject</tt> is much more natural and intuitive.</p> - -<h2><a name="Subject-TheCurrentlyExecutingSubject"></a>The Currently Executing Subject</h2> - -<p>In almost all environments, you can obtain the currently executing <tt>Subject</tt> by using <tt>org.apache.shiro.SecurityUtils</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject currentUser = SecurityUtils.getSubject(); -</pre> -</div></div> - -<p>The <tt>getSubject()</tt> call in a standalone application might return a <tt>Subject</tt> based on user data in an application-specific location, and in a server environment (e.g. web app), it acquires the Subject based on user data associated with current thread or incoming request.</p> - -<p>After you acquire the current <tt>Subject</tt>, what can you do with it?</p> - -<p>If you want to make things available to the user during their current session with the application, you can get their session:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Session session = currentUser.getSession(); -session.setAttribute( <span class="code-quote">"someKey"</span>, <span class="code-quote">"aValue"</span> ); -</pre> -</div></div> - -<p>The <tt>Session</tt> is a Shiro-specific instance that provides most of what you're used to with regular HttpSessions but with some extra goodies and one <b>big</b> difference: it does not require an HTTP environment!</p> - -<p>If deploying inside a web application, by default the <tt>Session</tt> will be <tt>HttpSession</tt> based. But, in a non-web environment, like this simple Quickstart, Shiro will automatically use its Enterprise Session Management by default. This means you get to use the same API in your applications, in any tier, regardless of deployment environment. This opens a whole new world of applications since any application requiring sessions does not need to be forced to use the <tt>HttpSession</tt> or EJB Stateful Session Beans. And, any client technology can now share session data.</p> - -<p>So now you can acquire a <tt>Subject</tt> and their <tt>Session</tt>. What about the <em>really</em> useful stuff like checking if they are allowed to do things, like checking against roles and permissions?</p> - -<p>Well, we can only do those checks for a known user. Our <tt>Subject</tt> instance above represents the current user, but <em>who</em> is actually the current user? Well, they're anonymous - that is, until they log in at least once. So, let's do that:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( !currentUser.isAuthenticated() ) { - <span class="code-comment">//collect user principals and credentials in a gui specific manner -</span> <span class="code-comment">//such as username/password html form, X509 certificate, OpenID, etc. -</span> <span class="code-comment">//We'll use the username/password example here since it is the most common. -</span> <span class="code-comment">//(<span class="code-keyword">do</span> you know what movie <span class="code-keyword">this</span> is from? ;) -</span> UsernamePasswordToken token = <span class="code-keyword">new</span> UsernamePasswordToken(<span class="code-quote">"lonestarr"</span>, <span class="code-quote">"vespa"</span>); - <span class="code-comment">//<span class="code-keyword">this</span> is all you have to <span class="code-keyword">do</span> to support 'remember me' (no config - built in!): -</span> token.setRememberMe(<span class="code-keyword">true</span>); - currentUser.login(token); -} -</pre> -</div></div> - -<p>That's it! It couldn't be easier.</p> - -<p>But what if their login attempt fails? You can catch all sorts of specific exceptions that tell you exactly what happened:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">try</span> { - currentUser.login( token ); - <span class="code-comment">//<span class="code-keyword">if</span> no exception, that's it, we're done! -</span>} <span class="code-keyword">catch</span> ( UnknownAccountException uae ) { - <span class="code-comment">//username wasn't in the system, show them an error message? -</span>} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice ) { - <span class="code-comment">//password didn't match, <span class="code-keyword">try</span> again? -</span>} <span class="code-keyword">catch</span> ( LockedAccountException lae ) { - <span class="code-comment">//account <span class="code-keyword">for</span> that username is locked - can't login. Show them a message? -</span>} - ... more types exceptions to check <span class="code-keyword">if</span> you want ... -} <span class="code-keyword">catch</span> ( AuthenticationException ae ) { - <span class="code-comment">//unexpected condition - error? -</span>} -</pre> -</div></div> - -<p>You, as the application/GUI developer can choose to show the end-user messages based on exceptions or not (for example, <tt>"There is no account in the system with that username."</tt>). There are many different types of exceptions you can check, or throw your own for custom conditions Shiro might not account for. See the <a class="external-link" href="http://www.jsecurity.org/api/org/jsecurity/authc/AuthenticationException.html"; rel="nofollow">AuthenticationException JavaDoc</a> for more.</p> - -<p>Ok, so by now, we have a logged in user. What else can we do?</p> - -<p>Let's say who they are:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//print their identifying principal (in <span class="code-keyword">this</span> <span class="code-keyword">case</span>, a username): -</span>log.info( <span class="code-quote">"User ["</span> + currentUser.getPrincipal() + <span class="code-quote">"] logged in successfully."</span> ); -</pre> -</div></div> - -<p>We can also test to see if they have specific role or not:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.hasRole( <span class="code-quote">"schwartz"</span> ) ) { - log.info(<span class="code-quote">"May the Schwartz be with you!"</span> ); -} <span class="code-keyword">else</span> { - log.info( <span class="code-quote">"Hello, mere mortal."</span> ); -} -</pre> -</div></div> - -<p>We can also see if they have a <a href="permissions.html" title="Permissions">permission</a> to act on a certain type of entity:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"lightsaber:weild"</span> ) ) { - log.info(<span class="code-quote">"You may use a lightsaber ring. Use it wisely."</span>); -} <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, lightsaber rings are <span class="code-keyword">for</span> schwartz masters only."</span>); -} -</pre> -</div></div> - -<p>Also, we can perform an extremely powerful <em>instance-level</em> <a href="permissions.html" title="Permissions">permission</a> check - the ability to see if the user has the ability to access a specific instance of a type:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"winnebago:drive:eagle5"</span> ) ) { - log.info(<span class="code-quote">"You are permitted to 'drive' the 'winnebago' with license plate (id) 'eagle5'. "</span> + - <span class="code-quote">"Here are the keys - have fun!"</span>); -} <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, you aren't allowed to drive the 'eagle5' winnebago!"</span>); -} -</pre> -</div></div> - -<p>Piece of cake, right?</p> - -<p>Finally, when the user is done using the application, they can log out:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -currentUser.logout(); <span class="code-comment">//removes all identifying information and invalidates their session too.</span> -</pre> -</div></div> - -<p>This simple API constitutes 90% of what Shiro end-users will ever have to deal with when using Shiro.</p> - -<h2><a name="Subject-CustomSubjectInstances"></a>Custom Subject Instances</h2> - -<p>A new feature added in Shiro 1.0 is the ability to construct custom/ad-hoc subject instances for use in special situations.</p> - -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Special Use Only!</b><br clear="none">You should almost always acquire the currently executing Subject by calling <tt>SecurityUtils.getSubject();</tt><br clear="none"> -Creating custom <tt>Subject</tt> instances should only be done in special cases.</td></tr></table></div> - -<p>Some 'special cases' when this can be useful:</p> - -<ul><li>System startup/bootstrap - when there are no users interacting with the system, but code should execute as a 'system' or daemon user. It is desirable to create Subject instances representing a particular user so bootstrap code executes as that user (e.g. as the <tt>admin</tt> user). -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"> -This practice is encouraged because it ensures that utility/system code executes in the same way as a normal user, ensuring code is consistent. This makes code easier to maintain since you don't have to worry about custom code blocks just for system/daemon scenarios. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>Integration <a href="testing.html" title="Testing">Testing</a> - you might want to create <tt>Subject</tt> instances as necessary to be used in integration tests. See the <a href="testing.html" title="Testing">testing documentation</a> for more. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>Daemon/background process work - when a daemon or background process executes, it might need to execute as a particular user.</li></ul> - - -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">If you already have access to a <tt>Subject</tt> instance and want it to be available to other threads, you should use the <tt>Subject.associateWith</tt>* methods instead of creating a new Subject instance.</td></tr></table></div> - -<p>Ok, so assuming you still need to create custom subject instances, let's see how to do it:</p> - -<h3><a name="Subject-Subject.Builder"></a>Subject.Builder</h3> - -<p>The <tt>Subject.Builder</tt> class is provided to build <tt>Subject</tt> instances easily without needing to know construction details.</p> - -<p>The simplest usage of the Builder is to construct an anonymous, session-less <tt>Subject</tt> instance:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-keyword">new</span> Subject.Builder().buildSubject() -</pre> -</div></div> - -<p>The default, no-arg <tt>Subject.Builder()</tt> constructor shown above will use the application's currently accessible <tt>SecurityManager</tt> via the <tt>SecurityUtils.getSecurityManager()</tt> method. You may also specify the <tt>SecurityManager</tt> instance to be used by the additional constructor if desired:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">SecurityManager</span> securityManager = <span class="code-comment">//acquired from somewhere -</span>Subject subject = <span class="code-keyword">new</span> Subject.Builder(securityManager).buildSubject(); -</pre> -</div></div> - -<p>All other <tt>Subject.Builder</tt> methods may be called before the <tt>buildSubject()</tt> method to provide context on how to construct the <tt>Subject</tt> instance. For example, if you have a session ID and want to acquire the <tt>Subject</tt> that 'owns' that session (assuming the session exists and is not expired):</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Serializable sessionId = <span class="code-comment">//acquired from somewhere -</span>Subject subject = <span class="code-keyword">new</span> Subject.Builder().sessionId(sessionId).buildSubject(); -</pre> -</div></div> - -<p>Similarly, if you want to create a <tt>Subject</tt> instance that reflects a certain identity:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">Object</span> userIdentity = <span class="code-comment">//a <span class="code-object">long</span> ID or <span class="code-object">String</span> username, or whatever the <span class="code-quote">"myRealm"</span> requires -</span><span class="code-object">String</span> realmName = <span class="code-quote">"myRealm"</span>; -PrincipalCollection principals = <span class="code-keyword">new</span> SimplePrincipalCollection(userIdentity, realmName); -Subject subject = <span class="code-keyword">new</span> Subject.Builder().principals(principals).buildSubject(); -</pre> -</div></div> - -<p>You can then use the built <tt>Subject</tt> instance and make calls on it as expected. But <b>note</b>: </p> - -<p>The built <tt>Subject</tt> instance is <b>not</b> automatically bound to the application (thread) for further use. If you want it to be available to any code that calls <tt>SecurityUtils.getSubject()</tt>, you must ensure a Thread is associated with the constructed <tt>Subject</tt>.</p> - -<h3><a name="Subject-ThreadAssociation"></a>Thread Association <a name="Subject-ThreadAssociation"></a></h3> - -<p>As stated above, just building a <tt>Subject</tt> instance does not associate it with a thread - a usual requirement if any calls to <tt>SecurityUtils.getSubject()</tt> during thread execution are to work properly. There are three ways of ensuring a thread is associated with a <tt>Subject</tt>:</p> - -<ul><li><b>Automatic Association</b> - A <tt>Callable</tt> or <tt>Runnable</tt> executed via the <tt>Subject.execute</tt>* methods will automatically bind and unbind the Subject to the thread before and after <tt>Callable</tt>/<tt>Runnable</tt> execution. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Manual Association</b> - You manually bind and unbind the <tt>Subject</tt> instance to the currently executing thread. This is usually useful for framework developers. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li><b>Different Thread</b> - A <tt>Callable</tt> or <tt>Runnable</tt> is associated with a <tt>Subject</tt> by calling the <tt>Subject.associateWith</tt>* methods and then the returned <tt>Callable</tt>/<tt>Runnable</tt> is executed by another thread. This is the preferred approach if you need to execute work on another thread as the <tt>Subject</tt>.</li></ul> - - -<p>The important thing to know about thread association is that 2 things must always occur:</p> - -<ol><li>The Subject is <em>bound</em> to the thread so it is available at all points of the thread's execution. Shiro does this via its <tt>ThreadState</tt> mechanism which is an abstraction on top of a <tt>ThreadLocal</tt>.</li><li>The Subject is <em>unbound</em> at some point later, even if the thread execution results in an error. This ensures the thread remains clean and clear of any previous <tt>Subject</tt> state in a pooled/reusable thread environment.</li></ol> - - -<p>These principles are guaranteed to occur in the 3 mechanisms listed above. Their usage is elaborated next.</p> - -<h4><a name="Subject-AutomaticAssociation"></a>Automatic Association </h4> - -<p>If you only need a <tt>Subject</tt> to be temporarily associated with the current thread, and you want the thread binding and cleanup to occur automatically, a <tt>Subject</tt>'s direct execution of a <tt>Callable</tt> or <tt>Runnable</tt> is the way to go. After the <tt>Subject.execute</tt> call returns, the current thread is guaranteed to be in the same state as it was before the execution. This mechanism is the most widely used of the three.</p> - -<p>For example, let's say that you had some logic to perform when the system starts up. You want to execute a chunk of code as a particular user, but once the logic is finished, you want to ensure the thread/environment goes back to normal automatically. You would do that by calling the <tt>Subject.execute</tt>* methods:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-comment">//build or acquire subject -</span>subject.execute( <span class="code-keyword">new</span> <span class="code-object">Runnable</span>() { - <span class="code-keyword">public</span> void run() { - <span class="code-comment">//subject is 'bound' to the current thread now -</span> <span class="code-comment">//any SecurityUtils.getSubject() calls in any -</span> <span class="code-comment">//code called from here will work -</span> } -}); -<span class="code-comment">//At <span class="code-keyword">this</span> point, the Subject is no longer associated -</span><span class="code-comment">//with the current thread and everything is as it was before</span> -</pre> -</div></div> - -<p>Of course <tt>Callable</tt> instances are supported as well so you can have return values and catch exceptions:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-comment">//build or acquire subject -</span>MyResult result = subject.execute( <span class="code-keyword">new</span> Callable<MyResult>() { - <span class="code-keyword">public</span> MyResult call() <span class="code-keyword">throws</span> Exception { - <span class="code-comment">//subject is 'bound' to the current thread now -</span> <span class="code-comment">//any SecurityUtils.getSubject() calls in any -</span> <span class="code-comment">//code called from here will work -</span> ... - <span class="code-comment">//finish logic as <span class="code-keyword">this</span> Subject -</span> ... - <span class="code-keyword">return</span> myResult; - } -}); -<span class="code-comment">//At <span class="code-keyword">this</span> point, the Subject is no longer associated -</span><span class="code-comment">//with the current thread and everything is as it was before</span> -</pre> -</div></div> - -<p>This approach is also useful in framework development. For example, Shiro's support for secure Spring remoting ensures the remote invocation is executed as a particular subject:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject.Builder builder = <span class="code-keyword">new</span> Subject.Builder(); -<span class="code-comment">//populate the builder's attributes based on the incoming RemoteInvocation -</span>... -Subject subject = builder.buildSubject(); - -<span class="code-keyword">return</span> subject.execute(<span class="code-keyword">new</span> Callable() { - <span class="code-keyword">public</span> <span class="code-object">Object</span> call() <span class="code-keyword">throws</span> Exception { - <span class="code-keyword">return</span> invoke(invocation, targetObject); - } -}); -</pre> -</div></div> - -<h4><a name="Subject-ManualAssociation"></a>Manual Association</h4> - -<p>While the <tt>Subject.execute</tt>* methods automatically clean up the thread state after they return, there might be some scenarios where you want to manage the <tt>ThreadState</tt> yourself. This is almost always done in framework-level development when integrating w/ Shiro and is rarely used even in bootstrap/daemon scenarios (where the <tt>Subject.execute(callable)</tt> example above is more frequent).</p> - -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Guarantee Cleanup</b><br clear="none">The most important thing about this mechanism is that you must <em>always</em> guarantee the current thread is cleaned up after logic is executed to ensure there is no thread state corruption in a reusable or pooled thread environment.</td></tr></table></div> - -<p>Guaranteeing cleanup is best done in a <tt>try/finally</tt> block:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-keyword">new</span> Subject.Builder()... -ThreadState threadState = <span class="code-keyword">new</span> SubjectThreadState(subject); -threadState.bind(); -<span class="code-keyword">try</span> { - <span class="code-comment">//execute work as the built Subject -</span>} <span class="code-keyword">finally</span> { - <span class="code-comment">//ensure any state is cleaned so the thread won't be -</span> <span class="code-comment">//corrupt in a reusable or pooled thread environment -</span> threadState.clear(); -} -</pre> -</div></div> - -<p>Interestingly enough, this is exactly what the <tt>Subject.execute</tt>* methods do - they just perform this logic automatically before and after <tt>Callable</tt> or <tt>Runnable</tt> execution. It is also nearly identical logic performed by Shiro's <tt>ShiroFilter</tt> for web applications (<tt>ShiroFilter</tt> uses web-specific <tt>ThreadState</tt> implementations outside the scope of this section).</p> - -<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web Use</b><br clear="none">Don't use the above <tt>ThreadState</tt> code example in a thread that is processing a web request. Web-specific ThreadState implementations are used during web requests instead. Instead, ensure the <tt>ShiroFilter</tt> intercepts web requests to ensure Subject building/binding/cleanup is done properly.</td></tr></table></div> - -<h4><a name="Subject-ADifferentThread"></a>A Different Thread</h4> - -<p>If you have a <tt>Callable</tt> or <tt>Runnable</tt> instance that should execute as a <tt>Subject</tt> and you will execute the <tt>Callable</tt> or <tt>Runnable</tt> yourself (or hand it off to a thread pool or <tt>Executor</tt> or <tt>ExecutorService</tt> for example), you should use the <tt>Subject.associateWith</tt>* methods. These methods ensure that the Subject is retained and accessible on the thread that eventually executes.</p> - -<p>Callable example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-keyword">new</span> Subject.Builder()... -Callable work = <span class="code-comment">//build/acquire a Callable instance. -</span><span class="code-comment">//associate the work with the built subject so SecurityUtils.getSubject() calls works properly: -</span>work = subject.associateWith(work); -ExecutorService executorService = <span class="code-keyword">new</span> java.util.concurrent.Executors.newCachedThreadPool(); -<span class="code-comment">//execute the work on a different thread as the built Subject: -</span>executor.execute(work); -</pre> -</div></div> - -<p>Runnable example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject subject = <span class="code-keyword">new</span> Subject.Builder()... -<span class="code-object">Runnable</span> work = <span class="code-comment">//build/acquire a <span class="code-object">Runnable</span> instance. -</span><span class="code-comment">//associate the work with the built subject so SecurityUtils.getSubject() calls works properly: -</span>work = subject.associateWith(work); -Executor executor = <span class="code-keyword">new</span> java.util.concurrent.Executors.newCachedThreadPool(); -<span class="code-comment">//execute the work on a different thread as the built Subject: -</span>executor.execute(work); -</pre> -</div></div> - -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Automatic Cleanup</b><br clear="none">The <tt>associateWith</tt>* methods perform necessary thread cleanup automatically to ensure threads remain clean in a pooled environment.</td></tr></table></div> - -<h2><a name="Subject-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> \ No newline at end of file
![https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"){kind=link}