Modified: shiro/site/publish/realm.html URL: http://svn.apache.org/viewvc/shiro/site/publish/realm.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/realm.html (original) +++ shiro/site/publish/realm.html Mon Oct 24 14:33:52 2016 @@ -79,14 +79,45 @@ <div id="content"> <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> - +<ul> + <li> + <p><a href="#Realm-RealmConfiguration">Realm Configuration</a></p> + <ul> + <li><a href="#Realm-ExplicitAssignment">Explicit Assignment</a></li> + <li><a href="#Realm-ImplicitAssignment">Implicit Assignment</a></li> + </ul> + </li> + <li> + <p><a href="#Realm-RealmAuthentication">Realm Authentication</a></p> + <ul> + <li><a href="#Realm-Supporting%7B%7BAuthenticationTokens%7D%7D">Supporting <code>AuthenticationTokens</code></a></li> + <li><a href="#Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D">Handling supported <code>AuthenticationTokens</code></a></li> + <li><a href="#Realm-CredentialsMatching">Credentials Matching</a> + <ul> + <li><a href="#Realm-SimpleEqualityCheck">Simple Equality Check</a></li> + <li><a href="#Realm-HashingCredentials">Hashing Credentials</a> + <ul> + <li> + <p><a href="#Realm-HashingandCorrespondingMatchers">Hashing and Corresponding Matchers</a></p> + <ul> + <li> + <p><a href="#Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"><code>SaltedAuthenticationInfo</code></a></p></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <p><a href="#Realm-DisablingAuthentication">Disabling Authentication</a></p></li> + </ul> + </li> + <li> + <p><a href="#Realm-RealmAuthorization">Realm Authorization</a></p></li> + <li><a href="#Realm-Lendahandwithdocumentation">Lend a hand with documentation</a></li> +</ul> +<p>A <code>Realm</code> is a component that can access application-specific security data such as users, roles, and permissions. The <code>Realm</code> 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 <code>Realm</code> 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"> @@ -100,39 +131,29 @@ <td colspan="1" rowspan="1"> <b>Tip</b> <br clear="none"> - A Realm is essentially a security-specific <a class="external-link" href="https://en.wikipedia.org/wiki/Data_Access_Object"; rel="nofollow">DAO</a> + 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> </tbody> </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>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 <code>Realm</code> can perform <em>both</em> authentication and authorization operations.</p> +<a name="Realm-RealmConfiguration"></a> +<h2><a href="#realm-configuration" name="realm-configuration">Realm Configuration</a></h2> +<p>If using Shiro’s INI configuration, you define and reference <code>Realms</code> like any other object in the <code>[main]</code> section, but they are configured on the <code>securityManager</code> in one of two ways: explicitly or implicitly.</p> +<a name="Realm-ExplicitAssignment"></a> +<h3><a href="#explicit-assignment" name="explicit-assignment">Explicit Assignment</a></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 <code>securityManager</code> 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 +<pre><code class="ini">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> - +</code></pre> +<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> +<a name="Realm-ImplicitAssignment"></a> +<h3><a href="#implicit-assignment" name="implicit-assignment">Implicit Assignment</a></h3> <div class="panelMacro"> <table class="warningMacro"> <colgroup span="1"> @@ -154,56 +175,40 @@ securityManager.realms = $fooRealm, $bar </tbody> </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 +<p>If for some reason you don’t want to explicitly configure the <code>securityManager.realms</code> property, you can allow Shiro to detect all configured realms and assign them to the <code>securityManager</code> directly.</p> +<p>Using this approach, realms are assigned to the <code>securityManager</code> instance in the <em>order that they are defined</em>.</p> +<p>That is, for the following <code>shiro.ini</code> example:</p> +<pre><code class="ini">blahRealm = com.company.blah.Realm fooRealm = com.company.foo.Realm barRealm = com.company.another.Realm # no securityManager.realms assignment here -</pre> -</div></div> - +</code></pre> <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> - +<pre><code class="java">securityManager.realms = $blahRealm, $fooRealm, $barRealm +</code></pre> +<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 <code>Authenticator</code>’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.</p> +<a name="Realm-authentication"></a> +<a name="Realm-RealmAuthentication"></a> +<h2><a href="#realm-authentication" name="realm-authentication">Realm Authentication</a></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 <code>Authenticator</code> interacts with a <code>Realm</code> during an authentication attempt.</p> +<a name="Realm-Supporting%7B%7BAuthenticationTokens%7D%7D"></a> +<h3>Supporting <code>AuthenticationTokens</code></h3> +<p>As mentioned in the <a href="authentication.html#Authentication-sequence">authentication sequence</a>, just before a <code>Realm</code> is consulted to perform an authentication attempt, its <a href="static/current/apidocs/org/apache/shiro/realm/Realm.html#supports-org.apache.shiro.authc.AuthenticationToken-"><code>supports</code></a> method is called. If the return value is <code>true</code>, only then will its <code>getAuthenticationInfo(token)</code> 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 <code>UsernamePasswordTokens</code> at all, in which case it would return <code>false</code> from the <code>supports</code> method.</p> +<a name="Realm-Handlingsupported%7B%7BAuthenticationTokens%7D%7D"></a> +<h3>Handling supported <code>AuthenticationTokens</code></h3> +<p>If a <code>Realm</code> <code>supports</code> a submitted <code>AuthenticationToken</code>, the <code>Authenticator</code> will call the Realm’s <a 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 <code>Realm's</code> backing data source. The method, in order:</p> +<ol> + <li>Inspects the <code>token</code> for the identifying principal (account identifying information)</li> + <li>Based on the <code>principal</code>, looks up corresponding account data in the data source</li> + <li>Ensures that the token’s supplied <code>credentials</code> matches those stored in the data store</li> + <li>If the credentials match, an <a 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 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 <code>getAuthenticationInfo</code> 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 <code>AuthenticationInfo</code> instance is returned that represents Subject account information from that data source.</p> <div class="panelMacro"> <table class="infoMacro"> <colgroup span="1"> @@ -221,17 +226,15 @@ securityManager.realms = $blahRealm, $fo <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. + Implementing `<a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html">Realm</a>` 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> </tbody> </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> - +<a name="Realm-CredentialsMatching"></a> +<h3><a href="#credentials-matching" name="credentials-matching">Credentials Matching</a></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"> @@ -247,135 +250,97 @@ securityManager.realms = $blahRealm, $fo <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. + It is each Realm's responsibility to match submitted credentials with those stored in the Realm's backing data store, and not the `Authenticator's` responsibility. Each `Realm` has intimate knowledge of credentials format and storage and can perform detailed credentials matching, whereas the `Authenticator` is a generic workflow component. </td> </tr> </tbody> </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(); +<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 href="static/current/apidocs/org/apache/shiro/realm/AuthenticatingRealm.html">AuthenticatingRealm</a> and its subclasses support the concept of a <a 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 <code>AuthenticationToken</code> are presented to a <code>CredentialsMatcher</code> to see if what was submitted matches what is stored in the data store.</p> +<p>Shiro has some <code>CredentialsMatcher</code> implementations to get you started out of the box, such as the <a href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a> and <a 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> +<pre><code class="java">Realm myRealm = new com.company.shiro.realm.MyRealm(); +CredentialsMatcher customMatcher = new 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] +</code></pre> +<p>Or, if using Shiro’s INI <a href="configuration.html" title="Configuration">configuration</a>:</p> +<pre><code class="ini">[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> - +</code></pre> +<a name="Realm-SimpleEqualityCheck"></a> +<h4><a href="#simple-equality-check" name="simple-equality-check">Simple Equality Check</a></h4> +<p>All of Shiro’s out-of-the-box <code>Realm</code> implementations default to using a <a href="static/current/apidocs/org/apache/shiro/authc/credential/SimpleCredentialsMatcher.html">SimpleCredentialsMatcher</a>. The <code>SimpleCredentialsMatcher</code> performs a plain direct equality check of the stored account credentials with what was submitted in the <code>AuthenticationToken</code>.</p> +<p>For example, if a <a href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a> was submitted, the <code>SimpleCredentialsMatcher</code> verifies that the password submitted is exactly equal to the password stored in the database.</p> +<p>The <code>SimpleCredentialsMatcher</code> 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> +<a name="Realm-HashingCredentials"></a> +<h4><a href="#hashing-credentials" name="hashing-credentials">Hashing Credentials</a></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 href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher</a> implementations to be configured on realms instead of the aforementioned <code>SimpleCredentialsMatcher</code>.</p> +<p>Hashing credentials and the benefits of salting and multiple hash iterations are outside the scope of this <code>Realm</code> documentation, but definitely read the <a href="static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html">HashedCredentialsMatcher JavaDoc</a> which covers these principles in detail.</p> +<a name="Realm-HashingandCorrespondingMatchers"></a> +<h5><a href="#hashing-and-corresponding-matchers" name="hashing-and-corresponding-matchers">Hashing and Corresponding Matchers</a></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="https://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; +<p>Shiro provides multiple <code>HashedCredentialsMatcher</code> 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 href="https://en.wikipedia.org/wiki/SHA_hash_functions";>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> +<pre><code class="java">import org.apache.shiro.crypto.hash.Sha256Hash; +import org.apache.shiro.crypto.RandomNumberGenerator; +import 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); +//We'll use a Random Number Generator to generate salts. This +//is much more secure than using a username as a salt or not +//having a salt at all. Shiro makes this easy. +// +//Note that a normal app would reference an attribute rather +//than create a new RNG every time: +RandomNumberGenerator rng = new SecureRandomNumberGenerator(); +Object salt = rng.nextBytes(); + +//Now hash the plain-text password with the random salt and multiple +//iterations and then Base64-encode the value (requires less space than Hex): +String hashedPasswordBase64 = new Sha256Hash(plainTextPassword, salt, 1024).toBase64(); + +User user = new User(username, hashedPasswordBase64); +//save the salt with the new account. The HashedCredentialsMatcher +//will need it later when handling login attempts: +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] +</code></pre> +<p>Since you’re <code>SHA-256</code> hashing your user’s passwords, you need to tell Shiro to use the appropriate <code>HashedCredentialsMatcher</code> to match your hashing preferences. In this example, we create a random salt and perform 1024 hash iterations for strong security (see the <code>HashedCredentialsMatcher</code> JavaDoc for why). Here is the Shiro INI configuration to make this work:</p> +<pre><code class="ini">[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> +# base64 encoding, not hex in this example: +credentialsMatcher.storedCredentialsHexEncoded = false 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> +# This next property is only needed in Shiro 1.0\. Remove it in 1.1 and later: +credentialsMatcher.hashSalted = true ... 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> +</code></pre> +<a name="Realm-%7B%7BSaltedAuthenticationInfo%7D%7D"></a> +<h6><a href="#saltedauthenticationinfo" name="saltedauthenticationinfo">SaltedAuthenticationInfo</a></h6> +<p>The last thing to do to ensure this works is that your <code>Realm</code> implementation must return a <a href="static/current/apidocs/org/apache/shiro/authc/SaltedAuthenticationInfo.html">SaltedAuthenticationInfo</a> instance instead of a normal <code>AuthenticationInfo</code> one. The <code>SaltedAuthenticationInfo</code> interface ensures that the salt that you used when you created the user account (e.g. the <code>user.setPasswordSalt(salt);</code> call above) can be referenced by the <code>HashedCredentialsMatcher</code>.</p> +<p>The <code>HashedCredentialsMatcher</code> needs the salt in order to perform the same hashing technique on the submitted <code>AuthenticationToken</code> 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 <code>Realm</code> implementation represents that by returning <code>SaltedAuthenticationInfo</code> instances.</p> +<a name="Realm-DisablingAuthentication"></a> +<h3><a href="#disabling-authentication" name="disabling-authentication">Disabling Authentication</a></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 <code>false</code> from the Realm’s <code>supports</code> method. Then your realm will never be consulted during an authentication attempt.</p> +<p>Of course at least one configured <code>Realm</code> needs to be able to support AuthenticationTokens if you want to authenticate Subjects.</p> +<a name="Realm-RealmAuthorization"></a> +<h2><a href="#realm-authorization" name="realm-authorization">Realm Authorization</a></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> +<a name="Realm-Lendahandwithdocumentation"></a> +<h2><a href="#lend-a-hand-with-documentation" name="lend-a-hand-with-documentation">Lend a hand with documentation</a></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 href="http://shiro-user.582556.n2.nabble.com/";>User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> </div>
Modified: shiro/site/publish/reference.html URL: http://svn.apache.org/viewvc/shiro/site/publish/reference.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/reference.html (original) +++ shiro/site/publish/reference.html Mon Oct 24 14:33:52 2016 @@ -78,58 +78,82 @@ <div id="content"> - <h1><a name="Reference-ApacheShiroReferenceDocumentation"></a>Apache Shiro Reference Documentation</h1> - -<p><b>I. Overview</b></p> - -<p>      1. <a href="introduction.html" title="Introduction">Introduction</a><br clear="none"> -      2. <a href="tutorial.html" title="Tutorial">Tutorial</a><br clear="none"> -      3. <a href="architecture.html" title="Architecture">Architecture</a><br clear="none"> -      4. <a href="configuration.html" title="Configuration">Configuration</a></p> - -<p><b>II. Core</b></p> - -<p>      5. <a href="authentication.html" title="Authentication">Authentication</a><br clear="none"> -      6. <a href="authorization.html" title="Authorization">Authorization</a><br clear="none"> -            6.1. <a href="permissions.html" title="Permissions">Permissions</a><br clear="none"> -      7. <a href="realm.html" title="Realm">Realms</a><br clear="none"> -      8. <a href="session-management.html" title="Session Management">Session Management</a><br clear="none"> -      9. <a href="cryptography.html" title="Cryptography">Cryptography</a></p> - -<p><b>III. Web Applications</b></p> - -<p>      10. <a href="web.html" title="Web">Web</a><br clear="none"> -            10.1. <a href="web.html#Web-configuration">Configuration</a><br clear="none"> -            10.2. <a href="web.html#Web-webini">[urls] (Path-based security)</a><br clear="none"> -            10.3. <a href="web.html#Web-defaultfilters">Default Filters</a><br clear="none"> -            10.4. <a href="web.html#Web-sessionManagement">Session Management</a><br clear="none"> -            10.5. <a href="web.html#Web-taglibrary">JSP Tag Library</a></p> - -<p><b>IV. Auxiliary Support</b></p> - -<p>      11. <a href="caching.html" title="Caching">Caching</a><br clear="none"> -      12. <a href="concurrency.html" title="Concurrency">Concurrency & Multithreading</a><br clear="none"> -      13. <a href="testing.html" title="Testing">Testing</a><br clear="none"> -      14. <a href="subject.html" title="Subject">Custom Subjects</a></p> - -<p><b>V. Integration</b></p> - -<p>      15. <a href="spring.html" title="Spring">Spring Framework</a><br clear="none"> -      16. <a href="guice.html" title="Guice">Guice</a><br clear="none"> -      17. <a href="cas.html" title="CAS">CAS</a></p> - -<p><b>VI. Tools</b></p> - -<p>      18. <a href="command-line-hasher.html" title="Command Line Hasher">Command Line Hasher</a></p> - -<p><b>VI. Index</b></p> - -<p>      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> + <a name="Reference-ApacheShiroReferenceDocumentation"></a> +<h1><a href="#apache-shiro-reference-documentation" name="apache-shiro-reference-documentation">Apache Shiro Reference Documentation</a></h1> +<ol> + <li> + <p>Overview</p> + <ul> + <li><a href="introduction.html">Introduction</a></li> + <li><a href="tutorial.html">Tutorial</a></li> + <li><a href="architecture.html">Architecture</a></li> + <li><a href="configuration.html">Configuration</a></li> + </ul> + </li> + <li> + <p>Core</p> + <ul> + <li><a href="authentication.html">Authentication</a></li> + <li><a href="authorization.html">Authorization</a> + <ul> + <li><a href="permissions.html">Permissions</a></li> + </ul> + </li> + <li><a href="realm.html">Realms</a></li> + <li><a href="session-management.html">Session Management</a></li> + <li><a href="cryptography.html">Cryptography</a></li> + </ul> + </li> + <li> + <p>Web Applications</p> + <ul> + <li> + <p><a href="web.html">Web</a></p> + <ul> + <li><a href="web.html#Web-configuration">Configuration</a></li> + <li><a href="web.html#Web-webini">[urls] (Path-based security)</a></li> + <li><a href="web.html#Web-defaultfilters">Default Filters</a></li> + <li><a href="web.html#Web-sessionManagement">Session Management</a></li> + <li><a href="web.html#Web-taglibrary">JSP Tag Library</a></li> + </ul> + </li> + </ul> + </li> + <li> + <p>Auxiliary Support</p> + <ul> + <li><a href="caching.html">Caching</a></li> + <li><a href="concurrency.html">Concurrency & Multithreading</a></li> + <li><a href="testing.html">Testing</a></li> + <li><a href="subject.html">Custom Subjects</a></li> + </ul> + </li> + <li> + <p>Integration</p> + <ul> + <li><a href="spring.html">Spring Framework</a></li> + <li><a href="guice.html">Guice</a></li> + <li><a href="cas.html">CAS</a></li> + </ul> + </li> + <li> + <p>Tools</p> + <ul> + <li> + <p><a href="command-line-hasher.html">Command Line Hasher</a></p></li> + </ul> + </li> + <li> + <p>Index</p> + <ul> + <li> + <p><a href="terminology.html">Terminology</a></p></li> + </ul> + </li> +</ol> +<h2><a href="#lend-a-hand-with-documentation" name="lend-a-hand-with-documentation">Lend a hand with documentation</a></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 href="http://shiro-user.582556.n2.nabble.com/";>User Forum</a> or the <a href="mailing-lists.html">User Mailing List</a>.</p> </div> Modified: shiro/site/publish/securitymanager.html URL: http://svn.apache.org/viewvc/shiro/site/publish/securitymanager.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/securitymanager.html (original) +++ shiro/site/publish/securitymanager.html Mon Oct 24 14:33:52 2016 @@ -78,48 +78,39 @@ <div id="content"> - <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> - + <a name="SecurityManager-UnderstandingtheSecurityManagerinApacheShiro"></a> +<h1><a href="#understanding-the-securitymanager-in-apache-shiro" name="understanding-the-securitymanager-in-apache-shiro">Understanding the SecurityManager in Apache Shiro</a></h1> +<p>The <a 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 <code>SecurityManager</code> performs security operations and manages state for <em>all</em> application users.</p> +<p>Because Shiro’s API encourages a <code>Subject</code>-centric programming approach, most application developers will rarely, if ever, interact with the <code>SecurityManager</code> directly (framework developers however might sometimes find it useful). Even so, it is still important to know how the <code>SecurityManager</code> functions, especially when configuring one for an application.</p> +<a name="SecurityManager-Design"></a> +<h2><a href="#design" name="design">Design</a></h2> +<p>As stated previously, the application’s <code>SecurityManager</code> performs security operations and manages state for <em>all</em> application users. In Shiro’s default <code>SecurityManager</code> 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> - + <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/>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 <code>SecurityManager</code> implementations mostly act as a lightweight ‘container’ component, delegating almost all behavior to nested/wrapped components.</p> +<a name="SecurityManager-Modularity"></a> +<h3><a href="#modularity" name="modularity">Modularity</a></h3> +<p>To simplify the <code>SecurityManager</code> implementation complexity and allow for pluggable behavior, the Shiro <code>SecurityManager</code> 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 <code>SecurityManager</code> implementation knows how and when to coordinate the components for the correct behavior.</p> +<p>The nested components that the <code>SecurityManager</code> 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> - + <li>Authenticator (<code>org.apache.shiro.authc.Authenticator</code>)</li> + <li>Authorizer (<code>org.apache.shiro.authz.Authorizer</code>)</li> + <li>SessionManager (<code>org.apache.shiro.session.mgt.SessionManager</code>)</li> + <li><a href="cachemanager.html" title="CacheManager">CacheManager</a> (<code>org.apache.shiro.cache.CacheManager</code>)</li> + <li>RememberMeManager (<code>org.apache.shiro.mgt.RememberMeManager</code>)</li> + <li>SubjectFactory(<code>org.apache.shiro.mgt.SubjectFactory</code>)</li> +</ul> +<p>The <code>SecurityManager</code> 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"> @@ -133,47 +124,36 @@ <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. + Because of JavaBeans compatibility, it is very easy to configure the <code>SecurityManager</code> 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> </tbody> </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> - +<a name="SecurityManager-ProgrammaticConfiguration"></a> +<h3><a href="#programmatic-configuration" name="programmatic-configuration">Programmatic Configuration</a></h3> +<p>The absolute simplest way to create a SecurityManager and make it available to the application is to create a <code>org.apache.shiro.mgt.DefaultSecurityManager</code> and wire it up in code:</p> +<pre><code class="java">Realm realm = //instantiate or acquire a Realm instance. We'll discuss Realms later. +SecurityManager securityManager = new DefaultSecurityManager(realm); +//Make the SecurityManager instance available to the entire application: +SecurityUtils.setSecurityManager(securityManager); +</code></pre> +<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 <code>SecurityManager</code> 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 <code>SecurityUtils.setSecurityManager</code> method call makes the instantiated <code>SecurityManager</code> 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> +<a name="SecurityManager-TextConfiguration"></a> +<h3><a href="#text-configuration" name="text-configuration">Text Configuration</a></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> +<a name="SecurityManager-Lendahandwithdocumentation"></a> +<h2><a href="#lend-a-hand-with-documentation" name="lend-a-hand-with-documentation">Lend a hand with documentation</a></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 href="http://shiro-user.582556.n2.nabble.com/";>User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p> </div> Modified: shiro/site/publish/session-management-features.html URL: http://svn.apache.org/viewvc/shiro/site/publish/session-management-features.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/session-management-features.html (original) +++ shiro/site/publish/session-management-features.html Mon Oct 24 14:33:52 2016 @@ -78,8 +78,8 @@ <div id="content"> - <h1><a name="SessionManagementFeatures-ApacheShiroSessionManagementFeatures"></a>Apache Shiro Session Management Features</h1> - + <a name="SessionManagementFeatures-ApacheShiroSessionManagementFeatures"></a> +<h1><a href="#apache-shiro-session-management-features" name="apache-shiro-session-management-features">Apache Shiro Session Management Features</a></h1> <div class="addthis_toolbox addthis_default_style"> <a class="addthis_button_compact" href="http://www.addthis.com/bookmark.php?v=250&pubid=ra-4d66ef016022c3bd";>Share</a> <span class="addthis_separator">|</span> @@ -90,42 +90,32 @@ </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> – 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> – 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> +<p>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> +<a name="SessionManagementFeatures-Features"></a> +<h2><a href="#features" name="features">Features</a></h2> +<ul> + <li> + <p><strong>POJO/J2SE based (IoC friendly)</strong> - 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.</p></li> + <li> + <p><strong>Session Storage</strong> - 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.</p></li> + <li> + <p><strong>Easy and Powerful Clustering</strong> - 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!</p></li> + <li> + <p><strong>Heterogeneous Client Access</strong> - 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.</p></li> + <li> + <p><strong>Event listeners</strong> - 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.</p></li> + <li> + <p><strong>Host address retention</strong> – 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).</p></li> + <li> + <p><strong>Inactivity/expiration support</strong> – Sessions expire due to inactivity as expected, but they can be prolonged via a <code>touch()</code> 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.</p></li> + <li> + <p><strong>Transparent web use</strong> - Shiro’s web support implements the <code>HttpSession</code> 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.</p></li> + <li> + <p><strong>Can be used for SSO</strong> - 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.</p></li> +</ul> +<a name="SessionManagementFeatures-GetStartedin10MinuteswithShiro"></a> +<h2><a href="#get-started-in-10-minutes-with-shiro" name="get-started-in-10-minutes-with-shiro">Get Started in 10 Minutes with Shiro</a></h2> +<p>Try out Shiro for yourself with our <a href="10-minute-tutorial.html">10 Minute Tutorial</a>. And if you have any questions about Shiro, please check out our <a href="forums.html">community forum</a> or <a href="mailing-lists.html">user mailing list</a> for answers from the community.</p> </div>
