Document usage of `AuthenticationEventPublisher`

Closes gh-11420

spring-boot-project/spring-boot-autoconfigure/src/test/java/org/springframework/boot/autoconfigure/security/servlet/SecurityAutoConfigurationTests.java

@@ -39,14 +39,18 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.mock.web.MockServletContext;
 import org.springframework.orm.jpa.JpaTransactionManager;
+import org.springframework.security.authentication.AuthenticationEventPublisher;
 import org.springframework.security.authentication.AuthenticationManager;
 import org.springframework.security.authentication.AuthenticationProvider;
+import org.springframework.security.authentication.DefaultAuthenticationEventPublisher;
 import org.springframework.security.authentication.ProviderManager;
 import org.springframework.security.authentication.TestingAuthenticationProvider;
 import org.springframework.security.authentication.TestingAuthenticationToken;
 import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
 import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.AuthenticationException;
 import org.springframework.security.core.userdetails.User;
 import org.springframework.security.core.userdetails.UserDetailsService;
 import org.springframework.security.data.repository.query.SecurityEvaluationContextExtension;
@@ -116,6 +120,25 @@ public class SecurityAutoConfigurationTests {
 		}
 	}
 
+	@Test
+	public void defaultAuthenticationEventPublisherRegistered() {
+		this.context = new AnnotationConfigWebApplicationContext();
+		this.context.register(SecurityAutoConfiguration.class);
+		this.context.refresh();
+		assertThat(this.context.getBean(AuthenticationEventPublisher.class))
+				.isInstanceOf(DefaultAuthenticationEventPublisher.class);
+	}
+
+	@Test
+	public void defaultAuthenticationEventPublisherIsConditionalOnMissingBean() {
+		this.context = new AnnotationConfigWebApplicationContext();
+		this.context.register(AuthenticationEventPublisherConfiguration.class,
+				SecurityAutoConfiguration.class);
+		this.context.refresh();
+		assertThat(this.context.getBean(AuthenticationEventPublisher.class))
+				.isInstanceOf(AuthenticationEventPublisherConfiguration.TestAuthenticationEventPublisher.class);
+	}
+
 	@Test
 	public void testDefaultFilterOrder() {
 		this.context = new AnnotationConfigWebApplicationContext();
@@ -274,6 +297,28 @@ public class SecurityAutoConfigurationTests {
 
 	}
 
+	@Configuration
+	static class AuthenticationEventPublisherConfiguration {
+
+		@Bean
+		public AuthenticationEventPublisher authenticationEventPublisher() {
+			return new TestAuthenticationEventPublisher();
+		}
+
+		class TestAuthenticationEventPublisher implements AuthenticationEventPublisher {
+
+			@Override
+			public void publishAuthenticationSuccess(Authentication authentication) {
+
+			}
+
+			@Override
+			public void publishAuthenticationFailure(AuthenticationException exception, Authentication authentication) {
+
+			}
+		}
+	}
+
 	@Configuration
 	protected static class TestAuthenticationManagerConfiguration {
 

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -2992,7 +2992,9 @@ bean with in-memory store and a single user with a generated password (see
 for the properties of the user).
 * Form-based login or HTTP Basic security (depending on Content-Type) for the entire
 application (including actuator endpoints if actuator is on the classpath).
+* A `DefaultAuthenticationEventPublisher` for publishing authentication events.
 
+You can provide a different `AuthenticationEventPublisher` by adding a bean for it.
 
 
 [[boot-features-security-mvc]]