bmarwell commented on a change in pull request #131:
URL: https://github.com/apache/shiro-site/pull/131#discussion_r749738217
##########
File path: jbake/content/authentication.adoc
##########
@@ -0,0 +1,389 @@
+[#Authentication-Authentication]
+= Apache Shiro Authentication
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation
+:idprefix:
+:icons: font
+:toc:
+
+image::/img/ShiroFeatures_Authentication.png[Shiro features authentication
graphic, align="center"]
+
+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.
+
+This is done by submitting a user's _principals_ and _credentials_ to Shiro to
see if they match what is expected by the application.
+
+* *Principals* 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
`Subject`, so the best principals to use for authentication are unique for an
application - typically a username or email address.
+
+[NOTE]
+====
+.Primary Principal
+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 `Subject` within the application.
+This is typically a username, email address or globally unique user id in most
applications.
+====
+
+* *Credentials* are usually secret values known only by the `Subject` 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.
+
+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.
+
+
+== Authenticating Subjects
+
+The process of authenticating a `Subject` can effectively broken down into
three distinct steps:
+
+. Collect the Subject's submitted principals and credentials
+. Submit the principals and credentials for authentication.
+. If the submission is successful, allow access, otherwise retry
authentication or block access.
+
+The following code demonstrates how Shiro's API reflects these steps:
+
+[#Authentication-AuthenticatingSubject-Step1]
+=== Step 1: Collect the Subject's principals and credentials
+
+[source,java]
+----
+//Example using most common scenario of username/password pair:
+UsernamePasswordToken token = new UsernamePasswordToken(username, password);
+
+//"Remember Me" built-in:
+token.setRememberMe(true);
+
+----
+
+In this particular case, we’re using the
link:/static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html[UsernamePasswordToken],
supporting the most common username/password authentication approach.
+This is an implementation of Shiro's
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html[org.apache.shiro.authc.AuthenticationToken]
interface, which is the base interface used by Shiro's authentication system
to represent submitted principals and credentials.
+
+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 `AuthenticationToken` concept.
+
+You may construct and represent `AuthenticationToken` instances however you
like - it is protocol agnostic.
+
+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 Remember Me services in a later chapter.
+
+[#Authentication-AuthenticatingSubject-Step2]
+=== Step 2: Submit the principals and credentials
+
+After the principals and credentials have been collected and represented as an
`AuthenticationToken` instance, we need to submit the token to Shiro to perform
the actual authentication attempt:
+
+[source,java]
+----
+Subject currentUser = SecurityUtils.getSubject();
+
+currentUser.login(token);
+----
+
+After acquiring the currently-executing `Subject`, we make a single
`link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)[login]`
call, passing in the `AuthenticationToken` instance we created earlier.
+
+An invocation to the `login` method effectively represents an authentication
attempt.
+
+[#Authentication-AuthenticatingSubject-Step3]
+=== Step 3: Handling Success or Failure
+
+If the `login` method returns quietly, that's it - we're done!
+The `Subject` has been authenticated.
+The application thread can continue uninterrupted and all further calls to
`SecurityUtils.getSubject()` will return the authenticated `Subject` instance,
and any calls to
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
will return `true`.
+
+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?
+
+Shiro has a rich runtime
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthenticationException`]
hierarchy that can indicate exactly why the attempt failed.
+You can wrap `login` in a `try/catch` block and catch any exception you wish
and react to them accordingly.
+For example:
+
+[source,java]
+----
+try {
+ currentUser.login(token);
+} catch ( UnknownAccountException uae ) { ...
+} catch ( IncorrectCredentialsException ice ) { ...
+} catch ( LockedAccountException lae ) { ...
+} catch ( ExcessiveAttemptsException eae ) { ...
+} ... catch your own ...
+} catch ( AuthenticationException ae ) {
+ //unexpected error?
+}
+
+//No problems, continue on as expected...
+----
+
+If one of the existing exception classes do not meet your needs, custom
`AuthenticationExceptions` can be created to represent specific failure
scenarios.
+
+[TIP]
+====
+.Login Failure Tip
+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.
+====
+
+[#Authentication-RememberedVsAuthenticated]
+== Remembered vs. Authenticated
+
+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 _remembered_ Subject and an actual _authenticated_
Subject:
+
+* *Remembered*: A remembered `Subject` is not anonymous and has a known
identity (i.e.
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#getPrincipals()[getPrincipals()]`
is non-empty).
+But this identity is remembered from a previous authentication during a
*previous* session.
+A subject is considered remembered if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isRemembered()[isRemembered()]`
returns `true`.
+
+* *Authenticated*: An authenticated `Subject` is one that has been
successfully authenticated (i.e. the `login` method was invoked without
throwing an exception) _during the Subject's current session_.
+A subject is considered authenticated if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
returns `true`.
+
+[WARNING]
+====
+.Mutually Exclusive
+Remembered and authenticated states are mutually exclusive - a `true` value
for one indicates a `false` value for the other and vice versa.
+====
Review comment:
According to
https://asciidoctor.org/docs/asciidoc-writers-guide/#admonitions, I might argue
that `CAUTION` would be the better choice (now that we have it available):
* Use CAUTION to advise the reader to act carefully (i.e., exercise care).
* Use WARNING to inform the reader of danger, harm, or consequences that
exist.
##########
File path: jbake/content/authentication.adoc
##########
@@ -0,0 +1,389 @@
+[#Authentication-Authentication]
+= Apache Shiro Authentication
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation
+:idprefix:
+:icons: font
+:toc:
+
+image::/img/ShiroFeatures_Authentication.png[Shiro features authentication
graphic, align="center"]
+
+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.
+
+This is done by submitting a user's _principals_ and _credentials_ to Shiro to
see if they match what is expected by the application.
+
+* *Principals* 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
`Subject`, so the best principals to use for authentication are unique for an
application - typically a username or email address.
+
+[NOTE]
+====
+.Primary Principal
+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 `Subject` within the application.
+This is typically a username, email address or globally unique user id in most
applications.
+====
+
+* *Credentials* are usually secret values known only by the `Subject` 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.
+
+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.
+
+
+== Authenticating Subjects
+
+The process of authenticating a `Subject` can effectively broken down into
three distinct steps:
+
+. Collect the Subject's submitted principals and credentials
+. Submit the principals and credentials for authentication.
+. If the submission is successful, allow access, otherwise retry
authentication or block access.
+
+The following code demonstrates how Shiro's API reflects these steps:
+
+[#Authentication-AuthenticatingSubject-Step1]
+=== Step 1: Collect the Subject's principals and credentials
+
+[source,java]
+----
+//Example using most common scenario of username/password pair:
+UsernamePasswordToken token = new UsernamePasswordToken(username, password);
+
+//"Remember Me" built-in:
+token.setRememberMe(true);
+
+----
+
+In this particular case, we’re using the
link:/static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html[UsernamePasswordToken],
supporting the most common username/password authentication approach.
+This is an implementation of Shiro's
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html[org.apache.shiro.authc.AuthenticationToken]
interface, which is the base interface used by Shiro's authentication system
to represent submitted principals and credentials.
+
+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 `AuthenticationToken` concept.
+
+You may construct and represent `AuthenticationToken` instances however you
like - it is protocol agnostic.
+
+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 Remember Me services in a later chapter.
+
+[#Authentication-AuthenticatingSubject-Step2]
+=== Step 2: Submit the principals and credentials
+
+After the principals and credentials have been collected and represented as an
`AuthenticationToken` instance, we need to submit the token to Shiro to perform
the actual authentication attempt:
+
+[source,java]
+----
+Subject currentUser = SecurityUtils.getSubject();
+
+currentUser.login(token);
+----
+
+After acquiring the currently-executing `Subject`, we make a single
`link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)[login]`
call, passing in the `AuthenticationToken` instance we created earlier.
+
+An invocation to the `login` method effectively represents an authentication
attempt.
+
+[#Authentication-AuthenticatingSubject-Step3]
+=== Step 3: Handling Success or Failure
+
+If the `login` method returns quietly, that's it - we're done!
+The `Subject` has been authenticated.
+The application thread can continue uninterrupted and all further calls to
`SecurityUtils.getSubject()` will return the authenticated `Subject` instance,
and any calls to
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
will return `true`.
+
+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?
+
+Shiro has a rich runtime
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthenticationException`]
hierarchy that can indicate exactly why the attempt failed.
+You can wrap `login` in a `try/catch` block and catch any exception you wish
and react to them accordingly.
+For example:
+
+[source,java]
+----
+try {
+ currentUser.login(token);
+} catch ( UnknownAccountException uae ) { ...
+} catch ( IncorrectCredentialsException ice ) { ...
+} catch ( LockedAccountException lae ) { ...
+} catch ( ExcessiveAttemptsException eae ) { ...
+} ... catch your own ...
+} catch ( AuthenticationException ae ) {
+ //unexpected error?
+}
+
+//No problems, continue on as expected...
+----
+
+If one of the existing exception classes do not meet your needs, custom
`AuthenticationExceptions` can be created to represent specific failure
scenarios.
+
+[TIP]
+====
+.Login Failure Tip
+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.
+====
+
+[#Authentication-RememberedVsAuthenticated]
+== Remembered vs. Authenticated
+
+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 _remembered_ Subject and an actual _authenticated_
Subject:
+
+* *Remembered*: A remembered `Subject` is not anonymous and has a known
identity (i.e.
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#getPrincipals()[getPrincipals()]`
is non-empty).
+But this identity is remembered from a previous authentication during a
*previous* session.
+A subject is considered remembered if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isRemembered()[isRemembered()]`
returns `true`.
+
+* *Authenticated*: An authenticated `Subject` is one that has been
successfully authenticated (i.e. the `login` method was invoked without
throwing an exception) _during the Subject's current session_.
+A subject is considered authenticated if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
returns `true`.
+
+[WARNING]
+====
+.Mutually Exclusive
+Remembered and authenticated states are mutually exclusive - a `true` value
for one indicates a `false` value for the other and vice versa.
+====
+
+[#Authentication-RememberedVsAuthenticated-WhyTheDistinction]
+=== Why the distinction?
+
+The word 'authentication' has a very strong connotation of _proof_.
+That is, there is an expected _guarantee_ that the `Subject` has proven they
are who they say they are.
+
+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 _guaranteeing_ 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.
+
+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.
+
+For example, a check to see if a `Subject` can access financial information
should almost always depend on `isAuthenticated()`, not `isRemembered()`, to
guarantee an expected and verified identity.
+
+[#Authentication-RememberedVsAuthenticated-AnIllustratingExample]
+=== An illustrating example
+
+The following is a fairly common scenario that helps illustrate why the the
distinction between remembered and authenticated is important.
+
+Let's say you're using https://www.amazon.com[Amazon.com].
+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.
+
+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, `subject.isRemembered()` would return `true`.
+
+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 (`isRemembered()` == `true`), it cannot guarantee
that you are in fact you (for example, maybe a co-worker is using your
computer).
+
+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,
`isAuthenticated()` would now be `true`.
+
+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 `isRemembered()` or `isAuthenticated()` to customize your
views and workflows is up to you, but Shiro will maintain this fundamental
state in case you need it.
+
+[#Authentication-LoggingOut]
+== Logging Out
+
+The opposite of authenticating is releasing all known identifying state.
+When the `Subject` is done interacting with the application, you can call
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#logout()[logout()]`
to relinquish all identifying information:
+
+[source,java]
+----
+currentUser.logout(); //removes all identifying information and invalidates
their session too.
+----
+
+When you call `logout`, any existing `Session` will be invalidated and any
identity will be disassociated (e.g. in a web app, the RememberMe cookie will
also be deleted).
+
+After a `Subject` logs-out, the `Subject` instance is considered anonymous
again and, except for web applications, can be re-used for `login` again if
desired.
+
+[CAUTION]
+====
+.Web Application Notice
+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 `subject.logout()`.
+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.
+====
Review comment:
Same, CAUTION might be a better choice which was not available in
MD+SCMS.
##########
File path: jbake/content/authentication.adoc
##########
@@ -0,0 +1,389 @@
+[#Authentication-Authentication]
+= Apache Shiro Authentication
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation
+:idprefix:
+:icons: font
+:toc:
+
+image::/img/ShiroFeatures_Authentication.png[Shiro features authentication
graphic, align="center"]
+
+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.
+
+This is done by submitting a user's _principals_ and _credentials_ to Shiro to
see if they match what is expected by the application.
+
+* *Principals* 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
`Subject`, so the best principals to use for authentication are unique for an
application - typically a username or email address.
+
+[NOTE]
+====
+.Primary Principal
+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 `Subject` within the application.
+This is typically a username, email address or globally unique user id in most
applications.
+====
+
+* *Credentials* are usually secret values known only by the `Subject` 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.
+
+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.
+
+
+== Authenticating Subjects
+
+The process of authenticating a `Subject` can effectively broken down into
three distinct steps:
+
+. Collect the Subject's submitted principals and credentials
+. Submit the principals and credentials for authentication.
+. If the submission is successful, allow access, otherwise retry
authentication or block access.
+
+The following code demonstrates how Shiro's API reflects these steps:
+
+[#Authentication-AuthenticatingSubject-Step1]
+=== Step 1: Collect the Subject's principals and credentials
+
+[source,java]
+----
+//Example using most common scenario of username/password pair:
+UsernamePasswordToken token = new UsernamePasswordToken(username, password);
+
+//"Remember Me" built-in:
+token.setRememberMe(true);
+
+----
+
+In this particular case, we’re using the
link:/static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html[UsernamePasswordToken],
supporting the most common username/password authentication approach.
+This is an implementation of Shiro's
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationToken.html[org.apache.shiro.authc.AuthenticationToken]
interface, which is the base interface used by Shiro's authentication system
to represent submitted principals and credentials.
+
+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 `AuthenticationToken` concept.
+
+You may construct and represent `AuthenticationToken` instances however you
like - it is protocol agnostic.
+
+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 Remember Me services in a later chapter.
+
+[#Authentication-AuthenticatingSubject-Step2]
+=== Step 2: Submit the principals and credentials
+
+After the principals and credentials have been collected and represented as an
`AuthenticationToken` instance, we need to submit the token to Shiro to perform
the actual authentication attempt:
+
+[source,java]
+----
+Subject currentUser = SecurityUtils.getSubject();
+
+currentUser.login(token);
+----
+
+After acquiring the currently-executing `Subject`, we make a single
`link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken)[login]`
call, passing in the `AuthenticationToken` instance we created earlier.
+
+An invocation to the `login` method effectively represents an authentication
attempt.
+
+[#Authentication-AuthenticatingSubject-Step3]
+=== Step 3: Handling Success or Failure
+
+If the `login` method returns quietly, that's it - we're done!
+The `Subject` has been authenticated.
+The application thread can continue uninterrupted and all further calls to
`SecurityUtils.getSubject()` will return the authenticated `Subject` instance,
and any calls to
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
will return `true`.
+
+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?
+
+Shiro has a rich runtime
link:/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html[`AuthenticationException`]
hierarchy that can indicate exactly why the attempt failed.
+You can wrap `login` in a `try/catch` block and catch any exception you wish
and react to them accordingly.
+For example:
+
+[source,java]
+----
+try {
+ currentUser.login(token);
+} catch ( UnknownAccountException uae ) { ...
+} catch ( IncorrectCredentialsException ice ) { ...
+} catch ( LockedAccountException lae ) { ...
+} catch ( ExcessiveAttemptsException eae ) { ...
+} ... catch your own ...
+} catch ( AuthenticationException ae ) {
+ //unexpected error?
+}
+
+//No problems, continue on as expected...
+----
+
+If one of the existing exception classes do not meet your needs, custom
`AuthenticationExceptions` can be created to represent specific failure
scenarios.
+
+[TIP]
+====
+.Login Failure Tip
+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.
+====
+
+[#Authentication-RememberedVsAuthenticated]
+== Remembered vs. Authenticated
+
+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 _remembered_ Subject and an actual _authenticated_
Subject:
+
+* *Remembered*: A remembered `Subject` is not anonymous and has a known
identity (i.e.
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#getPrincipals()[getPrincipals()]`
is non-empty).
+But this identity is remembered from a previous authentication during a
*previous* session.
+A subject is considered remembered if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isRemembered()[isRemembered()]`
returns `true`.
+
+* *Authenticated*: An authenticated `Subject` is one that has been
successfully authenticated (i.e. the `login` method was invoked without
throwing an exception) _during the Subject's current session_.
+A subject is considered authenticated if
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()[isAuthenticated()]`
returns `true`.
+
+[WARNING]
+====
+.Mutually Exclusive
+Remembered and authenticated states are mutually exclusive - a `true` value
for one indicates a `false` value for the other and vice versa.
+====
+
+[#Authentication-RememberedVsAuthenticated-WhyTheDistinction]
+=== Why the distinction?
+
+The word 'authentication' has a very strong connotation of _proof_.
+That is, there is an expected _guarantee_ that the `Subject` has proven they
are who they say they are.
+
+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 _guaranteeing_ 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.
+
+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.
+
+For example, a check to see if a `Subject` can access financial information
should almost always depend on `isAuthenticated()`, not `isRemembered()`, to
guarantee an expected and verified identity.
+
+[#Authentication-RememberedVsAuthenticated-AnIllustratingExample]
+=== An illustrating example
+
+The following is a fairly common scenario that helps illustrate why the the
distinction between remembered and authenticated is important.
+
+Let's say you're using https://www.amazon.com[Amazon.com].
+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.
+
+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, `subject.isRemembered()` would return `true`.
+
+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 (`isRemembered()` == `true`), it cannot guarantee
that you are in fact you (for example, maybe a co-worker is using your
computer).
+
+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,
`isAuthenticated()` would now be `true`.
+
+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 `isRemembered()` or `isAuthenticated()` to customize your
views and workflows is up to you, but Shiro will maintain this fundamental
state in case you need it.
+
+[#Authentication-LoggingOut]
+== Logging Out
+
+The opposite of authenticating is releasing all known identifying state.
+When the `Subject` is done interacting with the application, you can call
`subject.link:/static/current/apidocs/org/apache/shiro/subject/Subject.html#logout()[logout()]`
to relinquish all identifying information:
+
+[source,java]
+----
+currentUser.logout(); //removes all identifying information and invalidates
their session too.
+----
+
+When you call `logout`, any existing `Session` will be invalidated and any
identity will be disassociated (e.g. in a web app, the RememberMe cookie will
also be deleted).
+
+After a `Subject` logs-out, the `Subject` instance is considered anonymous
again and, except for web applications, can be re-used for `login` again if
desired.
+
+[CAUTION]
+====
+.Web Application Notice
+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 `subject.logout()`.
+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.
+====
+
+[#Authentication-AuthenticationSequence]
+== Authentication Sequence
+
+Until now, we've only looked at how to authenticate a `Subject` from within
application code.
+Now we'll cover what happens inside Shiro when an authentication attempt
occurs.
+
+We've taken our previous architecture diagram from the
link:/architecture.html[Architecture] chapter, and left only the components
relevant to authentication highlighted.
+Each number represents a step during an authentication attempt:
+
+image::/img/ShiroAuthenticationSequence.png[authentication flow diagram,
align="center"]
+
+*Step 1*: Application code invokes the `Subject.login` method, passing in the
constructed `AuthenticationToken` instance representing the end-user's
principals and credentials.
+
+*Step 2*: The `Subject` instance, typically a
link:/static/current/apidocs/org/apache/shiro/subject/support/DelegatingSubject.html[`DelegatingSubject`]
(or a subclass) delegates to the application's `SecurityManager` by calling
`securityManager.login(token)`, where the actual authentication work begins.
+
+*Step 3*: The `SecurityManager`, being a basic 'umbrella' component, receives
the token and simply delegates to its internal
link:/static/current/apidocs/org/apache/shiro/authc/Authenticator.html[`Authenticator`]
instance by calling
`link:/static/current/apidocs/org/apache/shiro/authc/Authenticator.html#authenticate(org.apache.shiro.authc.AuthenticationToken)[authenticator.authenticate(token)]`.
+This is almost always a
link:/static/current/apidocs/org/apache/shiro/authc/pam/ModularRealmAuthenticator.html[`ModularRealmAuthenticator`]
instance, which supports coordinating one or more `Realm` instances during
authentication.
+The `ModularRealmAuthenticator` essentially provides a
https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules[PAM]-style
paradigm for Apache Shiro (where each `Realm`
+is a 'module' in PAM terminology).
+
+*Step 4*: If more than one `Realm` is configured for the application, the
`ModularRealmAuthenticator` instance will initiate a multi-`Realm`
authentication attempt utilizing its configured
link:/static/current/apidocs/org/apache/shiro/authc/pam/AuthenticationStrategy.html[`AuthenticationStrategy`].
+Before, during and after the `Realms` are invoked for authentication, the
`AuthenticationStrategy` will be called to allow it to react to each Realm's
results.
+We will cover `AuthenticationStrategies` soon.
+
+[CAUTION]
+====
+.Single-Realm Application
+If only a single Realm is configured, it is called directly - there is no need
for an `AuthenticationStrategy` in a single-Realm application.
+====
Review comment:
This sounds more like INFO or TIP or NOTE to me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@shiro.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
