shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lhazlew...@apache.org
Subject svn commit: r1481417 [3/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/authentication.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/authentication.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/authentication.html (added)
+++ shiro/site/trunk/authentication.html Sat May 11 21:10:40 2013
@@ -0,0 +1,291 @@
+<h1><a name="Authentication-ApacheShiroAuthentication"></a>Apache Shiro
Authentication</h1>
+
+<div class="toc">
+<ul><li><a href="#Authentication-Authenticating%7B%7BSubjects%7D%7D">Authenticating
<tt>Subjects</tt></a></li><ul><li><a href="#Authentication-Step1%3ACollecttheSubject%27sprincipalsandcredentials">Step
1: Collect the Subject's principals and credentials</a></li><li><a href="#Authentication-Step2%3ASubmittheprincipalsandcredentials">Step
2: Submit the principals and credentials</a></li><li><a href="#Authentication-Step3%3AHandlingSuccessorFailure">Step
3: Handling Success or Failure</a></li></ul><li><a href="#Authentication-Rememberedvs.Authenticated">Remembered
vs. Authenticated</a></li><ul><li><a href="#Authentication-Whythedistinction%3F">Why
the distinction?</a></li><li><a href="#Authentication-Anillustratingexample">An
illustrating example</a></li></ul><li><a href="#Authentication-LoggingOut">Logging
Out</a></li><li><a href="#Authentication-AuthenticationSequence">Authentication
Sequence</a></li><ul><li><a href="#Authentication-%7B%7BAuthenticator%7D%7D">
<tt>Authentica
 tor</tt></a></li><li><a href="#Authentication-%7B%7BAuthenticationStrategy%7D%7D">
<tt>AuthenticationStrategy</tt></a></li><li><a href="#Authentication-RealmAuthenticationOrder">Realm
Authentication Order</a></li><ul><li><a href="#Authentication-ImplicitOrdering">Implicit
Ordering</a></li><li><a href="#Authentication-ExplicitOrdering">Explicit
Ordering</a></li></ul></ul><li><a href="#Authentication-RealmAuthentication">Realm
Authentication</a></li><li><a href="#Authentication-Lendahandwithdocumentation">Lend
a hand with documentation</a></li></ul></div>
+
+<p><span class="image-wrap" style="display: block; text-align: center"><img
src="assets/images/ShiroFeatures_Authentication.png" style="border: 0px solid black"></span></p>
+
+<p>Authentication is the process of identity verification - that is, proving a user
actually is who they say they are.  For a user to prove their identity, they need to provide
some identifying information as well as some sort of proof of that identity that your system
understands and trusts.  </p>
+
+<p>This is done by submitting a user's <em>principals</em> and <em>credentials</em>
to Shiro to see if they match what is expected by the application.</p>
+
+<ul><li><b>Principals</b> are a Subject's 'identifying attributes'.
 Principals can be anything that identifies a Subject, such as a first name (given name),
last name (surname or family name), a username, Social Security Number, etc.  Of course things
like family names are not very good at uniquely identifying a <tt>Subject</tt>,
so the best principals to use for authentication are unique for an application - typically
a username or email address.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<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>Primary
Principal</b><br clear="none">While Shiro can represent any number of principals,
Shiro expects an application to have exactly one 'Primary' principal - a single value that
uniquely identifies the <tt>Subject</tt> within the application. This is typically
a username, email address or globally unique user id in most applications.</td></tr></table></div>
+<p><br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p></li><li><b>Credentials</b>
are usually secret values known only by the <tt>Subject</tt> which are used as
supporting evidence that they in fact 'own' the claimed identity.  Some common examples of
credentials are passwords, biometric data such as fingerprints and retina scans, and X.509
certificates.</li></ul>
+
+
+<p>The most common example of a principal/credential pairing is that of a username
and password.  The username is the claimed identity, and the password is the proof matching
the claimed identity.  If a submitted password matches what is expected by the application,
the application can largely assume that the user really is who they say they are because no-one
else should know the same password.</p>
+
+<h2><a name="Authentication-Authenticating%7B%7BSubjects%7D%7D"></a>Authenticating
<tt>Subjects</tt></h2>
+
+<p>The process of authenticating a <tt>Subject</tt> can effectively broken
down into three distinct steps:</p>
+
+<ol><li>Collect the Subject's submitted principals and credentials</li><li>Submit
the principals and credentials for authentication.</li><li>If the submission is
successful, allow access, otherwise retry authentication or block access.</li></ol>
+
+
+<p>The following code demonstrates how Shiro's API reflects these steps:</p>
+
+<h3><a name="Authentication-Step1%3ACollecttheSubject%27sprincipalsandcredentials"></a>Step
1: Collect the Subject's principals and credentials</h3>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-comment">//Example using most common scenario of username/password
pair:
+</span>UsernamePasswordToken token = <span class="code-keyword">new</span>
UsernamePasswordToken(username, password);
+
+<span class="code-comment">//&#8221;Remember Me&#8221; built-in:
+</span>token.setRememberMe(<span class="code-keyword">true</span>);
+</pre>
+</div></div>
+
+<p>In this particular case, we&#8217;re using the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a>,
supporting the most common username/password authentication approach.  This is an implementation
of Shiro's <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html">org.apache.shiro.authc.AuthenticationToken</a>
interface, which is the base interface used by Shiro's authentication system to represent
submitted principals and credentials.  </p>
+
+<p>It is important to note here that Shiro does not care how you acquire this information:
perhaps the data was acquired by a user submitting an HTML form, or maybe it was retrieved
from an HTTP header, or perhaps it was read from a Swing or Flex GUI password form, or maybe
via command line arguments.  The process of collecting information from an application end-user
is completely decoupled from Shiro's <tt>AuthenticationToken</tt> concept.</p>
+
+<p>You may construct and represent <tt>AuthenticationToken</tt> instances
however you like - it is protocol agnostic.</p>
+
+<p>This example also shows that we have indicated that we wish Shiro to perform 'Remember
Me' services for the authentication attempt.  This ensures that Shiro remembers the user identity
if they return to the application at a later date.  We will cover <a class="createlink"
href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=SHIRO&amp;title=Remember+Me&amp;linkCreation=true&amp;fromPageId=25203054">Remember
Me</a> services in a later chapter.</p>
+
+<h3><a name="Authentication-Step2%3ASubmittheprincipalsandcredentials"></a>Step
2: Submit the principals and credentials</h3>
+
+<p>After the principals and credentials have been collected and represented as an <tt>AuthenticationToken</tt>
instance, we need to submit the token to Shiro to perform the actual authentication attempt:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+Subject currentUser = SecurityUtils.getSubject();
+
+currentUser.login(token);
+</pre>
+</div></div>
+
+<p>After acquiring the currently-executing <tt>Subject</tt>, we make a
single <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)">login</a></tt>
call, passing in the <tt>AuthenticationToken</tt> instance we created earlier.</p>
+
+<p>An invocation to the <tt>login</tt> method effectively represents an
authentication attempt.</p>
+
+<h3><a name="Authentication-Step3%3AHandlingSuccessorFailure"></a>Step
3: Handling Success or Failure</h3>
+
+<p>If the <tt>login</tt> method returns quietly, that's it - we're done!
 The <tt>Subject</tt> has been authenticated.  The application thread can continue
uninterrupted and all further calls to <tt>SecurityUtils.getSubject()</tt> will
return the authenticated <tt>Subject</tt> instance, and any calls to <tt>subject.</tt><tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()">isAuthenticated()</a></tt>
will return <tt>true</tt>.</p>
+
+<p>But what happens if the login attempt failed?  For example, what if the end-user
supplied an incorrect password, or accessed the system too many times and maybe their account
is locked?</p>
+
+<p>Shiro has a rich runtime <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/AuthorizationException.html">AuthenticationException</a></tt>
hierarchy that can indicate exactly why the attempt failed.  You can wrap <tt>login</tt>
in a <tt>try/catch</tt> block and catch any exception you wish and react to them
accordingly.  For example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">try</span> {
+    currentUser.login(token);
+} <span class="code-keyword">catch</span> ( UnknownAccountException uae ) { ...
+} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice
) { ...
+} <span class="code-keyword">catch</span> ( LockedAccountException lae ) { ...
+} <span class="code-keyword">catch</span> ( ExcessiveAttemptsException eae )
{ ...
+} ... <span class="code-keyword">catch</span> your own ...
+} <span class="code-keyword">catch</span> ( AuthenticationException ae ) {
+    <span class="code-comment">//unexpected error?
+</span>}
+
+<span class="code-comment">//No problems, <span class="code-keyword">continue</span>
on as expected...</span>
+</pre>
+</div></div>
+
+<p>If one of the existing exception classes do not meet your needs, custom <tt>AuthenticationExceptions</tt>
can be created to represent specific failure scenarios.</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>Login
Failure Tip</b><br clear="none">While your code can react to specific exceptions
and execute logic as necessary, a security best practice is to only show a generic failure
message to an end user in the event of a failure, for example, "Incorrect username or password.".
 This ensures no specific information is available to hackers that may be attempting an attack
vector.</td></tr></table></div>
+
+<h2><a name="Authentication-Rememberedvs.Authenticated"></a>Remembered
vs. Authenticated</h2>
+
+<p>As shown in the example above, Shiro supports the notion of "remember me" in addition
to the normal login process.  It is worth pointing out at this time that Shiro makes a very
precise distinction between a <em>remembered</em> Subject and an actual <em>authenticated</em>
Subject:  </p>
+
+<ul><li><b>Remembered</b>: A remembered <tt>Subject</tt>
is not anonymous and has a known identity (i.e. <tt>subject.</tt><tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#getPrincipals()">getPrincipals()</a></tt>
is non-empty).  But this identity is remembered from a previous authentication during a <b>previous</b>
session.  A subject is considered remembered if <tt>subject.</tt><tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isRemembered()">isRemembered()</a></tt>
returns <tt>true</tt>.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></li><li><b>Authenticated</b>:
An authenticated <tt>Subject</tt> is one that has been successfully authenticated
(i.e. the <tt>login</tt> method was invoked without throwing an exception) <em>during
the Subject's current session</em>.  A subject is considered authenticated if <tt>subject.</tt><tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()">isAuthenticated()</a></tt>
returns <tt>true</tt>.</li></ul>
+
+
+<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>Mutually
Exclusive</b><br clear="none">Remembered and authenticated states are mutually
exclusive - a <tt>true</tt> value for one indicates a <tt>false</tt>
value for the other and vice versa.</td></tr></table></div>
+
+<h3><a name="Authentication-Whythedistinction%3F"></a>Why the distinction?</h3>
+
+<p>The word 'authentication' has a very strong connotation of <em>proof</em>.
 That is, there is an expected <em>guarantee</em> that the <tt>Subject</tt>
has proven they are who they say they are.  </p>
+
+<p>When a user is only remembered from a previous interaction with the application,
the state of proof no longer exists: the remembered identity gives the system an idea who
that user probably is, but in reality, has no way of absolutely <em>guaranteeing</em>
if the remembered Subject represents the expected user. Once the subject is authenticated,
they are no longer considered only remembered because their identity would have been verified
during the current session.</p>
+
+<p>So although many parts of the application can still perform user-specific logic
based on the remembered principals, such as customized views, it should typically never perform
highly-sensitive operations until the user has legitimately verified their identity by executing
a successful authentication attempt.</p>
+
+<p>For example, a check to see if a <tt>Subject</tt> can access financial
information should almost always depend on <tt>isAuthenticated()</tt>, not <tt>isRemembered()</tt>,
to guarantee an expected and verified identity.</p>
+
+<h3><a name="Authentication-Anillustratingexample"></a>An illustrating
example</h3>
+
+<p>The following is a fairly common scenario that helps illustrate why the the distinction
between remembered and authenticated is important.</p>
+
+<p>Let's say you're using <a class="external-link" href="http://www.amazon.com"
rel="nofollow">Amazon.com</a>. You've logged-in successfully and have added a few
books to your shopping cart.  But you have to run off to a meeting, but forget to log out.
 By the time the meeting is over, it's time to go home and you leave the office.</p>
+
+<p>The next day when you come in to work, you realize you didn't complete your purchase,
so you go back to amazon.com.  This time, Amazon 'remembers' who you are, greets you by name,
and still gives you some personalized book recommendations.  To Amazon, <tt>subject.isRemembered()</tt>
would return <tt>true</tt>.</p>
+
+<p>But, what happens if you try to access your account to update your credit card information
to make your book purchase?  While Amazon 'remembers' you (<tt>isRemembered()</tt>
== <tt>true</tt>), it cannot guarantee that you are in fact you (for example,
maybe a co-worker is using your computer).</p>
+
+<p>So before you can perform a sensitive action like updating credit card information,
Amazon will force you to login so they can guarantee your identity.  After you login, your
identity has been verified and to Amazon, <tt>isAuthenticated()</tt> would now
be <tt>true</tt>.</p>
+
+<p>This scenario happens so frequently for many types of applications, so the functionality
is built in to Shiro so you can leverage it for your own application.  Now, whether you use
<tt>isRemembered()</tt> or <tt>isAuthenticated()</tt> to customize
your views and workflows is up to you, but Shiro will maintain this fundamental state in case
you need it.</p>
+
+<h2><a name="Authentication-LoggingOut"></a>Logging Out</h2>
+
+<p>The opposite of authenticating is releasing all known identifying state.  When the
<tt>Subject</tt> is done interacting with the application, you can call <tt>subject.</tt><tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#logout()">logout()</a></tt>
to relinquish all identifying information:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+currentUser.logout(); <span class="code-comment">//removes all identifying information
and invalidates their session too.</span>
+</pre>
+</div></div>
+
+<p>When you call <tt>logout</tt>, any existing <tt>Session</tt>
will be invalidated and any identity will be disassociated (e.g. in a web app, the RememberMe
cookie will also be deleted).</p>
+
+<p>After a <tt>Subject</tt> logs-out, the <tt>Subject</tt>
instance is considered anonymous again and, except for web applications, can be re-used for
<tt>login</tt> again if desired.</p>
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Web
Application Notice</b><br clear="none">Because remembered identity in web applications
is often persisted with cookies, and cookies can only be deleted before a Response body is
committed, it is highly recommended to redirect the end-user to a new view or page immediately
after calling <tt>subject.logout()</tt>.  This guarantees that any security-related
cookies are deleted as expected. This is a limitation of how HTTP cookies function and not
a limitation of Shiro.</td></tr></table></div>
+<p><a name="Authentication-sequence"></a></p>
+<h2><a name="Authentication-AuthenticationSequence"></a>Authentication
Sequence</h2>
+
+<p>Until now, we've only looked at how to authenticate a <tt>Subject</tt>
from within application code.  Now we'll cover what happens inside Shiro when an authentication
attempt occurs.</p>
+
+<p>We've taken our previous architecture diagram from the <a href="architecture.html"
title="Architecture">Architecture</a> chapter, and left only the components relevant
to authentication highlighted.  Each number represents a step during an authentication attempt:
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline"></p>
+
+<p><span class="image-wrap" style="display: block; text-align: center"><img
src="assets/images/ShiroAuthenticationSequence.png" style="border: 0px solid black"></span></p>
+
+<p><br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Step 1</b>: Application code invokes the <tt>Subject.login</tt>
method, passing in the constructed <tt>AuthenticationToken</tt> instance representing
the end-user's principals and credentials.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Step 2</b>: The <tt>Subject</tt> instance, typically a <tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/subject/support/DelegatingSubject.html">DelegatingSubject</a></tt>
(or a subclass) delegates to the application's <tt>SecurityManager</tt> by calling
<tt>securityManager.login(token)</tt>, where the actual authentication work begins.
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Step 3</b>: The <tt>SecurityManager</tt>, being a basic 'umbrella'
component, receives the token and simply delegates to its internal <tt><a class="external-link"
href="static/current/apidocs/org/apache/shiro/authc/Authenticator.html">Authenticator</a></tt>
instance by calling <tt>authenticator.</tt><tt><a class="external-link"
href="static/current/apidocs/org/apache/shiro/authc/Authenticator.html#authenticate(org.apache.shiro.authc.AuthenticationToken)">authenticate(token)</a></tt>.
 This is almost always a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html">ModularRealmAuthenticator</a></tt>
instance, which supports coordinating one or more <tt>Realm</tt> instances during
authentication.  The <tt>ModularRealmAuthenticator</tt> essentially provides a
<a class="external-link" href="http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules"
rel="nofollow">PAM</a>-style paradigm for Apache Shiro (where eac
 h <tt>Realm</tt> is a 'module' in PAM terminology).
+<br clear="none" class="atl-forced-newline">
+<br clear="none" class="atl-forced-newline">
+<b>Step 4</b>: If more than one <tt>Realm</tt> is configured for
the application, the <tt>ModularRealmAuthenticator</tt> instance will initiate
a multi-<tt>Realm</tt> authentication attempt utilizing its configured <tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html">AuthenticationStrategy</a></tt>.
 Before, during and after the <tt>Realms</tt> are invoked for authentication,
the <tt>AuthenticationStrategy</tt> will be called to allow it to react to each
Realm's results.  We will cover <tt>AuthenticationStrategies</tt> soon.</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>Single-Realm
Application</b><br clear="none">If only a single Realm is configured, it is called
directly - there is no need for an <tt>AuthenticationStrategy</tt> in a single-Realm
application.</td></tr></table></div> 
+<p><b>Step 5</b>: Each configured <tt>Realm</tt> is consulted
to see if it <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html#supports(org.apache.shiro.authc.AuthenticationToken)">supports</a></tt>
the submitted <tt>AuthenticationToken</tt>.  If so, the supporting Realm's <tt><a
class="external-link" href="static/current/apidocs/org/apache/shiro/realm/Realm.html#getAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken)">getAuthenticationInfo</a></tt>
method will be invoked with the submitted <tt>token</tt>.  The <tt>getAuthenticationInfo</tt>
method effectively represents a single authentication attempt for that particular <tt>Realm</tt>.
 We will cover the <tt>Realm</tt> authentication behavior shortly.</p>
+
+<h3><a name="Authentication-%7B%7BAuthenticator%7D%7D"></a><tt>Authenticator</tt></h3>
+
+<p>As mentioned earlier, the Shiro <tt>SecurityManager</tt> implementations
default to using a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html">ModularRealmAuthenticator</a></tt>
instance.  The <tt>ModularRealmAuthenticator</tt> equally supports applications
with single Realm as well as those with multiple realms.</p>
+
+<p>In a single-realm application, the <tt>ModularRealmAuthenticator</tt>
will invoke the single <tt>Realm</tt> directly.  If two or more Realms are configured,
it will use an <tt>AuthenticationStrategy</tt> instance to coordinate how the
attempt occurs.  We'll cover AuthenticationStrategies below.</p>
+
+<p>If you wish to configure the <tt>SecurityManager</tt> with a custom
<tt>Authenticator</tt> implementation, you can do so in <tt>shiro.ini</tt>
for example:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+[main]
+...
+authenticator = com.foo.bar.CustomAuthenticator
+
+securityManager.authenticator = $authenticator
+</pre>
+</div></div>
+
+<p>Although in practice, the <tt>ModularRealmAuthenticator</tt> is probably
suitable for most needs.</p>
+
+<h3><a name="Authentication-%7B%7BAuthenticationStrategy%7D%7D"></a><tt>AuthenticationStrategy</tt></h3>
+
+<p>When two or more realms are configured for an application, the <tt>ModularRealmAuthenticator</tt>
relies on an internal <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html">AuthenticationStrategy</a></tt>
component to determine the conditions for which an authentication attempt succeeds or fails.</p>
+
+<p>For example, if only one Realm authenticates an <tt>AuthenticationToken</tt>
successfully, but all others fail, is the authentication attempt considered successful?  Or
must all Realms authenticate successfully for the overall attempt to be considered successful?
 Or, if a Realm authenticates successfully, is it necessary to consult other Realms further?
 An <tt>AuthenticationStrategy</tt> makes the appropriate decision based on an
application's needs.</p>
+
+<p>An AuthenticationStrategy is a stateless component that is consulted 4 times during
an authentication attempt (any necessary state required for these 4 interactions will be given
as method arguments):</p>
+<ol><li>before any of the Realms are invoked</li><li>immediately
before an individual Realm's <tt>getAuthenticationInfo</tt> method is called</li><li>immediately
after an an individual Realm's <tt>getAuthenticationInfo</tt> method is called</li><li>after
all of the Realms have been invoked</li></ol>
+
+
+<p>Also an <tt>AuthenticationStrategy</tt> is responsible for aggregating
the results from each successful Realm and 'bundling' them into a single <tt><a class="external-link"
href="static/current/apidocs/org/apache/shiro/authc/AuthenticationInfo.html">AuthenticationInfo</a></tt>
representation.  This final aggregate <tt>AuthenticatinoInfo</tt> instance is
what is returned by the <tt>Authenticator</tt> instance and is what Shiro uses
to represent the <tt>Subject</tt>'s final identity (aka Principals).</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>Subject
Identity 'View'</b><br clear="none">If you use more than one Realm in your application
to acquire account data from multiple data sources, the <tt>AuthenticationStrategy</tt>
is ultimately responsible for the final 'merged' view of the Subject's identity that is seen
by the application.</td></tr></table></div>
+
+<p>Shiro has 3 concrete <tt>AuthenticationStrategy</tt> implementations:</p>
+
+<div class="table-wrap">
+<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><tt>AuthenticationStrategy</tt> class </th><th
colspan="1" rowspan="1" class="confluenceTh"> Description</th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"> <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/AtLeastOneSuccessfulStrategy.html">AtLeastOneSuccessfulStrategy</a></tt>
</td><td colspan="1" rowspan="1" class="confluenceTd"> If one (or more) Realms
authenticate successfully, the overall attempt is considered successful. If none authenticate
succesfully, the attempt fails. </td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"> <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/FirstSuccessfulStrategy.html">FirstSuccessfulStrategy</a></tt>
</td><td colspan="1" rowspan="1" class="confluenceTd"> Only the information returned
from the first successfully authenticated Realm will be used.  All fur
 ther Realms will be ignored. If none authenticate successfully, the attempt fails.</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"> <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/AllSuccessfulStrategy.html">AllSuccessfulStrategy</a></tt>
</td><td colspan="1" rowspan="1" class="confluenceTd"> All configured Realms must
authenticate successfully for the overall attempt to be considered successful.  If any one
does not authenticate successfully, the attempt fails. </td></tr></tbody></table>
+</div>
+
+
+<p>The <tt>ModularRealmAuthenticator</tt> defaults to the <b><tt>AtLeastOneSuccessfulStrategy</tt></b>
implementation, as this is the most commonly desired strategy.  However, you could configure
a different strategy if you wanted:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>shiro.ini</b></div><div class="codeContent
panelContent">
+<pre class="code-java">
+[main]
+...
+authcStrategy = org.apache.shiro.authc.pam.FirstSuccessfulStrategy
+
+securityManager.authenticator.authenticationStrategy = $authcStrategy
+
+...
+</pre>
+</div></div>
+
+<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Custom
AuthenticationStrategy</b><br clear="none">If you wanted to create your own <tt>AuthenticationStrategy</tt>
implementation yourself, you could use the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/pam/AbstractAuthenticationStrategy.html">org.apache.shiro.authc.pam.AbstractAuthenticationStrategy</a></tt>
as a starting point.  The <tt>AbstractAuthenticationStrategy</tt> class automatically
implements the 'bundling'/aggregation behavior of merging the results from each Realm into
a single <tt>AuthenticationInfo</tt> instance.</td></tr></table></div>
+
+<h3><a name="Authentication-RealmAuthenticationOrder"></a>Realm Authentication
Order</h3>
+
+<p>It is very important to point out that the <tt>ModularRealmAuthenticator</tt>
will interact with Realm instances in <em>iteration</em> order.</p>
+
+<p>The <tt>ModularRealmAuthenticator</tt> has access to the <tt>Realm</tt>
instances configured on the <tt>SecurityManager</tt>.  When performing an authentication
attempt, it will iterate over that collection, and for each <tt>Realm</tt> that
supports the submitted <tt>AuthenticationToken</tt>, invoke the Realm's <tt>getAuthenticationInfo</tt>
method.</p>
+
+<h4><a name="Authentication-ImplicitOrdering"></a>Implicit Ordering</h4>
+
+<p>When using Shiro's INI configuration format, you should configure Realms <em>in
the order you want them to process an <tt>AuthenticationToken</tt></em>.
 For example, in <tt>shiro.ini</tt>, Realms will be consulted in the order in
which they are defined in the INI file.  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
+
+</pre>
+</div></div>
+
+<p>The <tt>SecurityManager</tt> will be configured with those three realms,
and during an authentication attempt, <tt>blahRealm</tt>, <tt>fooRealm</tt>,
and <tt>barRealm</tt> will be invoked <em>in that order</em>.</p>
+
+<p>This has basically the same effect as if the following line were defined:</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>Using this approach, you don't need to set the <tt>securityManager's</tt>
<tt>realms</tt> property - every realm defined will automatically be added to
the <tt>realms</tt> property.</p>
+
+<h4><a name="Authentication-ExplicitOrdering"></a>Explicit Ordering</h4>
+
+<p>If you want to explicitly define the order in which the realms will be interacted
with, regardless of how they are defined, you can set the securityManager's <tt>realms</tt>
property as an explicit collection property.  For example, if using the definition above,
but you wanted the <tt>blahRealm</tt> to be consulted last instead of first:</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
+
+securityManager.realms = $fooRealm, $barRealm, $blahRealm
+...
+</pre>
+</div></div>
+
+<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>Explicit
Realm Inclusion</b><br clear="none">When you explicitly configure the <tt>securityManager.realms</tt>
property, <em>only</em> the referenced realms will be configured on the <tt>SecurityManager</tt>.
 This means you could define 5 realms in INI, but only actually use 3 if 3 are referenced
for the <tt>realms</tt> property.  This is different than implicit realm ordering
where all available realms will be used.</td></tr></table></div>
+
+<h2><a name="Authentication-RealmAuthentication"></a>Realm Authentication</h2>
+
+<p>This chapter covers Shiro's master workflow explaining how an authentication attempt
occurs.  The internal workflow of what happens in a single realm as it is consulted during
authentication (i.e. 'Step 5' above) is covered in the <a href="realm.html" title="Realm">Realm</a>
chapter's <a href="realm.html#Realm-authentication">Realm Authentication</a> section.</p>
+
+<h2><a name="Authentication-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/authenticator.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/authenticator.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/authenticator.html (added)
+++ shiro/site/trunk/authenticator.html Sat May 11 21:10:40 2013
@@ -0,0 +1,7 @@
+<p>TODO</p>
+
+<h2><a name="Authenticator-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/authorization-features.html
URL: http://svn.apache.org/viewvc/shiro/site/trunk/authorization-features.html?rev=1481417&view=auto
==============================================================================
--- shiro/site/trunk/authorization-features.html (added)
+++ shiro/site/trunk/authorization-features.html Sat May 11 21:10:40 2013
@@ -0,0 +1,44 @@
+<h1><a name="AuthorizationFeatures-ApacheShiroAuthorizationFeatures"></a>Apache
Shiro Authorization 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">
+Authorization, also called access control, is the process of determining access rights to
resources in an application.  In other words, determining "who has access to what."  Authorization
is used to answer security questions like, "is the user allowed to edit accounts", "is this
user allowed to view this web page", "does this user have access to this button?"  These are
all decisions determining what a user has access to and therefore all represent authorization
checks.</p>
+
+<p>Authorization is a critical element of any application but it can quickly become
very complex.  Shiro's goal is to eliminate much of the complexity around authorization so
that you can more easily build secure software. Below is a highlight of the Shiro authorization
features. </p>
+
+<h2><a name="AuthorizationFeatures-Features"></a>Features</h2>
+<ul><li><b>Subject-based</b> - Almost everything you do in Shiro
is based on the currently executing user, called a Subject.  And you can easily access the
subject retrieve the Subject and checks its roles, permissions, or other relevant attributes
anywhere in your code.  This makes it easier for you to understand and work with Shiro in
your applications.</li></ul>
+
+
+<ul><li><b>Checks based on roles or permissions</b> - Since the complexity
of authorization differs greatly between applications, Shiro is designed to be flexible, supporting
both role-based security and permission-based security based on your projects needs.</li></ul>
+
+
+<ul><li><b>Powerful and intuitive permission syntax</b> - As an option,
Shiro provides an out-of-the-box permission syntax, called Wildcard Permissions, that help
you model the fine grained access policies your application may have. By using Shiro's Wildcard
Permissions you get an easy-to-process and human readable syntax.  Moreoever, you don't have
to go through the time-consuming effort and complexity of creating your own method for representing
your access policies.</li></ul>
+
+
+<ul><li><b>Multiple enforcement options</b> &#8211; Authorization
checks in Shiro can be done through in-code checks, JDK 1.5 annotations, AOP, and JSP/GSP
Taglibs.  Shiro's goal is to give you the choice to use the option you think are best based
on your preferences and project needs.</li></ul>
+
+
+<ul><li><b>Strong caching support</b> - Any of the modern open-source
and/or enterprise caching products can be plugged in to Shiro to provide a fast and efficient
user-experience. For authorization, caching is crucial for performance in larger environments
or with more complex policies using back-end security data sources.</li></ul>
+
+
+<ul><li><b>Pluggable data sources</b> - Shiro uses pluggable data
access objects, referred to as Realms, to connect to security data sources where you keep
your access control information, like a LDAP or a relational database.  To help you avoid
building and maintaining integrations yourself, Shiro provides out-of-the-box realms for popular
data sources like LDAP, Active Directory, Kerboros, and JDBC.  If needed, you can also create
your own realms to support specific functionality not included in the basic realms.</li></ul>
+
+
+<ul><li><b>Supports any data model</b> - Shiro can support any data
model for access control-- it doesn't force a model on you. Your realm implementation ultimately
decides how your permissions and roles are grouped together and whether to return a "yes"
or a "no" answer to Shiro.  This feature allows you to architect your application in the manner
you chose and Shiro will bend to support you.</li></ul>
+
+
+<h2><a name="AuthorizationFeatures-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>



Mime
View raw message