diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc index 383059d4a1..9aa35e604e 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc @@ -4,6 +4,51 @@ This section provides details on how Spring Security provides support for https://tools.ietf.org/html/rfc7617[Basic HTTP Authentication] for servlet based applications. // FIXME: describe authenticationentrypoint, authenticationfailurehandler, authenticationsuccesshandler +Let's take a look at how HTTP Basic Authentication works within Spring Security. +First, we see the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client. + +.Sending WWW-Authenticate Header +image::{figures}/basicauthenticationentrypoint.png[] + +The figure builds off our <> 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 <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. + +image:{icondir}/number_3.png[] Since the user is not authenticated, <> initiates __Start Authentication__. +The configured <> is an instance of {security-api-url}org/springframework/security/web/authentication/www/BasicAuthenticationEntryPoint.html[`BasicAuthenticationEntryPoint`] which sends a WWW-Authenticate header. +The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested. + +When a client receives the WWW-Authenticate header it knows it should retry with a username and password. +Below is the flow for the username and password being processed. + +.Authenticating Username and Password +image::{figures}/basicauthenticationfilter.png[] + +The figure builds off our <> diagram. + + +image:{icondir}/number_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <> 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 <>. + +image:{icondir}/number_3.png[] If authentication fails, then __Failure__ + +* The <> is cleared out. +* `RememberMeServices.loginFail` is invoked. +If remember me is not configured, this is a no-op. +// FIXME: link to rememberme +* `AuthenticationEntryPoint` is invoked to trigger the WWW-Authenticate to be sent again. + +image:{icondir}/number_4.png[] If authentication is successful, then __Success__. +* The <> is set on the <>. +* `RememberMeServices.loginSuccess` is invoked. +If remember me is not configured, this is a no-op. +// FIXME: link to rememberme +* The `BasicAuthenticationFilter` invokes `FilterChain.doFilter(request,response)` to continue with the rest of the application logic. + Spring Security's HTTP Basic Authentication support in is enabled by default. However, as soon as any servlet based configuration is provided, HTTP Basic must be explicitly provided. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc index f3e5d051af..4d2d818094 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc @@ -1,7 +1,5 @@ [[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. @@ -11,7 +9,7 @@ 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[] +image::{figures}/loginurlauthenticationentrypoint.png[] The figure builds off our <> diagram. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc index 5915222130..94d4fb0b09 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc @@ -1,5 +1,7 @@ [[servlet-authentication-unpwd]] = Username/Password Authentication +:figures: images/servlet/authentication/unpwd +:icondir: images/icons 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 authenticating with a username and password. diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg new file mode 100644 index 0000000000..6686d77d61 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png new file mode 100644 index 0000000000..7361a16835 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.odg new file mode 100644 index 0000000000..b44a93bce5 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.odg differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.png new file mode 100644 index 0000000000..a9471e2105 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.png differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg similarity index 100% rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.odg rename to docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png similarity index 100% rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.png rename to docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png