Add Support for Custom Default Configuration in Web Security

Fixes gh-4102

docs/manual/src/docs/asciidoc/index.adoc

@@ -1101,6 +1101,93 @@ protected void configure(HttpSecurity http) throws Exception {
 }
 ----
 
+[[jc-custom-dsls]]
+=== Custom DSLs
+
+You can provide your own custom DSLs in Spring Security.
+For example, you might have something that looks like this:
+
+[source,java]
+----
+public class MyCustomDsl extends AbstractHttpConfigurer<CorsConfigurerMyCustomDsl, HttpSecurity> {
+	private boolean flag;
+
+	@Override
+	public void init(H http) throws Exception {
+		// any method that adds another configurer
+		// must be done in the init method
+		http.csrf().disable();
+	}
+
+	@Override
+	public void configure(H http) throws Exception {
+		ApplicationContext context = http.getSharedObject(ApplicationContext.class);
+
+		// here we lookup from the ApplicationContext. You can also just create a new instance.
+		MyFilter myFilter = context.getBean(MyFilter.class);
+		myFilter.setFlag(flag);
+		http.addFilterBefore(myFilter, UsernamePasswordAuthenticationFilter.class);
+	}
+
+	public MyCustomDsl flag(boolean value) {
+		this.flag = value;
+		return this;
+	}
+
+	public static MyCustomDsl customDsl() {
+		return new MyCustomDsl();
+	}
+}
+----
+
+NOTE: This is actually how methods like `HttpSecurity.authorizeRequests()` are implemented.
+
+The custom DSL can then be used like this:
+
+[source,java]
+----
+@EnableWebSecurity
+public class Config extends WebSecurityConfigurerAdapter {
+	@Override
+	protected void configure(HttpSecurity http) throws Exception {
+		http
+			.apply(customDsl())
+				.flag(true)
+				.and()
+			...;
+	}
+}
+----
+
+The code is invoked in the following order:
+
+* Code in `Config`s configure method is invoked
+* Code in `MyCustomDsl`s init method is invoked
+* Code in `MyCustomDsl`s configure method is invoked
+
+If you want, you can have `WebSecurityConfiguerAdapter` add `MyCustomDsl` by default by using `SpringFactories`.
+For example, you would create a resource on the classpath named `META-INF/spring.factories` with the following contents:
+
+.META-INF/spring.factories
+----
+org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer = sample.MyCustomDsl
+----
+
+Users wishing to disable the default can do so explicitly.
+
+[source,java]
+----
+@EnableWebSecurity
+public class Config extends WebSecurityConfigurerAdapter {
+	@Override
+	protected void configure(HttpSecurity http) throws Exception {
+		http
+			.apply(customDsl()).disable()
+			...;
+	}
+}
+----
+
 [[ns-config]]
 == Security Namespace Configuration