diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/dao-authentication-provider.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/dao-authentication-provider.adoc new file mode 100644 index 0000000000..3818a019ac --- /dev/null +++ b/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 <> implementation that leverages a <> and <> 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 <> in figures from <> works. + +.`DaoAuthenticationProvider` Usage +image::{figures}/daoauthenticationprovider.png[] + +image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by <>. + +image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <> 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 <> to validate the password on the `UserDetails` returned in the previous step. + +image:{icondir}/number_5.png[] When authentication is successful, the <> 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 <> by the authentication `Filter`. 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 94d4fb0b09..415d828118 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 @@ -7,6 +7,8 @@ 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`: * <> @@ -14,12 +16,14 @@ Spring Security provides the following built in mechanisms for reading a usernam * <> [[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 <> * Relational Databases with <> -* LDAP Servers with <> * Custom data stores with <> +* LDAP storage with <> 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] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/password-encoder.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/password-encoder.adoc index 587bc876b0..73f9e1f2e1 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/password-encoder.adoc +++ b/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 <>. +Customizing the `PasswordEncoder` implementation used by Spring Security can be done by <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc index 2a70647bcf..9147cedbd2 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc +++ b/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 <> for retrieving a username, password, and other attributes for authenticating with a username and password. +Spring Security provides <> and <> 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"] +---- + +---- -[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 diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details.adoc new file mode 100644 index 0000000000..d56626b37e --- /dev/null +++ b/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 <>. +The <> validates the `UserDetails` and then returns an <> that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`. diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.odg b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.odg new file mode 100644 index 0000000000..0bc89db347 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.odg differ diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.png b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.png new file mode 100644 index 0000000000..f8fec179e6 Binary files /dev/null and b/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.png differ