Add Figures to Form Log In Docs

Closes gh-8035

Author: rwinch

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc

@@ -1,7 +1,5 @@
 [[servlet-authentication-authenticationentrypoint]]
 = Request Credentials with `AuthenticationEntryPoint`
-:figures: images/servlet/authentication/architecture
-:icondir: images/icons
 
 
 {security-api-url}org/springframework/security/web/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`] is used to send an HTTP response that requests credentials from a client.
@@ -11,23 +9,6 @@ In these cases, Spring Security does not need to provide an HTTP response that r
 
 In other cases, a client will make an unauthenticated request to a resource that they are not authorized to access.
 In this case, an implementation of `AuthenticationEntryPoint` is used to request credentials from the client.
-The `AuthenticationEntryPoint` implementation might perform a redirect to a log in page, respond with an https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate[WWW-Authenticate] header, etc.
+The `AuthenticationEntryPoint` implementation might perform a <<servlet-authentication-form,redirect to a log in page>>, respond with an https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate[WWW-Authenticate] header, etc.
 
-[[servlet-authentication-authenticationentrypoint-example]]
-To better understand how `AuthenticationEntryPoint` is used, let's take a look at a concrete example using <<servlet-authentication-form,form based log in>>.
-// FIXME: link to form based login
 
-.AuthenticationEntryPoint with Form Log In
-image::{figures}/request-credentials.png[]
-
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
-
-image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
-
-image:{icondir}/number_2.png[] Spring Security's <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
-
-image:{icondir}/number_3.png[] Since the user is not authenticated, <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__ and sends a redirect to the log in page with the configured `AuthenticationEntryPoint`.
-
-image:{icondir}/number_4.png[] The browser will then request the log in page that it was redirected to.
-
-image:{icondir}/number_5.png[] Something within the application, must <<servlet-authentication-form-custom,render the log in page>>.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/basic.adoc renamed to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc

@@ -1,18 +1,73 @@
 [[servlet-authentication-form]]
 = Form Login
+:figures: images/servlet/authentication/unpwd
+:icondir: images/icons
 
 Spring Security provides support for username and password being provided through an html form.
 This section provides details on how form based authentication works within Spring Security.
 // FIXME: describe authenticationentrypoint, authenticationfailurehandler, authenticationsuccesshandler
 
-[[servlet-authentication-form-min]]
-== Form Login Configuration
+Let's take a look at how form based log in works within Spring Security.
+First, we see how the user is redirected to the log in form.
+
+.Redirecting to the Log In Page
+image::{figures}/request-credentials.png[]
+
+The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+
+image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
+
+image:{icondir}/number_2.png[] Spring Security's <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
+
+image:{icondir}/number_3.png[] Since the user is not authenticated, <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__ and sends a redirect to the log in page with the configured <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
+In most cases the `AuthenticationEntryPoint` is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`].
+
+image:{icondir}/number_4.png[] The browser will then request the log in page that it was redirected to.
+
+image:{icondir}/number_5.png[] Something within the application, must <<servlet-authentication-form-custom,render the log in page>>.
+
+[[servlet-authentication-usernamepasswordauthenticationfilter]]
+When the username and password are submitted, the `UsernamePasswordAuthenticationFilter` authenticates the username and password.
+The `UsernamePasswordAuthenticationFilter` extends <<servlet-authentication-abstractprocessingfilter>>, so this diagram should look pretty similar.
+
+.Authenticating Username and Password
+image::{figures}/usernamepasswordauthenticationfilter.png[]
 
+The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+
+
+image:{icondir}/number_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <<servlet-authentication-authentication,`Authentication`>> by extracting the username and password from the `HttpServletRequest`.
+
+image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated.
+The details of what `AuthenticationManager` look like depend on how the <<servlet-authentication-unpwd-storage,user information is stored>>.
+
+image:{icondir}/number_3.png[] If authentication fails, then __Failure__
+
+* The <<servlet-authentication-securitycontextholder>> is cleared out.
+* `RememberMeServices.loginFail` is invoked.
+If remember me is not configured, this is a no-op.
+// FIXME: link to rememberme
+* `AuthenticationFailureHandler` is invoked.
+// FIXME: link to AuthenticationFailureHandler
+
+image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
+
+* `SessionAuthenticationStrategy` is notified of a new log in.
+// FIXME: Add link to SessionAuthenticationStrategy
+* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
+// FIXME: link securitycontextpersistencefilter
+* `RememberMeServices.loginSuccess` is invoked.
+If remember me is not configured, this is a no-op.
+// FIXME: link to rememberme
+* `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`.
+* The `AuthenticationSuccessHandler` is invoked. Typically this is a `SimpleUrlAuthenticationSuccessHandler` which will redirect to a request saved by <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> when we redirect to the log in page.
+
+[[servlet-authentication-form-min]]
 Spring Security form log in is enabled by default.
 However, as soon as any servlet based configuration is provided, form based log in must be explicitly provided.
 A minimal, explicit Java configuration can be found below:
 
-.Form Log
+.Form Log In
 ====
 .Java
 [source,java,role="primary"]
@@ -49,8 +104,6 @@ In this configuration Spring Security will render a default log in page.
 Most production applications will require a custom log in form.
 
 [[servlet-authentication-form-custom]]
-== Custom Log In Form
-
 The configuration below demonstrates how to provide a custom log in form.
 
 .Custom Log In Form Configuration

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/digest.adoc renamed to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc

@@ -2,8 +2,33 @@
 = Username/Password Authentication
 
 One of the most common ways to authenticate a user is by validating a username and password.
-As such, Spring Security provides comprehensive support for user <<servlet-authentication-unpwd-input,input>> and <<servlet-authentication-unpwd-storage,storage>> of a username and password.
+As such, Spring Security provides comprehensive support for authenticating with a username and password.
 
-include::input/index.adoc[leveloffset=+1]
+[[servlet-authentication-unpwd-input]]
+Spring Security provides the following built in mechanisms for reading a username and password from the `HttpServletRequest`:
 
-include::storage/index.adoc[leveloffset=+1]
+* <<servlet-authentication-form,Form Login>>
+* <<servlet-authentication-basic,Basic Authentication>>
+* <<servlet-authentication-digest,Digest Authentication>>
+
+[[servlet-authentication-unpwd-storage]]
+Each of the supported mechanisms for reading a username and password can leverage any of the supported storage mechanisms:
+
+* Simple Storage with <<servlet-authentication-inmemory>>
+* Relational Databases with <<servlet-authentication-jdbc>>
+* LDAP Servers with <<servlet-authentication-ldap>>
+* Custom data stores with <<servlet-authentication-userdetailsservice>>
+
+include::form.adoc[leveloffset=+1]
+
+include::basic.adoc[leveloffset=+1]
+
+include::digest.adoc[leveloffset=+1]
+
+include::in-memory.adoc[leveloffset=+1]
+
+include::jdbc.adoc[leveloffset=+1]
+
+include::ldap.adoc[leveloffset=+1]
+
+include::user-details-service.adoc[leveloffset=+1]