Use LDAP AuthenticationManager factory in reference docs

Closes gh-10789

Author: eleftherias

docs/modules/ROOT/pages/servlet/authentication/passwords/ldap.adoc

@@ -120,14 +120,39 @@ depenendencies {
 ----
 ====
 
-You can then configure the Embedded LDAP Server:
+You can then configure the Embedded LDAP Server using an `EmbeddedLdapServerContextSourceFactoryBean`.
+This will instruct Spring Security to start an in-memory LDAP server:
 
 .Embedded LDAP Server Configuration
 ====
 .Java
 [source,java,role="primary"]
 ----
 @Bean
+public EmbeddedLdapServerContextSourceFactoryBean contextSourceFactoryBean() {
+	return EmbeddedLdapServerContextSourceFactoryBean.fromEmbeddedLdapServer();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun contextSourceFactoryBean(): EmbeddedLdapServerContextSourceFactoryBean {
+    return EmbeddedLdapServerContextSourceFactoryBean.fromEmbeddedLdapServer()
+}
+----
+====
+
+Alternatively, you can manually configure the Embedded LDAP Server.
+If you choose this approach, you will be responsible for managing the lifecycle of the Embedded LDAP Server.
+
+.Explicit Embedded LDAP Server Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
 UnboundIdContainer ldapContainer() {
 	return new UnboundIdContainer("dc=springframework,dc=org",
 				"classpath:users.ldif");
@@ -229,7 +254,36 @@ fun ldapContainer(): ApacheDSContainer {
 == LDAP ContextSource
 
 Once you have an LDAP Server to which to point your configuration, you need to configure Spring Security to point to an LDAP server that should be used to authenticate users.
-To do so, create an LDAP `ContextSource` (which is the equivalent of a JDBC `DataSource`):
+To do so, create an LDAP `ContextSource` (which is the equivalent of a JDBC `DataSource`).
+If you have already configured an `EmbeddedLdapServerContextSourceFactoryBean`, Spring Security will create an LDAP `ContextSource` that points to the embedded LDAP server.
+
+.LDAP Context Source with Embedded LDAP Server
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public EmbeddedLdapServerContextSourceFactoryBean contextSourceFactoryBean() {
+	EmbeddedLdapServerContextSourceFactoryBean contextSourceFactoryBean =
+			EmbeddedLdapServerContextSourceFactoryBean.fromEmbeddedLdapServer();
+	contextSourceFactoryBean.setPort(0);
+	return contextSourceFactoryBean;
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun contextSourceFactoryBean(): EmbeddedLdapServerContextSourceFactoryBean {
+    val contextSourceFactoryBean = EmbeddedLdapServerContextSourceFactoryBean.fromEmbeddedLdapServer()
+    contextSourceFactoryBean.setPort(0)
+    return contextSourceFactoryBean
+}
+----
+====
+
+Alternatively, you can explicitly configure the LDAP `ContextSource` to connect to the supplied LDAP server:
 
 .LDAP Context Source
 ====
@@ -288,15 +342,10 @@ The following example shows bind authentication configuration:
 [source,java,role="primary",attrs="-attributes"]
 ----
 @Bean
-BindAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
-	BindAuthenticator authenticator = new BindAuthenticator(contextSource);
-	authenticator.setUserDnPatterns(new String[] { "uid={0},ou=people" });
-	return authenticator;
-}
-
-@Bean
-LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
-	return new LdapAuthenticationProvider(authenticator);
+AuthenticationManager authenticationManager(BaseLdapPathContextSource contextSource) {
+	LdapBindAuthenticationManagerFactory factory = new LdapBindAuthenticationManagerFactory(contextSource);
+	factory.setUserDnPatterns("uid={0},ou=people");
+	return factory.createAuthenticationManager();
 }
 ----
 
@@ -311,15 +360,10 @@ LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticato
 [source,kotlin,role="secondary",attrs="-attributes"]
 ----
 @Bean
-fun authenticator(contextSource: BaseLdapPathContextSource): BindAuthenticator {
-    val authenticator = BindAuthenticator(contextSource)
-    authenticator.setUserDnPatterns(arrayOf("uid={0},ou=people"))
-    return authenticator
-}
-
-@Bean
-fun authenticationProvider(authenticator: LdapAuthenticator): LdapAuthenticationProvider {
-    return LdapAuthenticationProvider(authenticator)
+fun authenticationManager(contextSource: BaseLdapPathContextSource): AuthenticationManager {
+    val factory = LdapBindAuthenticationManagerFactory(contextSource)
+    factory.setUserDnPatterns("uid={0},ou=people")
+    return factory.createAuthenticationManager()
 }
 ----
 ====
@@ -334,19 +378,11 @@ If, instead, you wish to configure an LDAP search filter to locate the user, you
 [source,java,role="primary",attrs="-attributes"]
 ----
 @Bean
-BindAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
-	String searchBase = "ou=people";
-	String filter = "(uid={0})";
-	FilterBasedLdapUserSearch search =
-		new FilterBasedLdapUserSearch(searchBase, filter, contextSource);
-	BindAuthenticator authenticator = new BindAuthenticator(contextSource);
-	authenticator.setUserSearch(search);
-	return authenticator;
-}
-
-@Bean
-LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
-	return new LdapAuthenticationProvider(authenticator);
+AuthenticationManager authenticationManager(BaseLdapPathContextSource contextSource) {
+	LdapBindAuthenticationManagerFactory factory = new LdapBindAuthenticationManagerFactory(contextSource);
+	factory.setUserSearchFilter("(uid={0})");
+	factory.setUserSearchBase("ou=people");
+	return factory.createAuthenticationManager();
 }
 ----
 
@@ -362,18 +398,11 @@ LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticato
 [source,kotlin,role="secondary",attrs="-attributes"]
 ----
 @Bean
-fun authenticator(contextSource: BaseLdapPathContextSource): BindAuthenticator {
-    val searchBase = "ou=people"
-    val filter = "(uid={0})"
-    val search = FilterBasedLdapUserSearch(searchBase, filter, contextSource)
-    val authenticator = BindAuthenticator(contextSource)
-    authenticator.setUserSearch(search)
-    return authenticator
-}
-
-@Bean
-fun authenticationProvider(authenticator: LdapAuthenticator): LdapAuthenticationProvider {
-    return LdapAuthenticationProvider(authenticator)
+fun authenticationManager(contextSource: BaseLdapPathContextSource): AuthenticationManager {
+    val factory = LdapBindAuthenticationManagerFactory(contextSource)
+    factory.setUserSearchFilter("(uid={0})")
+    factory.setUserSearchBase("ou=people")
+    return factory.createAuthenticationManager()
 }
 ----
 ====
@@ -395,13 +424,11 @@ An LDAP compare cannot be done when the password is properly hashed with a rando
 [source,java,role="primary"]
 ----
 @Bean
-PasswordComparisonAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
-	return new PasswordComparisonAuthenticator(contextSource);
-}
-
-@Bean
-LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
-	return new LdapAuthenticationProvider(authenticator);
+AuthenticationManager authenticationManager(BaseLdapPathContextSource contextSource) {
+	LdapPasswordComparisonAuthenticationManagerFactory factory = new LdapPasswordComparisonAuthenticationManagerFactory(
+			contextSource, NoOpPasswordEncoder.getInstance());
+	factory.setUserDnPatterns("uid={0},ou=people");
+	return factory.createAuthenticationManager();
 }
 ----
 
@@ -418,13 +445,12 @@ LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticato
 [source,kotlin,role="secondary"]
 ----
 @Bean
-fun authenticator(contextSource: BaseLdapPathContextSource): PasswordComparisonAuthenticator {
-    return PasswordComparisonAuthenticator(contextSource)
-}
-
-@Bean
-fun authenticationProvider(authenticator: LdapAuthenticator): LdapAuthenticationProvider {
-    return LdapAuthenticationProvider(authenticator)
+fun authenticationManager(contextSource: BaseLdapPathContextSource?): AuthenticationManager? {
+    val factory = LdapPasswordComparisonAuthenticationManagerFactory(
+        contextSource, NoOpPasswordEncoder.getInstance()
+    )
+    factory.setUserDnPatterns("uid={0},ou=people")
+    return factory.createAuthenticationManager()
 }
 ----
 ====
@@ -437,17 +463,12 @@ The following example shows a more advanced configuration with some customizatio
 [source,java,role="primary"]
 ----
 @Bean
-PasswordComparisonAuthenticator authenticator(BaseLdapPathContextSource contextSource) {
-	PasswordComparisonAuthenticator authenticator =
-		new PasswordComparisonAuthenticator(contextSource);
-	authenticator.setPasswordAttributeName("pwd"); // <1>
-	authenticator.setPasswordEncoder(new BCryptPasswordEncoder()); // <2>
-	return authenticator;
-}
-
-@Bean
-LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator) {
-	return new LdapAuthenticationProvider(authenticator);
+AuthenticationManager authenticationManager(BaseLdapPathContextSource contextSource) {
+	LdapPasswordComparisonAuthenticationManagerFactory factory = new LdapPasswordComparisonAuthenticationManagerFactory(
+			contextSource, new BCryptPasswordEncoder());
+	factory.setUserDnPatterns("uid={0},ou=people");
+	factory.setPasswordAttribute("pwd");  // <1>
+	return factory.createAuthenticationManager();
 }
 ----
 
@@ -468,23 +489,18 @@ LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticato
 [source,kotlin,role="secondary"]
 ----
 @Bean
-fun authenticator(contextSource: BaseLdapPathContextSource): PasswordComparisonAuthenticator {
-    val authenticator = PasswordComparisonAuthenticator(contextSource)
-    authenticator.setPasswordAttributeName("pwd") // <1>
-    authenticator.setPasswordEncoder(BCryptPasswordEncoder()) // <2>
-    return authenticator
-}
-
-@Bean
-fun authenticationProvider(authenticator: LdapAuthenticator): LdapAuthenticationProvider {
-    return LdapAuthenticationProvider(authenticator)
+fun authenticationManager(contextSource: BaseLdapPathContextSource): AuthenticationManager {
+    val factory = LdapPasswordComparisonAuthenticationManagerFactory(
+        contextSource, BCryptPasswordEncoder()
+    )
+    factory.setUserDnPatterns("uid={0},ou=people")
+    factory.setPasswordAttribute("pwd") // <1>
+    return factory.createAuthenticationManager()
 }
 ----
 ====
 
 <1> Specify the password attribute as `pwd`.
-<2> Use `BCryptPasswordEncoder`.
-
 
 == LdapAuthoritiesPopulator
 
@@ -506,8 +522,11 @@ LdapAuthoritiesPopulator authorities(BaseLdapPathContextSource contextSource) {
 }
 
 @Bean
-LdapAuthenticationProvider authenticationProvider(LdapAuthenticator authenticator, LdapAuthoritiesPopulator authorities) {
-	return new LdapAuthenticationProvider(authenticator, authorities);
+AuthenticationManager authenticationManager(BaseLdapPathContextSource contextSource, LdapAuthoritiesPopulator authorities) {
+	LdapBindAuthenticationManagerFactory factory = new LdapBindAuthenticationManagerFactory(contextSource);
+	factory.setUserDnPatterns("uid={0},ou=people");
+	factory.setLdapAuthoritiesPopulator(authorities);
+	return factory.createAuthenticationManager();
 }
 ----
 
@@ -531,8 +550,13 @@ fun authorities(contextSource: BaseLdapPathContextSource): LdapAuthoritiesPopula
 }
 
 @Bean
-fun authenticationProvider(authenticator: LdapAuthenticator, authorities: LdapAuthoritiesPopulator): LdapAuthenticationProvider {
-    return LdapAuthenticationProvider(authenticator, authorities)
+fun authenticationManager(
+    contextSource: BaseLdapPathContextSource,
+    authorities: LdapAuthoritiesPopulator): AuthenticationManager {
+    val factory = LdapBindAuthenticationManagerFactory(contextSource)
+    factory.setUserDnPatterns("uid={0},ou=people")
+    factory.setLdapAuthoritiesPopulator(authorities)
+    return factory.createAuthenticationManager()
 }
 ----
 ====