From 5e9c03aa83592e613270cfc5795f73c8b23ebfb8 Mon Sep 17 00:00:00 2001
From: Rob Winch <rwinch@users.noreply.github.com>
Date: Thu, 20 Feb 2020 14:48:32 -0600
Subject: [PATCH] Add AbstractAuthenticationProcessingFilter Docs

Closes gh-8004
---
 ...ract-authentication-processing-filter.adoc | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc

diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc
new file mode 100644
index 0000000000..a27c6d1313
--- /dev/null
+++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc
@@ -0,0 +1,40 @@
+= AbstractAuthenticationProcessingFilter
+:figures: images/servlet/authentication/architecture
+:icondir: images/icons
+
+{security-api-url}org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.html[`AbstractAuthenticationProcessingFilter`] is used as a base `Filter` for authenticating a user's credentials.
+Before the credentials can be authenticated, Spring Security typically requests the credentials using <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
+
+Next, the `AbstractAuthenticationProcessingFilter` can authenticate any authentication requests that are submitted to it.
+
+image::{figures}/abstractauthenticationprocessingfilter.png[]
+
+image:{icondir}/number_1.png[] When the user submits their credentials, the `AbstractAuthenticationProcessingFilter` creates an <<servlet-authentication>> from the `HttpServletRequest` to be authenticated.
+The type of `Authentication` created depends on the subclass of `AbstractAuthenticationProcessingFilter`.
+For example, `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`.
+// FIXME: link UsernamePasswordAuthenticationFilter
+
+image:{icondir}/number_2.png[] Next, the `Authentication` is passed into the `AuthenticationManager` to be authenticated.
+// FIXME: link to AuthenticationManager
+
+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>>.
+Later the `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession`.
+// 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`.
+