diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc index 3ab0b1f3c5..ca0bca572e 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc +++ b/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 <>, 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 <>. -// FIXME: link to form based login -.AuthenticationEntryPoint with Form Log In -image::{figures}/request-credentials.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__ 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 <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/basic.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/basic.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/digest.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/digest.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/form.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc similarity index 51% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/form.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc index f3de983ae7..f3e5d051af 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/form.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.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 <> 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__ and sends a redirect to the log in page with the configured <>. +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-usernamepasswordauthenticationfilter]] +When the username and password are submitted, the `UsernamePasswordAuthenticationFilter` authenticates the username and password. +The `UsernamePasswordAuthenticationFilter` extends <>, so this diagram should look pretty similar. + +.Authenticating Username and Password +image::{figures}/usernamepasswordauthenticationfilter.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 +* `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 <> is set on the <>. +// 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 <> 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 diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/in-memory.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/in-memory.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc 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 2685c50048..5915222130 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 @@ -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 <> and <> 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-unpwd-storage]] +Each of the supported mechanisms for reading a username and password can leverage any of the supported storage mechanisms: + +* Simple Storage with <> +* Relational Databases with <> +* LDAP Servers with <> +* Custom data stores with <> + +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] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/index.adoc deleted file mode 100644 index 435dcd2d15..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/input/index.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[[servlet-authentication-unpwd-input]] -= Username/Password Input - -Spring Security provides multiple ways for a user to enter their username and password. -Each of the supported mechanisms leverage any of the supported <> mechanisms. -This section discusses how a username and password can be provided to Spring Security: - -* <> -* <> -* <> - -include::form.adoc[leveloffset=+1] - -include::basic.adoc[leveloffset=+1] - -include::digest.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/jdbc.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/jdbc.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/jdbc.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/jdbc.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/ldap.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/ldap.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/ldap.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/ldap.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/user-details-service.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc similarity index 100% rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/user-details-service.adoc rename to docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.odg deleted file mode 100644 index 5388b3bcb9..0000000000 Binary files a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.odg and /dev/null differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.png deleted file mode 100644 index d3507233ec..0000000000 Binary files a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/request-credentials.png and /dev/null 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/request-credentials.odg new file mode 100644 index 0000000000..b40d43fc95 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.odg differ 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/request-credentials.png new file mode 100644 index 0000000000..a3dc2ae2d4 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/request-credentials.png differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg new file mode 100644 index 0000000000..298c504d2b Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png new file mode 100644 index 0000000000..1f06ce8423 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png differ