Update UserDetailsService Docs

Closes gh-8048

Author: rwinch

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/dao-authentication-provider.adoc

@@ -0,0 +1,21 @@
+[[servlet-authentication-daoauthenticationprovider]]
+= DaoAuthenticationProvider
+
+{security-api-url}org/springframework/security/authentication/dao/DaoAuthenticationProvider.html[`DaoAuthenticationProvider`] is an <<servlet-authentication-authenticationprovider,`AuthenticationProvider`>> implementation that leverages a <<servlet-authentication-userdetailsservice,`UserDetailsService`>> and <<servlet-authentication-password-storage,`PasswordEncoder`>> to authenticate a username and password.
+
+Let's take a look at how `DaoAuthenticationProvider` works within Spring Security.
+The figure explains details of how the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> in figures from <<servlet-authentication-unpwd-input,Reading the Username & Password>> works.
+
+.`DaoAuthenticationProvider` Usage
+image::{figures}/daoauthenticationprovider.png[]
+
+image:{icondir}/number_1.png[] The authentication `Filter` from <<servlet-authentication-unpwd-input,Reading the Username & Password>> passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by <<servlet-authentication-providermanager,`ProviderManager`>>.
+
+image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <<servlet-authentication-authenticationprovider>> of type `DaoAuthenticationProvider`.
+
+image:{icondir}/number_3.png[] `DaoAuthenticationProvider` looks up the `UserDetails` from the `UserDetailsService`.
+
+image:{icondir}/number_4.png[] `DaoAuthenticationProvider` then uses the <<servlet-authentication-password-storage,`PasswordEncoder`>> to validate the password on the `UserDetails` returned in the previous step.
+
+image:{icondir}/number_5.png[] When authentication is successful, the <<servlet-authentication-authentication,`Authentication`>> that is returned is of type `UsernamePasswordAuthenticationToken` and has a principal that is the `UserDetails` returned by the configured `UserDetailsService`.
+Ultimately, the returned `UsernamePasswordAuthenticationToken` will be set on the <<servlet-authentication-securitycontextholder,`SecurityContextHolder`>> by the authentication `Filter`.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc

@@ -7,19 +7,23 @@ One of the most common ways to authenticate a user is by validating a username a
 As such, Spring Security provides comprehensive support for authenticating with a username and password.
 
 [[servlet-authentication-unpwd-input]]
+*Reading the Username & Password*
+
 Spring Security provides the following built in mechanisms for reading a username and password from the `HttpServletRequest`:
 
 * <<servlet-authentication-form,Form Login>>
 * <<servlet-authentication-basic,Basic Authentication>>
 * <<servlet-authentication-digest,Digest Authentication>>
 
 [[servlet-authentication-unpwd-storage]]
+*Storage Mechanisms*
+
 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>>
+* LDAP storage with <<servlet-authentication-ldap>>
 
 include::form.adoc[leveloffset=+1]
 
@@ -31,6 +35,12 @@ include::in-memory.adoc[leveloffset=+1]
 
 include::jdbc.adoc[leveloffset=+1]
 
-include::ldap.adoc[leveloffset=+1]
+include::user-details.adoc[leveloffset=+1]
 
 include::user-details-service.adoc[leveloffset=+1]
+
+include::password-encoder.adoc[leveloffset=+1]
+
+include::dao-authentication-provider.adoc[leveloffset=+1]
+
+include::ldap.adoc[leveloffset=+1]

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/password-encoder.adoc

@@ -1,4 +1,5 @@
-[[servlet-password-storage]]
-= Password Storage
+[[servlet-authentication-password-storage]]
+= PasswordEncoder
 
-Spring Security provides
+Spring Security's servlet support storing passwords securely by integrating with <<authentication-password-storage,`PasswordEncoder`>>.
+Customizing the `PasswordEncoder` implementation used by Spring Security can be done by <<authentication-password-storage-configuration,exposing a `PasswordEncoder` Bean>>.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc

@@ -1,26 +1,37 @@
 [[servlet-authentication-userdetailsservice]]
 = UserDetailsService
 
+{security-api-url}org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] is used by <<servlet-authentication-daoauthenticationprovider,`DaoAuthenticationProvider`>> for retrieving a username, password, and other attributes for authenticating with a username and password.
+Spring Security provides <<servlet-authentication-inmemory,in-memory>> and <<servlet-authentication-jdbc,JDBC>> implementations of `UserDetailsService`.
+
 You can define custom authentication by exposing a custom `UserDetailsService` as a bean.
-For example, the following will customize authentication assuming that `SpringDataUserDetailsService` implements `UserDetailsService`:
+For example, the following will customize authentication assuming that `CustomUserDetailsService` implements `UserDetailsService`:
 
 NOTE: This is only used if the `AuthenticationManagerBuilder` has not been populated and no `AuthenticationProviderBean` is defined.
 
-[source,java]
+.Custom UserDetailsService Bean
+====
+.Java
+[source,java,role="primary"]
 ----
 @Bean
-public SpringDataUserDetailsService springDataUserDetailsService() {
-	return new SpringDataUserDetailsService();
+CustomUserDetailsService customUserDetailsService() {
+	return new CustomUserDetailsService();
 }
 ----
 
-You can also customize how passwords are encoded by exposing a `PasswordEncoder` as a bean.
-For example, if you use bcrypt you can add a bean definition as shown below:
+.XML
+[source,java,role="secondary"]
+----
+<b:bean class="example.CustomUserDetailsService"/>
+----
 
-[source,java]
+.Kotlin
+[source,kotlin,role="secondary"]
 ----
 @Bean
-public BCryptPasswordEncoder passwordEncoder() {
-	return new BCryptPasswordEncoder();
-}
+fun customUserDetailsService() = CustomUserDetailsService()
 ----
+====
+
+// FIXME: Add CustomUserDetails example with links to @AuthenticationPrincipal

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details.adoc

@@ -0,0 +1,5 @@
+[[servlet-authentication-userdetails]]
+= UserDetails
+
+{security-api-url}org/springframework/security/core/userdetails/UserDetails.html[`UserDetails`] is returned by the <<servlet-authentication-userdetailsservice,`UserDetailsService`>>.
+The <<servlet-authentication-daoauthenticationprovider,`DaoAuthenticationProvider`>> validates the `UserDetails` and then returns an <<servlet-authentication-authentication,`Authentication`>> that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`.