shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r1481417 [9/13] - in /shiro/site: ./ 2010/ 2011/ 2012/ assets/ templates/ trunk/ trunk/2010/ trunk/2010/03/ trunk/2010/03/18/ trunk/2010/06/ trunk/2010/06/01/ trunk/2010/09/ trunk/2010/09/14/ trunk/2010/09/20/ trunk/2010/09/24/ trunk/2010/1...
Date Sat, 11 May 2013 21:10:45 GMT
Added: shiro/site/trunk/permissions.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/permissions.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/permissions.html (added)
+++ shiro/site/trunk/permissions.html Sat May 11 21:10:40 2013
@@ -0,0 +1,302 @@
+<h1><a name="Permissions-UnderstandingPermissionsinApacheShiro"></a>Understanding Permissions in Apache Shiro</h1>
+
+<p>Shiro defines a Permission as a statement that defines an explicit behavior or action.  It is a statement of raw functionality in an application and nothing more.  Permissions are the lowest-level constructs in security polices, and they explicitly define only "what" the application can do.</p>
+
+<p>They do <em>not</em> at all describe "who" is able to perform the action(s).</p>
+
+<p>Some examples of permissions:</p>
+<ul><li>Open a file</li><li>View the '/user/list' web page</li><li>Print documents</li><li>Delete the 'jsmith' user</li></ul>
+
+
+<p>Defining "who" (users) is allowed to do "what" (permissions) is an exercise of assigning permissions to users in some way.  This is always done by the application's data model and can vary greatly across applications.  </p>
+
+<p>For example, permissions can be grouped in a Role and that Role could be associated with one or more User objects.  Or some applications can have a Group of users and a Group can be assigned a Role, which by transitive association would mean that all the Users in that Group are implicitly granted the permissions in the Role.</p>
+
+<p>There are many variations for how permissions could be granted to users - the application determines how to model this based on the application requirements.</p>
+
+<h2><a name="Permissions-WildcardPermissions"></a>Wildcard Permissions</h2>
+
+<p>The above examples of permissions, "Open a file", "View the 'user/list' web page", etc are all valid permission statements.  However, it would be very difficult computationally to interpret those natural language strings and determine if a user is allowed to perform that behavior or not.</p>
+
+<p>So to enable easy-to-process yet still readable permission statements, Shiro provides powerful and intuitive permission syntax we refer to as the WildcardPermission.</p>
+
+<h3><a name="Permissions-SimpleUsage"></a>Simple Usage</h3>
+
+<p>Let's you want to protect access to your company's printers such that some people can print to particular printers, while others can query what jobs are currently in the queue. </p>
+
+<p>An extremely simple approach would be to use grant the user a "queryPrinter" permission.  Then you could check to see if the user has the queryPrinter permission by calling:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+subject.isPermitted(<span class="code-quote">"queryPrinter"</span>)
+</pre>
+</div></div>
+
+<p>This is (mostly) equivalent to</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+subject.isPermitted( <span class="code-keyword">new</span> WildcardPermission(<span class="code-quote">"queryPrinter"</span>) )
+</pre>
+</div></div>
+
+<p>but more on that later.</p>
+
+<p>The simple permission string may work for simple applications, but it requires you to have permissions like "printPrinter", "queryPrinter", "managePrinter", etc.  You can also grant a user "*" permissions using the wildcard character (giving this permission construct its name), which means they have <b><em>all</em></b> permissions across <em>the entire application</em>.  </p>
+
+<p>But using this approach there's no way to just say a user has "all printer permissions".  For this reason, Wildcard Permissions supports multiple <em>levels</em> of permissioning. </p>
+
+<h3><a name="Permissions-MultipleParts"></a>Multiple Parts</h3>
+
+<p>Wildcard Permissions support the concept of multiple <em>levels</em> or <em>parts</em>. For example, you could restructure the previous simple example by granting a user the permission </p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:query
+</pre>
+</div></div>
+<p>The colon in this example is a special character used to delimit the next part in the permission string.</p>
+
+<p>In this example, the first part is the domain that is being operated on (<tt>printer</tt>) and the second part is the action (<tt>query</tt>) being performed. The other above examples would be changed to:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print
+printer:manage
+</pre>
+</div></div>
+
+<p>There is no limit to the number of parts that can be used, so it is up to your imagination in terms of ways that this could be used in your application.</p>
+
+<h4><a name="Permissions-MultipleValues"></a>Multiple Values</h4>
+
+<p>Each part can contain multiple values. So instead of granting the user both the "printer:print" and "printer:query" permissions, you could simply grant them one: </p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print,query
+</pre>
+</div></div>
+
+<p>which gives them the ability to <tt>print</tt> and <tt>query</tt> printers.  And since they are granted both those actions, you could check to see if the user has the ability to query printers by calling:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+subject.isPermitted(<span class="code-quote">"printer:query"</span>)
+</pre>
+</div></div>
+<p>which would return <tt>true</tt></p>
+
+<h4><a name="Permissions-AllValues"></a>All Values</h4>
+
+<p>What if you wanted to grant a user <em>all</em> values in a particular part?  It would be more convenient to do this than to have to manually list every value.  Again, based on the wildcard character, we can do this.  If the <tt>printer</tt> domain had 3 possible actions (<tt>query</tt>, <tt>print</tt>, and <tt>manage</tt>), this:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:query,print,manage
+</pre>
+</div></div>
+<p>simply becomes this:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:*
+</pre>
+</div></div>
+
+<p>Then, <em>any</em> permission check for "printer:XXX" will return <tt>true</tt>.  Using the wildcard in this way scales better than explicitly listing actions since, if you added a new action to the application later, you don't need to update the permissions that use the wildcard character in that part.</p>
+
+<p>Finally, it is also possible to use the wildcard token in any part of a wildcard permission string. For example, if you wanted to grant a user the "view" action across <em>all</em> domains (not just printers), you could grant this:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+*:view
+</pre>
+</div></div>
+
+<p>Then any permission check for "foo:view" would return <tt>true</tt></p>
+
+<h3><a name="Permissions-InstanceLevelAccessControl"></a>Instance-Level Access Control</h3>
+
+<p>Another common usage of wildcard permissions is to model instance-level Access Control Lists. In this scenario you use three parts - the first is the <em>domain</em>, the second is the <em>action</em>(s), and the third is the instance(s) being acted upon.</p>
+
+<p>So for example you could have</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:query:lp7200
+printer:print:epsoncolor
+</pre>
+</div></div>
+
+<p>The first defines the behavior to <tt>query</tt> the <tt>printer</tt> with the ID <tt>lp7200</tt>.  The second permission defines the behavior to <tt>print</tt> to the <tt>printer</tt> with ID <tt>epsoncolor</tt>.  If you grant these permissions to users, then they can perform specific behavior on <em>specific instances</em>.  Then you can do a check in code:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( SecurityUtils.getSubject().isPermitted(<span class="code-quote">"printer:query:lp7200"</span>) {
+    <span class="code-comment">// Return the current jobs on printer lp7200
+</span>}
+</pre>
+</div></div>
+
+<p>This is an extremely powerful way to express permissions.  But again, having to define multiple instance IDs for all printers does not scale well, particularly when new printers are added to the system.  You can instead use a wildcard:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print:*
+</pre>
+</div></div>
+
+<p>This does scale, because it covers any new printers as well. You could even allow access to all actions on all printers:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:*:*
+</pre>
+</div></div>
+
+<p>or all actions on a single printer:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:*:lp7200
+</pre>
+</div></div>
+
+<p>or even specific actions:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:query,print:lp7200
+</pre>
+</div></div>
+
+<p>The '*' wildcard and ',' sub-part separator can be used in any part of the permission.</p>
+
+<h4><a name="Permissions-MissingParts"></a>Missing Parts</h4>
+
+<p>One final thing to note about permission assignments: missing parts imply that the user has access to all values corresponding to that part. In other words,</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print
+</pre>
+</div></div>
+
+<p>is equivalent to</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print:*
+</pre>
+</div></div>
+
+<p>and</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer
+</pre>
+</div></div>
+
+<p>is equivalent to</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:*:*
+</pre>
+</div></div>
+
+<p>However, you can only leave off parts from the <em>end</em> of the string, so this:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:lp7200
+</pre>
+</div></div>
+
+<p>is <b><em>not</em></b> equivalent to</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:*:lp7200
+</pre>
+</div></div>
+
+<h2><a name="Permissions-CheckingPermissions"></a>Checking Permissions</h2>
+
+<p>While permission assignments use the wildcard construct quite a bit ("printer:print:*" = print to any printer) for convenience and scalability, permission <b>checks</b> at runtime should <em>always</em> be based on the most specific permission string possible.</p>
+
+<p>For example, if the user had a UI and they wanted to print a document to the <tt>lp7200</tt> printer, you <b>should</b> check if the user is permitted to do so by executing this code:<br clear="none">
+<font color=""></font></p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( SecurityUtils.getSubject().isPermitted(<span class="code-quote">"printer:print:lp7200"</span>) ) {
+    <span class="code-comment">//print the document to the lp7200 printer
+</span>}
+</pre>
+</div></div>
+
+<p>That check is very specific and explicitly reflects what the user is attempting to do at that moment in time.  </p>
+
+
+<p>The following however is much less ideal for a runtime check:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">if</span> ( SecurityUtils.getSubject().isPermitted(<span class="code-quote">"printer:print"</span>) ) {
+    <span class="code-comment">//print the document
+</span>}
+</pre>
+</div></div>
+
+<p>Why?  Because the second example says "You must be able to print to <b>any</b> printer for the following code block to execute".  But remember that "printer:print" is equivalent to "printer:print:*"!  </p>
+
+<p>Therefore, this is an incorrect check.  What if the current user does not have the ability to print to any printer, but they <b>do</b> have the ability to print to say, the <tt>lp7200</tt> and <tt>epsoncolor</tt> printers.  Then the 2nd example above would never allow them to print to the <tt>lp7200</tt> printer even though they have been granted that ability!</p>
+
+<p>So the rule of thumb is to use the most specific permission string possible when performing permission checks.  Of course, the 2nd block above might be a valid check somewhere else in the application if you really did only want to execute the code block if the user was allowed to print to any printer (suspect, but possible).  Your application will determine what checks make sense, but in general, the more specific, the better.</p>
+
+<h2><a name="Permissions-Implication%2CnotEquality"></a>Implication, not Equality</h2>
+
+<p>Why is it that runtime permission checks should be as specific as possible, but permission assignments can be a little more generic?  It is because the permission checks are evaluated by <em>implication</em> logic - not equality checks.</p>
+
+<p>That is, if a user is assigned the <tt>user:*</tt> permission, this <em>implies</em> that the user can perform the <tt>user:view</tt> action.  The string "user:*" is clearly not equal to "user:view", but the former implies the latter.  "user:*" describes a superset of functionality of that defined by "user:view".</p>
+
+<p>To support implication rules, all permissions are translated in to object instances that implement the <tt>org.apache.shiro.authz.Permission</tt> interface.  This is so that implication logic can be executed at runtime and that implication logic is often more complex than a simple string equality check.  All of the wildcard behavior described in this document is actually made possible by the <tt>org.apache.shiro.authz.permission.WildcardPermission</tt> class implementation. Here are some more wildcard permission strings that show access by implication:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+user:*
+</pre>
+</div></div>
+<p><em>implies</em> the ability to also delete a user:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+user:delete
+</pre>
+</div></div>
+
+<p>Similarly,</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+user:*:12345
+</pre>
+</div></div>
+<p><em>implies</em> the ability to also update user account with ID 12345:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+user:update:12345
+</pre>
+</div></div>
+
+<p>and</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer
+</pre>
+</div></div>
+<p><em>implies</em> the ability to print to any printer</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+printer:print
+</pre>
+</div></div>
+
+<h2><a name="Permissions-PerformanceConsiderations"></a>Performance Considerations</h2>
+
+<p>Permission checks are more complex than a simple equals comparison, so runtime implication logic must execute for each assigned Permission.  When using permission strings like the ones shown above, you're implicitly using Shiro's default <tt>WildcardPermission</tt> which executes the necessary implication logic.</p>
+
+<p>Shiro's default behavior for Realm implementations is that, for every permission check (for example, a call to <tt>subject.isPermitted</tt> ), <em>all</em> of the permissions assigned to that user (in their Groups, Roles, or directly assigned to them) need to be checked individually for implication.  Shiro 'short circuits' this process by returning immediately after the first successful check occurs to increase performance, but it is not a silver bullet.</p>
+
+<p>This is usually extremely fast when users, roles and permissions are cached in memory when using a proper <a href="cachemanager.html" title="CacheManager">CacheManager</a>, which Shiro does support for Realm implementations.  Just know that with this default behavior, as the number of permissions assigned to a user or their roles or groups increase, the time to perform the check will necessarily increase.</p>
+
+<p>If a Realm implementor has a more efficient way of checking permissions and performing this implication logic, especially if based on the applicaton's data model, they should implement that as part of their Realm isPermitted* method implementations.  The default Realm/WildcardPermission support exists to cover 80-90% of most use cases, but it might not be the best solution for applications that have massive amounts of permissions to store and/or check at runtime.</p>
+
+<h2><a name="Permissions-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

Added: shiro/site/trunk/powered-by-shiro.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/powered-by-shiro.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/powered-by-shiro.html (added)
+++ shiro/site/trunk/powered-by-shiro.html Sat May 11 21:10:40 2013
@@ -0,0 +1,26 @@
+<h1><a name="PoweredbyShiro-OrganizationsusingApacheShiro"></a>Organizations using Apache Shiro</h1>
+
+<p>Please consider adding yourself to the Apache Shiro PoweredBy wiki page.  By letting others know that you are using Shiro, you help expand the community and in turn improve Shiro.  Win/Win!</p>
+
+<h3><a name="PoweredbyShiro-Katasoft"></a><a class="external-link" href="http://www.katasoft.com" rel="nofollow">Katasoft</a></h3>
+<p>Katasoft builds software products that make application security easy for developers and their organization.  Les Hazlewood, the Apache Shiro PMC Chair, is Katasoft's founder and CTO.</p>
+<ul><li>Katasoft uses Shiro as the core security subsystem for all of their products.</li><li>Shiro is used to support Katasoft's Single Sign-On (SSO) architecture.</li><li>Shiro's pluggable Realm architecture is used by Katasoft's runtime plugin system to allow changing an application's Realms at runtime, without requiring a server restart.</li></ul>
+
+
+<h3><a name="PoweredbyShiro-LargeFinancialInformationProvider"></a>Large Financial Information Provider</h3>
+<p>Using Shiro in a large scale external web application for authentication, authorization, and custom Session clustering in an enterprise clustered cache</p>
+
+<h3><a name="PoweredbyShiro-MuleSoft"></a><a class="external-link" href="http://mulesoft.com" rel="nofollow">MuleSoft</a></h3>
+<p>The company behind <a class="external-link" href="http://mulesoft.org" rel="nofollow">Mule</a>, MuleSoft is behind the leading open source middleware, making integration and managing applications easier for everyone.</p>
+
+<p>Mule uses Shiro to provide authentication and authorization to hosted services and resources. This allows users to secure HTTP/REST services, Web Services, message queues, data and file access with the simplicity of  Shiro.</p>
+
+<h3><a name="PoweredbyShiro-Sonatype"></a><a class="external-link" href="http://www.sonatype.com" rel="nofollow">Sonatype</a></h3>
+<p>The company behind <a class="external-link" href="http://maven.apache.org">Maven</a>, Sonatype streamlines infrastructure and development workflows for Maven-centric development environments.</p>
+<ul><li>Sonatype uses Shiro to secure <a class="external-link" href="http://www.sonatype.com/nexus-professional.html" rel="nofollow">Nexus</a>, the leading open-source and professional Maven repository manager.</li></ul>
+
+
+
+<h2><a name="PoweredbyShiro-Template"></a>Template</h2>
+<p><a class="external-link" href="http://www.apache.org">Your Company Name</a> - Your company description</p>
+<ul><li>Any details you can share</li><li>...</li></ul>

Added: shiro/site/trunk/privacy-policy.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/privacy-policy.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/privacy-policy.html (added)
+++ shiro/site/trunk/privacy-policy.html Sat May 11 21:10:40 2013
@@ -0,0 +1,11 @@
+<h1><a name="PrivacyPolicy-ApacheShiroPrivacyPolicy"></a>Apache Shiro Privacy Policy</h1>
+
+<p>Information about your use of this website is collected using server access logs and a tracking cookie. The collected information consists of the following:</p>
+<ol><li>The IP address from which you access the website;</li><li>The type of browser and operating system you use to access our site;</li><li>The date and time you access our site;</li><li>The pages you visit; and</li><li>The addresses of pages from where you followed a link to our site.</li></ol>
+
+
+<p>Part of this information is gathered using a tracking cookie set by the Google Analytics service and handled by Google as described in their privacy policy. See your browser documentation for instructions on how to disable the cookie if you prefer not to share this data with Google.</p>
+
+<p>We use the gathered information to help us make our site more useful to visitors and to better understand how and when our site is used. We do not track or collect personally identifiable information or associate gathered data with any personally identifying information from other sources.</p>
+
+<p>By using this website, you consent to the collection of this data in the manner and for the purpose described above.</p>
\ No newline at end of file

Added: shiro/site/trunk/quickstart.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/quickstart.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/quickstart.html (added)
+++ shiro/site/trunk/quickstart.html Sat May 11 21:10:40 2013
@@ -0,0 +1,3 @@
+<p>This page has been moved.  You are being redirected.</p>
+
+<p></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>Redirection Notice</b><br clear="none">This page should redirect to <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a>.</td></tr></table></div>
\ No newline at end of file

Added: shiro/site/trunk/realm.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/realm.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/realm.html (added)
+++ shiro/site/trunk/realm.html Sat May 11 21:10:40 2013
@@ -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-Disa
 blingAuthentication">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>
+
+<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">A Realm is essentially a security-specific <a class="external-link" href="http://en.wikipedia.org/wiki/Data_Access_Object" rel="nofollow">DAO</a></td></tr></table></div>
+
+<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>
+
+<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>Not Preferred</b><br clear="none">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.</td></tr></table></div>
+
+<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>
+
+<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>Save Time</b><br clear="none">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.</td></tr></table></div>
+
+<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>
+
+<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>Realm Credentials Matching</b><br clear="none">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.</td></tr></table></div>
+
+<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

Added: shiro/site/trunk/reference.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/reference.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/reference.html (added)
+++ shiro/site/trunk/reference.html Sat May 11 21:10:40 2013
@@ -0,0 +1,52 @@
+<h1><a name="Reference-ApacheShiroReferenceDocumentation"></a>Apache Shiro Reference Documentation</h1>
+
+<p><b>I. Overview</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;1. <a href="introduction.html" title="Introduction">Introduction</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;2. <a href="tutorial.html" title="Tutorial">Tutorial</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;3. <a href="architecture.html" title="Architecture">Architecture</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;4. <a href="configuration.html" title="Configuration">Configuration</a></p>
+
+<p><b>II. Core</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;5. <a href="authentication.html" title="Authentication">Authentication</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;6. <a href="authorization.html" title="Authorization">Authorization</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;6.1. <a href="permissions.html" title="Permissions">Permissions</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;7. <a href="realm.html" title="Realm">Realms</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;8. <a href="session-management.html" title="Session Management">Session Management</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;9. <a href="cryptography.html" title="Cryptography">Cryptography</a></p>
+
+<p><b>III. Web Applications</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;10. <a href="web.html" title="Web">Web</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;10.1. <a href="web.html#Web-configuration">Configuration</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;10.2. <a href="web.html#Web-webini">[urls] (Path-based security)</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;10.3. <a href="web.html#Web-defaultfilters">Default Filters</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;10.4. <a href="web.html#Web-sessionManagement">Session Management</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;10.5. <a href="web.html#Web-taglibrary">JSP Tag Library</a></p>
+
+<p><b>IV. Auxiliary Support</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;11. <a href="caching.html" title="Caching">Caching</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;12. <a href="concurrency.html" title="Concurrency">Concurrency &amp; Multithreading</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;13. <a href="testing.html" title="Testing">Testing</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;14. <a href="subject.html" title="Subject">Custom Subjects</a></p>
+
+<p><b>V. Integration</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;15. <a href="spring.html" title="Spring">Spring Framework</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;16. <a href="guice.html" title="Guice">Guice</a><br clear="none">
+&#160;&#160;&#160;&#160;&#160;&#160;17. <a href="cas.html" title="CAS">CAS</a></p>
+
+<p><b>VI. Tools</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;18. <a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a></p>
+
+<p><b>VI. Index</b></p>
+
+<p>&#160;&#160;&#160;&#160;&#160;&#160;19. <a href="terminology.html" title="Terminology">Terminology</a></p>
+<h2><a name="Reference-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

Added: shiro/site/trunk/securitymanager.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/securitymanager.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/securitymanager.html (added)
+++ shiro/site/trunk/securitymanager.html Sat May 11 21:10:40 2013
@@ -0,0 +1,64 @@
+<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><a href="authenticator.html" title="Authenticator">Authenticator</a> (<tt>org.apache.shiro.authc.Authenticator</tt>)</li><li><a href="authorizer.html" title="Authorizer">Authorizer</a> (<tt>org.apache.shiro.authz.Authorizer</tt>)</li><li><a href="sessionmanager.html" title="SessionManager">SessionManager</a> (<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><a class="createlink" href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=SHIRO&amp;title=RememberMeManager&amp;linkCreation=true&amp;fromPageId=9373660">RememberMeManager</a> (<tt>org.apache.shiro.mgt.RememberMeManager</tt>)</li><li><a class="createlink" href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=SHIRO&amp;title=SubjectFactory&amp;linkCreation=true&amp;fromPageId=9373660">SubjectFactory</a> (<tt>org.apache.shiro.mgt.SubjectFact
 ory</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>

Added: shiro/site/trunk/session-management-features.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/session-management-features.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/session-management-features.html (added)
+++ shiro/site/trunk/session-management-features.html Sat May 11 21:10:40 2013
@@ -0,0 +1,48 @@
+<h1><a name="SessionManagementFeatures-ApacheShiroSessionManagementFeatures"></a>Apache Shiro Session Management Features</h1>
+
+<div class="addthis_toolbox addthis_default_style">
+<a class="addthis_button_compact" href="http://www.addthis.com/bookmark.php?v=250&amp;pubid=ra-4d66ef016022c3bd">Share</a>
+<span class="addthis_separator">|</span>
+<a class="addthis_button_preferred_1"></a>
+<a class="addthis_button_preferred_2"></a>
+<a class="addthis_button_preferred_3"></a>
+<a class="addthis_button_preferred_4"></a>
+</div>
+<script type="text/javascript">var addthis_config = {"data_track_clickback":true};</script>
+<script type="text/javascript" src="http://s7.addthis.com/js/250/addthis_widget.js#pubid=ra-4d66ef016022c3bd"></script>
+
+
+<p><br clear="none" class="atl-forced-newline">
+Sessions are buckets of data that your users carry with them for a period of time when using your application.  Sessions have traditionally been exclusive to web or EJB environments.  No more!  Shiro enables <b>sessions for any application environment</b>. Further, Shiro offers to a host of other great features to help you manage sessions. </p>
+
+<h2><a name="SessionManagementFeatures-Features"></a>Features</h2>
+
+<ul><li><b>POJO/J2SE based (IoC friendly)</b> - Everything in Shiro (including all aspects of Sessions and Session Management) is interface-based and implemented with POJOs.  This allows you to easily configure all session components with any JavaBeans-compatible configuration format, like JSON, YAML, Spring XML or similar mechanisms. You can also easily extend Shiro's components or write your own as necessary to fully customize session management functionality.</li></ul>
+
+
+<ul><li><b>Session Storage</b> - Because Shiro's Session objects are POJO-based, session data can be easily stored in any number of data sources.  This allows you to customize exactly where your application's session data resides - for example, the file system, an enterprise cache, a relational database, or proprietary data store.</li></ul>
+
+
+<ul><li><b>Easy and Powerful Clustering</b> - Shiro's sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache, Coherence, GigaSpaces, et. al.  This means you can configure session clustering for Shiro once and only once, and no matter what web container you deploy to, your sessions will be clustered the same way.  No need for container-specific configuration!</li></ul>
+
+
+<ul><li><b>Heterogeneous Client Access</b> - Unlike EJB or Web sessions, Shiro sessions can be 'shared' across various client technologies.  For example, a desktop application could 'see' and 'share' the same physical session used by the same user in a server-side web application.  We are unaware of any framework other than Shiro that can support this.</li></ul>
+
+
+<ul><li><b>Event listeners</b> - Event listeners allow you to listen to lifecycle events during a session's lifetime.  You can listen for these events and react to them for custom application behavior - for example, updating a user record when their session expires.</li></ul>
+
+
+<ul><li><b>Host address retention</b> &#8211; Shiro Sessions retain the IP address of the host from where the session was initiated.  This allows you to determine where the user is located and react accordingly (mostly useful in intranet environments where IP association is deterministic).</li></ul>
+
+
+<ul><li><b>Inactivity/expiration support</b> &#8211; Sessions expire due to inactivity as expected, but they can be prolonged via a <tt>touch()</tt> method to keep them 'alive' if desired.  This is useful in Rich Internet Application (RIA) environments where the user might be using a desktop application, but may not be regularly communicating with the server, but the server session should not expire.</li></ul>
+
+
+<ul><li><b>Transparent web use</b> - Shiro's web support implements the <tt>HttpSession</tt> interface and all of it's associated APIs.  This means you can use Shiro sessions in existing web applications and you don't need to change any of your existing web code.</li></ul>
+
+
+<ul><li><b>Can be used for SSO</b> - Because Shiro session's are POJO based, they are easily stored in any data source, and they can be 'shared' across applications if needed.  This can be used to provide a simple sign-on experience since the shared session can retain authentication state.</li></ul>
+
+
+<h2><a name="SessionManagementFeatures-GetStartedin10MinuteswithShiro"></a>Get Started in 10 Minutes with Shiro</h2>
+<p>Try out Shiro for yourself with our <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a>.  And if you have any questions about Shiro, please check out our <a href="forums.html" title="Forums">community forum</a> or <a href="mailing-lists.html" title="Mailing Lists">user mailing list</a> for answers from the community.</p>
\ No newline at end of file



Mime
View raw message