diff --git a/.github/actions/dispatch.sh b/.github/actions/dispatch.sh
new file mode 100755
index 0000000000..d6c2a37794
--- /dev/null
+++ b/.github/actions/dispatch.sh
@@ -0,0 +1,5 @@
+REPOSITORY_REF="$1"
+TOKEN="$2"
+
+curl -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${TOKEN}" --request POST  --data '{"event_type": "request-build"}' https://api.github.com/repos/${REPOSITORY_REF}/dispatches
+echo "Requested Build for $REPOSITORY_REF"
\ No newline at end of file
diff --git a/.github/workflows/build-reference.yml b/.github/workflows/build-reference.yml
new file mode 100644
index 0000000000..8e7b9ce30c
--- /dev/null
+++ b/.github/workflows/build-reference.yml
@@ -0,0 +1,28 @@
+name: reference
+
+on:
+  push:
+    branches-ignore:
+      - 'gh-pages'
+
+env:
+  GH_TOKEN_DISPATCH: ${{ secrets.GH_TOKEN_DISPATCH }}
+  GH_TOKEN_PUSH: ${{ secrets.GH_TOKEN_PUSH }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v2
+      - name: Generate antora.yml
+        run: ./gradlew :spring-security-docs:generateAntora
+      - name: Push generated antora files to the spring-security-docs-generated
+        uses: JamesIves/github-pages-deploy-action@4.1.4
+        with:
+          branch: "spring-security/main" # The branch the action should deploy to.
+          folder: "docs/build/generateAntora" # The folder the action should deploy.
+          repository-name: "rwinch/spring-security-docs-generated"
+          token: ${{ secrets.GH_TOKEN_PUSH }}
+      - name: Dispatch Build Request
+        run: ${GITHUB_WORKSPACE}/.github/actions/dispatch.sh 'rwinch/spring-reference' "$GH_TOKEN_DISPATCH"
diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle
index fd47234f40..b0555da6c7 100644
--- a/buildSrc/build.gradle
+++ b/buildSrc/build.gradle
@@ -76,13 +76,9 @@ dependencies {
 	implementation 'gradle.plugin.org.gretty:gretty:3.0.1'
 	implementation 'com.apollographql.apollo:apollo-runtime:2.4.5'
 	implementation 'com.github.ben-manes:gradle-versions-plugin:0.38.0'
-	implementation 'io.spring.gradle:docbook-reference-plugin:0.3.1'
 	implementation 'io.spring.gradle:propdeps-plugin:0.0.10.RELEASE'
 	implementation 'io.spring.javaformat:spring-javaformat-gradle-plugin:0.0.15'
 	implementation 'io.spring.nohttp:nohttp-gradle:0.0.10'
-	implementation 'org.aim42:htmlSanityCheck:1.1.6'
-	implementation 'org.asciidoctor:asciidoctor-gradle-jvm:3.1.0'
-	implementation 'org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.1.0'
 	implementation 'org.hidetake:gradle-ssh-plugin:2.10.1'
 	implementation 'org.jfrog.buildinfo:build-info-extractor-gradle:4.9.10'
 	implementation 'org.sonarsource.scanner.gradle:sonarqube-gradle-plugin:2.7.1'
diff --git a/buildSrc/src/main/groovy/io/spring/gradle/convention/DocsPlugin.groovy b/buildSrc/src/main/groovy/io/spring/gradle/convention/DocsPlugin.groovy
index a527d719e6..d0a64ab85b 100644
--- a/buildSrc/src/main/groovy/io/spring/gradle/convention/DocsPlugin.groovy
+++ b/buildSrc/src/main/groovy/io/spring/gradle/convention/DocsPlugin.groovy
@@ -1,12 +1,9 @@
 package io.spring.gradle.convention
 
-import org.aim42.htmlsanitycheck.HtmlSanityCheckPlugin
-import org.aim42.htmlsanitycheck.HtmlSanityCheckTask
-import org.aim42.htmlsanitycheck.check.BrokenHttpLinksChecker
-import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.Task
+import org.gradle.api.plugins.BasePlugin
 import org.gradle.api.plugins.PluginManager
 import org.gradle.api.tasks.bundling.Zip
 
@@ -19,54 +16,18 @@ public class DocsPlugin implements Plugin<Project> {
 	public void apply(Project project) {
 
 		PluginManager pluginManager = project.getPluginManager();
-		pluginManager.apply("org.asciidoctor.jvm.convert");
-		pluginManager.apply("org.asciidoctor.jvm.pdf");
-		pluginManager.apply(AsciidoctorConventionPlugin);
+		pluginManager.apply(BasePlugin);
 		pluginManager.apply(DeployDocsPlugin);
 		pluginManager.apply(JavadocApiPlugin);
-		pluginManager.apply(HtmlSanityCheckPlugin)
-
-		String projectName = Utils.getProjectName(project);
-		String pdfFilename = projectName + "-reference.pdf";
-
-		project.tasks.withType(AbstractAsciidoctorTask) { t ->
-			project.configure(t) {
-				sources {
-					include "**/*.adoc"
-					exclude '_*/**'
-				}
-			}
-		}
-
-		project.tasks.withType(HtmlSanityCheckTask) { HtmlSanityCheckTask t ->
-			project.configure(t) {
-				t.dependsOn 'asciidoctor'
-				t.checkerClasses = [BrokenHttpLinksChecker]
-				t.checkingResultsDir = new File(project.getBuildDir(), "/report/htmlchecks")
-				t.failOnErrors = false
-				t.httpConnectionTimeout = 3000
-				t.sourceDir = new File(project.getBuildDir(), "/docs/asciidoc/")
-				t.sourceDocuments = project.files(new File(project.getBuildDir(), "/docs/asciidoc/index.html"))
-			}
-		}
 
 		Task docsZip = project.tasks.create('docsZip', Zip) {
-			dependsOn 'api', 'asciidoctor'
+			dependsOn 'api'
 			group = 'Distribution'
 			archiveBaseName = project.rootProject.name
 			archiveClassifier = 'docs'
 			description = "Builds -${classifier} archive containing all " +
 				"Docs for deployment at docs.spring.io"
 
-			from(project.tasks.asciidoctor.outputs) {
-				into 'reference/html5'
-				include '**'
-			}
-			from(project.tasks.asciidoctorPdf.outputs) {
-				into 'reference/pdf'
-				include '**'
-				rename "index.pdf", pdfFilename
-			}
 			from(project.tasks.api.outputs) {
 				into 'api'
 			}
diff --git a/buildSrc/src/main/java/io/spring/gradle/convention/AsciidoctorConventionPlugin.java b/buildSrc/src/main/java/io/spring/gradle/convention/AsciidoctorConventionPlugin.java
deleted file mode 100644
index 548dfbca51..0000000000
--- a/buildSrc/src/main/java/io/spring/gradle/convention/AsciidoctorConventionPlugin.java
+++ /dev/null
@@ -1,208 +0,0 @@
-/*
- * Copyright 2019-2020 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package io.spring.gradle.convention;
-
-import org.asciidoctor.gradle.base.AsciidoctorAttributeProvider;
-import org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask;
-import org.asciidoctor.gradle.jvm.AsciidoctorJExtension;
-import org.asciidoctor.gradle.jvm.AsciidoctorJPlugin;
-import org.asciidoctor.gradle.jvm.AsciidoctorTask;
-import org.gradle.api.Action;
-import org.gradle.api.Plugin;
-import org.gradle.api.Project;
-import org.gradle.api.artifacts.Configuration;
-import org.gradle.api.artifacts.DependencySet;
-import org.gradle.api.artifacts.dsl.RepositoryHandler;
-import org.gradle.api.file.CopySpec;
-import org.gradle.api.file.FileTree;
-import org.gradle.api.tasks.Sync;
-
-import java.io.File;
-import java.net.URI;
-import java.time.LocalDate;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.Callable;
-import java.util.function.Consumer;
-
-/**
- * Conventions that are applied in the presence of the {@link AsciidoctorJPlugin}. When
- * the plugin is applied:
- *
- * <ul>
- * <li>All warnings are made fatal.
- * <li>A task is created to resolve and unzip our documentation resources (CSS and
- * Javascript).
- * <li>For each {@link AsciidoctorTask} (HTML only):
- * <ul>
- * <li>A configuration named asciidoctorExtensions is ued to add the
- * <a href="https://github.com/spring-io/spring-asciidoctor-extensions#block-switch">block
- * switch</a> extension
- * <li>{@code doctype} {@link AsciidoctorTask#options(Map) option} is configured.
- * <li>{@link AsciidoctorTask#attributes(Map) Attributes} are configured for syntax
- * highlighting, CSS styling, docinfo, etc.
- * </ul>
- * <li>For each {@link AbstractAsciidoctorTask} (HTML and PDF):
- * <ul>
- * <li>{@link AsciidoctorTask#attributes(Map) Attributes} are configured to enable
- * warnings for references to missing attributes, the year is added as @{code today-year},
- * etc
- * <li>{@link AbstractAsciidoctorTask#baseDirFollowsSourceDir() baseDirFollowsSourceDir()}
- * is enabled.
- * </ul>
- * </ul>
- *
- * @author Andy Wilkinson
- * @author Rob Winch
- */
-public class AsciidoctorConventionPlugin implements Plugin<Project> {
-
-	public void apply(Project project) {
-		project.getPlugins().withType(AsciidoctorJPlugin.class, (asciidoctorPlugin) -> {
-			createDefaultAsciidoctorRepository(project);
-			makeAllWarningsFatal(project);
-			Sync unzipResources = createUnzipDocumentationResourcesTask(project);
-			project.getTasks().withType(AbstractAsciidoctorTask.class, (asciidoctorTask) -> {
-				asciidoctorTask.dependsOn(unzipResources);
-				configureExtensions(project, asciidoctorTask);
-				configureCommonAttributes(project, asciidoctorTask);
-				configureOptions(asciidoctorTask);
-				asciidoctorTask.baseDirFollowsSourceDir();
-				asciidoctorTask.useIntermediateWorkDir();
-				asciidoctorTask.resources(new Action<CopySpec>() {
-					@Override
-					public void execute(CopySpec resourcesSpec) {
-						resourcesSpec.from(unzipResources);
-						resourcesSpec.from(asciidoctorTask.getSourceDir(), new Action<CopySpec>() {
-							@Override
-							public void execute(CopySpec resourcesSrcDirSpec) {
-								// https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/523
-								// For now copy the entire sourceDir over so that include files are
-								// available in the intermediateWorkDir
-								// resourcesSrcDirSpec.include("images/**");
-							}
-						});
-					}
-				});
-				if (asciidoctorTask instanceof AsciidoctorTask) {
-					configureHtmlOnlyAttributes(project, asciidoctorTask);
-				}
-			});
-		});
-	}
-
-	private void createDefaultAsciidoctorRepository(Project project) {
-		project.getGradle().afterProject(new Action<Project>() {
-			@Override
-			public void execute(Project project) {
-				RepositoryHandler repositories = project.getRepositories();
-				if (repositories.isEmpty()) {
-					repositories.mavenCentral();
-					repositories.maven(repo -> {
-						repo.setUrl(URI.create("https://repo.spring.io/release"));
-					});
-				}
-			}
-		});
-	}
-
-	private void makeAllWarningsFatal(Project project) {
-		project.getExtensions().getByType(AsciidoctorJExtension.class).fatalWarnings(".*");
-	}
-
-	private void configureExtensions(Project project, AbstractAsciidoctorTask asciidoctorTask) {
-		Configuration extensionsConfiguration = project.getConfigurations().maybeCreate("asciidoctorExtensions");
-		extensionsConfiguration.defaultDependencies(new Action<DependencySet>() {
-			@Override
-			public void execute(DependencySet dependencies) {
-				dependencies.add(project.getDependencies().create("io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch:0.4.2.RELEASE"));
-			}
-		});
-		asciidoctorTask.configurations(extensionsConfiguration);
-	}
-
-	private Sync createUnzipDocumentationResourcesTask(Project project) {
-		Configuration documentationResources = project.getConfigurations().maybeCreate("documentationResources");
-		documentationResources.getDependencies()
-				.add(project.getDependencies().create("io.spring.docresources:spring-doc-resources:0.2.5"));
-		Sync unzipResources = project.getTasks().create("unzipDocumentationResources",
-				Sync.class, new Action<Sync>() {
-					@Override
-			public void execute(Sync sync) {
-				sync.dependsOn(documentationResources);
-				sync.from(new Callable<List<FileTree>>() {
-					@Override
-					public List<FileTree> call() throws Exception {
-						List<FileTree> result = new ArrayList<>();
-						documentationResources.getAsFileTree().forEach(new Consumer<File>() {
-							@Override
-							public void accept(File file) {
-								result.add(project.zipTree(file));
-							}
-						});
-						return result;
-					}
-				});
-				File destination = new File(project.getBuildDir(), "docs/resources");
-				sync.into(project.relativePath(destination));
-			}
-		});
-		return unzipResources;
-	}
-
-	private void configureOptions(AbstractAsciidoctorTask asciidoctorTask) {
-		asciidoctorTask.options(Collections.singletonMap("doctype", "book"));
-	}
-
-	private void configureHtmlOnlyAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask) {
-		Map<String, Object> attributes = new HashMap<>();
-		attributes.put("source-highlighter", "highlight.js");
-		attributes.put("highlightjsdir", "js/highlight");
-		attributes.put("highlightjs-theme", "github");
-		attributes.put("linkcss", true);
-		attributes.put("icons", "font");
-		attributes.put("stylesheet", "css/spring.css");
-		asciidoctorTask.getAttributeProviders().add(new AsciidoctorAttributeProvider() {
-			@Override
-			public Map<String, Object> getAttributes() {
-				Object version = project.getVersion();
-				Map<String, Object> attrs = new HashMap<>();
-				if (version != null && version.toString() != Project.DEFAULT_VERSION) {
-					attrs.put("revnumber", version);
-				}
-				return attrs;
-			}
-		});
-		asciidoctorTask.attributes(attributes);
-	}
-
-	private void configureCommonAttributes(Project project, AbstractAsciidoctorTask asciidoctorTask) {
-		Map<String, Object> attributes = new HashMap<>();
-		attributes.put("attribute-missing", "warn");
-		attributes.put("icons", "font");
-		attributes.put("idprefix", "");
-		attributes.put("idseparator", "-");
-		attributes.put("docinfo", "shared");
-		attributes.put("sectanchors", "");
-		attributes.put("sectnums", "");
-		attributes.put("today-year", LocalDate.now().getYear());
-		asciidoctorTask.attributes(attributes);
-	}
-}
diff --git a/buildSrc/src/test/java/io/spring/gradle/convention/DocsPluginITest.java b/buildSrc/src/test/java/io/spring/gradle/convention/DocsPluginITest.java
deleted file mode 100644
index badd126a82..0000000000
--- a/buildSrc/src/test/java/io/spring/gradle/convention/DocsPluginITest.java
+++ /dev/null
@@ -1,87 +0,0 @@
-package io.spring.gradle.convention;
-
-import io.spring.gradle.TestKit;
-import org.codehaus.groovy.runtime.ResourceGroovyMethods;
-import org.gradle.testkit.runner.BuildResult;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.io.TempDir;
-
-import java.io.File;
-import java.nio.file.Path;
-import java.util.Collections;
-import java.util.List;
-import java.util.zip.ZipEntry;
-import java.util.zip.ZipFile;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.gradle.testkit.runner.TaskOutcome.FAILED;
-import static org.gradle.testkit.runner.TaskOutcome.SUCCESS;
-
-public class DocsPluginITest {
-	private TestKit testKit;
-
-	@BeforeEach
-	void setup(@TempDir Path tempDir) {
-		this.testKit = new TestKit(tempDir.toFile());
-	}
-
-	@Test
-	public void buildTriggersDocs() throws Exception {
-		BuildResult result = testKit.withProjectResource("samples/docs/simple/")
-				.withArguments("build")
-				.build();
-		assertThat(result.task(":build").getOutcome()).isEqualTo(SUCCESS);
-		assertThat(result.task(":docs").getOutcome()).isEqualTo(SUCCESS);
-		assertThat(result.task(":docsZip").getOutcome()).isEqualTo(SUCCESS);
-		File zip = new File(testKit.getRootDir(), "build/distributions/simple-1.0.0.BUILD-SNAPSHOT-docs.zip");
-		try (ZipFile file = new ZipFile(zip)) {
-			List<? extends ZipEntry> entries = Collections.list(file.entries());
-			assertThat(entries)
-					.extracting(ZipEntry::getName)
-					.contains("docs/reference/html5/index.html")
-					.contains("docs/reference/pdf/simple-reference.pdf");
-		}
-	}
-
-	@Test
-	public void asciidocCopiesImages() throws Exception {
-		BuildResult result = testKit.withProjectResource("samples/docs/simple/").withArguments("asciidoctor").build();
-		assertThat(result.task(":asciidoctor").getOutcome()).isEqualTo(SUCCESS);
-		assertThat(new File(testKit.getRootDir(), "build/docs/asciidoc/images")).exists();
-	}
-
-	@Test
-	public void asciidocDocInfoFromResourcesUsed() throws Exception {
-		BuildResult result = this.testKit.withProjectResource("samples/docs/simple/")
-				.withArguments("asciidoctor")
-				.build();
-		assertThat(result.task(":asciidoctor").getOutcome()).isEqualTo(SUCCESS);
-		assertThat(ResourceGroovyMethods.getText(new File(testKit.getRootDir(), "build/docs/asciidoc/index.html")))
-				.contains("<script type=\"text/javascript\" src=\"js/tocbot/tocbot.min.js\"></script>");
-	}
-
-	@Test
-	public void missingAttributeFails() throws Exception {
-		BuildResult result = this.testKit.withProjectResource("samples/docs/missing-attribute/")
-				.withArguments(":asciidoctor")
-				.buildAndFail();
-		assertThat(result.task(":asciidoctor").getOutcome()).isEqualTo(FAILED);
-	}
-
-	@Test
-	public void missingInclude() throws Exception {
-		BuildResult result = this.testKit.withProjectResource("samples/docs/missing-include/")
-				.withArguments(":asciidoctor")
-				.buildAndFail();
-		assertThat(result.task(":asciidoctor").getOutcome()).isEqualTo(FAILED);
-	}
-
-	@Test
-	public void missingCrossReference() throws Exception {
-		BuildResult result = this.testKit.withProjectResource("samples/docs/missing-cross-reference/")
-				.withArguments(":asciidoctor")
-				.buildAndFail();
-		assertThat(result.task(":asciidoctor").getOutcome()).isEqualTo(FAILED);
-	}
-}
diff --git a/buildSrc/src/test/resources/samples/docs/missing-attribute/build.gradle b/buildSrc/src/test/resources/samples/docs/missing-attribute/build.gradle
deleted file mode 100644
index 91d6d7e151..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-attribute/build.gradle
+++ /dev/null
@@ -1,6 +0,0 @@
-plugins {
-	id 'io.spring.convention.docs'
-	id 'java'
-}
-
-version = '1.0.0.BUILD-SNAPSHOT'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-attribute/settings.gradle b/buildSrc/src/test/resources/samples/docs/missing-attribute/settings.gradle
deleted file mode 100644
index 7378d4a349..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-attribute/settings.gradle
+++ /dev/null
@@ -1 +0,0 @@
-rootProject.name = 'simple'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-attribute/src/docs/asciidoc/index.adoc b/buildSrc/src/test/resources/samples/docs/missing-attribute/src/docs/asciidoc/index.adoc
deleted file mode 100644
index ba2fbbe84b..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-attribute/src/docs/asciidoc/index.adoc
+++ /dev/null
@@ -1,3 +0,0 @@
-= Example Manual
-
-This will fail due to {missing} attribute
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/build.gradle b/buildSrc/src/test/resources/samples/docs/missing-cross-reference/build.gradle
deleted file mode 100644
index 91d6d7e151..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/build.gradle
+++ /dev/null
@@ -1,6 +0,0 @@
-plugins {
-	id 'io.spring.convention.docs'
-	id 'java'
-}
-
-version = '1.0.0.BUILD-SNAPSHOT'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/settings.gradle b/buildSrc/src/test/resources/samples/docs/missing-cross-reference/settings.gradle
deleted file mode 100644
index 1731930901..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/settings.gradle
+++ /dev/null
@@ -1 +0,0 @@
-rootProject.name = 'missing-include'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/src/docs/asciidoc/index.adoc b/buildSrc/src/test/resources/samples/docs/missing-cross-reference/src/docs/asciidoc/index.adoc
deleted file mode 100644
index 2a41dd8a8c..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-cross-reference/src/docs/asciidoc/index.adoc
+++ /dev/null
@@ -1,3 +0,0 @@
-= Example Manual
-
-This will fail due to <<missing>> cross reference
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-include/build.gradle b/buildSrc/src/test/resources/samples/docs/missing-include/build.gradle
deleted file mode 100644
index 91d6d7e151..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-include/build.gradle
+++ /dev/null
@@ -1,6 +0,0 @@
-plugins {
-	id 'io.spring.convention.docs'
-	id 'java'
-}
-
-version = '1.0.0.BUILD-SNAPSHOT'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-include/settings.gradle b/buildSrc/src/test/resources/samples/docs/missing-include/settings.gradle
deleted file mode 100644
index 1731930901..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-include/settings.gradle
+++ /dev/null
@@ -1 +0,0 @@
-rootProject.name = 'missing-include'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/missing-include/src/docs/asciidoc/index.adoc b/buildSrc/src/test/resources/samples/docs/missing-include/src/docs/asciidoc/index.adoc
deleted file mode 100644
index ecf2133e9a..0000000000
--- a/buildSrc/src/test/resources/samples/docs/missing-include/src/docs/asciidoc/index.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-= Example Manual
-
-This will fail due to missing include
-
-include::missing.adoc[]
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/simple/build.gradle b/buildSrc/src/test/resources/samples/docs/simple/build.gradle
deleted file mode 100644
index 9deefc7e1a..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/build.gradle
+++ /dev/null
@@ -1,13 +0,0 @@
-plugins {
-	id 'io.spring.convention.docs'
-	id 'java'
-}
-
-version = '1.0.0.BUILD-SNAPSHOT'
-
-asciidoctorj {
-	attributes \
-		'build-gradle': project.buildFile,
-		'sourcedir': project.sourceSets.main.java.srcDirs[0],
-		'endpoint-url': 'https://example.org'
-}
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/simple/settings.gradle b/buildSrc/src/test/resources/samples/docs/simple/settings.gradle
deleted file mode 100644
index 7378d4a349..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/settings.gradle
+++ /dev/null
@@ -1 +0,0 @@
-rootProject.name = 'simple'
\ No newline at end of file
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/docinfo.html b/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/docinfo.html
deleted file mode 100644
index f399886516..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/docinfo.html
+++ /dev/null
@@ -1 +0,0 @@
-<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.js"></script>
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/images/sunset.jpg b/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/images/sunset.jpg
deleted file mode 100644
index 48c9129b30..0000000000
Binary files a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/images/sunset.jpg and /dev/null differ
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/index.adoc b/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/index.adoc
deleted file mode 100644
index ea4087750a..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/index.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= Example Manual
-Doc Writer <doc.writer@example.org>
-2014-09-09
-:example-caption!:
-ifndef::imagesdir[:imagesdir: images]
-ifndef::sourcedir[:sourcedir: ../java]
-
-This is a user manual for an example project.
-
-== Introduction
-
-This project does something.
-We just haven't decided what that is yet.
-
-== Source Code
-
-[source,java]
-.Java code from project
-----
-include::{sourcedir}/example/StringUtils.java[tags=contains,indent=0]
-----
-
-This page was built by the following command:
-
- $ ./gradlew asciidoctor
-
-== Images
-
-[.thumb]
-image::sunset.jpg[scaledwidth=75%]
-
-== Attributes
-
-.Built-in
-asciidoctor-version:: {asciidoctor-version}
-safe-mode-name:: {safe-mode-name}
-docdir:: {docdir}
-docfile:: {docfile}
-imagesdir:: {imagesdir}
-revnumber:: {revnumber}
-
-.Custom
-sourcedir:: {sourcedir}
-endpoint-url:: {endpoint-url}
-
-== Includes
-
-.include::subdir/_b.adoc[]
-====
-include::subdir/_b.adoc[]
-====
-
-WARNING: Includes can be tricky!
-
-== build.gradle
-
-[source,groovy]
-----
-include::{build-gradle}[]
-----
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_b.adoc b/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_b.adoc
deleted file mode 100644
index 422eb5ee04..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_b.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-content from _src/docs/asciidoc/subdir/_b.adoc_.
-
-.include::_c.adoc[]
-[example]
---
-include::_c.adoc[]
---
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_c.adoc b/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_c.adoc
deleted file mode 100644
index 3aca173636..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/src/docs/asciidoc/subdir/_c.adoc
+++ /dev/null
@@ -1 +0,0 @@
-content from _src/docs/asciidoc/subdir/c.adoc_.
diff --git a/buildSrc/src/test/resources/samples/docs/simple/src/main/java/example/StringUtils.java b/buildSrc/src/test/resources/samples/docs/simple/src/main/java/example/StringUtils.java
deleted file mode 100644
index 3884f862bb..0000000000
--- a/buildSrc/src/test/resources/samples/docs/simple/src/main/java/example/StringUtils.java
+++ /dev/null
@@ -1,9 +0,0 @@
-package example;
-
-public class StringUtils {
-    // tag::contains[]
-    public boolean contains(String haystack, String needle) {
-        return haystack.contains(needle);
-    }
-    // end::contains[]
-}
diff --git a/buildSrc/src/test/resources/samples/showcase/sgbcs-docs/sgbcs-docs.gradle b/buildSrc/src/test/resources/samples/showcase/sgbcs-docs/sgbcs-docs.gradle
index f3d52b8c1f..88d66263de 100644
--- a/buildSrc/src/test/resources/samples/showcase/sgbcs-docs/sgbcs-docs.gradle
+++ b/buildSrc/src/test/resources/samples/showcase/sgbcs-docs/sgbcs-docs.gradle
@@ -2,10 +2,3 @@ apply plugin: 'java'
 apply plugin: 'io.spring.convention.docs'
 
 version = "1.0.0.BUILD-SNAPSHOT"
-
-asciidoctorj {
-	attributes \
-		'build-gradle': project.buildFile,
-		'sourcedir': project.sourceSets.main.java.srcDirs[0],
-		'endpoint-url': 'https://example.org'
-}
\ No newline at end of file
diff --git a/docs/antora.yml b/docs/antora.yml
new file mode 100644
index 0000000000..2519066807
--- /dev/null
+++ b/docs/antora.yml
@@ -0,0 +1,7 @@
+name: ''
+title: Spring Security
+version: ~
+display_version: 5.6
+start_page: ROOT:index.adoc
+nav:
+- modules/ROOT/nav.adoc
diff --git a/docs/guides/spring-security-docs-guides.gradle b/docs/guides/spring-security-docs-guides.gradle
deleted file mode 100644
index bce20f0081..0000000000
--- a/docs/guides/spring-security-docs-guides.gradle
+++ /dev/null
@@ -1,40 +0,0 @@
-apply plugin: 'org.asciidoctor.jvm.convert'
-apply plugin: 'io.spring.convention.repository'
-
-asciidoctor {
-	baseDir = file('src/docs/asciidoc')
-	options eruby: 'erubis'
-
-	def ghSamplesUrl = "https://github.com/spring-projects/spring-security-samples/tree/$samplesBranch"
-	attributes copycss : '',
-			icons : 'font',
-			'source-highlighter': 'prettify',
-			sectanchors : '',
-			toc: '',
-			'toc-placement' : 'preamble',
-			idprefix: '',
-			idseparator: '-',
-			doctype: 'book',
-			'spring-security-version' : project.version,
-			'include-maven-repository' : getMavenRepositoryInclude(),
-			revnumber : project.version,
-			'gh-samples-url': ghSamplesUrl,
-			'gh-old-samples-url': "https://github.com/spring-projects/spring-security/tree/5.4.x/samples"
-}
-
-ext.spec = copySpec {
-	into ('guides') {
-		from(asciidoctor.outputDir)
-		exclude 'build', 'Guardfile'
-	}
-}
-
-def getMavenRepositoryInclude() {
-	if(snapshotBuild) {
-		return "_includes/maven-repository-snapshot.asc"
-	} else if(releaseBuild) {
-		return "_includes/maven-repository-release.asc"
-	} else {
-		return "_includes/maven-repository-milestone.asc"
-	}
-}
diff --git a/docs/guides/src/docs/asciidoc/Guardfile b/docs/guides/src/docs/asciidoc/Guardfile
deleted file mode 100644
index 1075c0114c..0000000000
--- a/docs/guides/src/docs/asciidoc/Guardfile
+++ /dev/null
@@ -1,15 +0,0 @@
-require 'asciidoctor'
-require 'erb'
-
-guard 'shell' do
-  watch(/^.*\.asc$/) {|m|
-    Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'toc' => '', 'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'toc-placement' => 'preamble', 'revnumber' => '3.2.0.CI-SNAPSHOT',
-     'spring-security-version' => '3.2.0.CI-SNAPSHOT',
-     'download-url' => 'https://github.com/spring-projects/spring-security/archive/main.zip',
-     'include-maven-repository' => '_includes/maven-repository-snapshot.asc' })
-  }
-end
-
-guard 'livereload' do
-  watch(%r{build/.+\.(css|js|html)$})
-end
diff --git a/docs/guides/src/docs/asciidoc/_form-includes/verify-app.asc b/docs/guides/src/docs/asciidoc/_form-includes/verify-app.asc
deleted file mode 100644
index c8127c2c7a..0000000000
--- a/docs/guides/src/docs/asciidoc/_form-includes/verify-app.asc
+++ /dev/null
@@ -1,6 +0,0 @@
-Verify the application is working:
-
-* Navigate to http://localhost:8080/sample/ You should see a login form
-* Enter the *username* _user_, the *password* _password_, and click the *Login* button. You should now see the main application.
-* Try clicking on the Compose link and creating a message. The message details should be displayed.
-* Now click on the Inbox link and see the message listed. You can click on the summary link to see the details displayed again.
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-boot.asc b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-boot.asc
deleted file mode 100644
index b786261c20..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-boot.asc
+++ /dev/null
@@ -1,21 +0,0 @@
-=== Exploring the secured application
-
-Start the application as we did in <<running-the-{starter-appname}-application>>
-
-Navigate to http://localhost:8080/ and click on the *_secured pages_* link and you will be prompted to login.
-
-==== Authenticating to the secured application
-
-Try entering an invalid username and password:
-
-* *Username* _invalid_
-* *Password* _invalid_
-
-You should see an error message stating that authentication failed. Now try entering a valid username and password:
-
-* *Username* _user_
-* *Password* _password_
-
-You should now see the page that we wanted to secure.
-
-NOTE: The reason we can successfully authenticate with *Username* _user_ and *Password* _password_ is because that is what we configured in our <<security-config-java,SecurityConfig>>.
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-javaconfig.asc b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-javaconfig.asc
deleted file mode 100644
index fbdaf4b272..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-javaconfig.asc
+++ /dev/null
@@ -1,19 +0,0 @@
-=== Exploring the secured application
-
-Start the server as we did in <<running-the-{starter-appname}-application>> Now when you visit http://localhost:8080/sample/ you will be prompted with a login page that is automatically generated by Spring Security.
-
-==== Authenticating to the secured application
-
-Try entering an invalid username and password:
-
-* *Username* _invalid_
-* *Password* _invalid_
-
-You should see an error message stating that authentication failed. Now try entering a valid username and password:
-
-* *Username* _user_
-* *Password* _password_
-
-You should now see the page that we wanted to secure.
-
-NOTE: The reason we can successfully authenticate with *Username* _user_ and *Password* _password_ is because that is what we configured in our <<security-config-java,SecurityConfig>>.
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc b/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc
deleted file mode 100644
index b8c6d971fe..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/exploring-the-secured-application-xml.asc
+++ /dev/null
@@ -1,19 +0,0 @@
-=== Exploring the secured application
-
-Start the server as we did in <<running-the-{starter-appname}-application>> Now when you visit http://localhost:8080/sample/ you will be prompted with a login page that is automatically generated by Spring Security.
-
-==== Authenticating to the secured application
-
-Try entering an invalid username and password:
-
-* *Username* _invalid_
-* *Password* _invalid_
-
-You should see an error message stating that authentication failed. Now try entering a valid username and password:
-
-* *Username* _user_
-* *Password* _password_
-
-You should now see the page that we wanted to secure.
-
-NOTE: The reason we can successfully authenticate with *Username* _user_ and *Password* _password_ is because that is what we configured in our <<security-config-xml,security-config-xml>>.
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-boot.asc b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-boot.asc
deleted file mode 100644
index 5d2c63dcbe..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-boot.asc
+++ /dev/null
@@ -1,118 +0,0 @@
-== Securing the application
-
-Before securing the application, it is important to ensure that the existing application works as we did in <<running-the-{starter-appname}-application>>. Now that the application runs without security, we are ready to add security to our application. This section demonstrates the minimal steps to add Spring Security to our application.
-
-=== Updating your dependencies
-
-include::../{include-maven-repository}[]
-
-In order to use Spring Security you must add the necessary dependencies. For the sample we will add the following Spring Security dependencies:
-
-.pom.xml
-[source,xml]
-[subs="verbatim,attributes"]
-----
-<dependencies>
-  <!-- ... other dependency elements ... -->
-  <dependency>
-	<groupId>org.springframework.security</groupId>
-	<artifactId>spring-security-web</artifactId>
-	<version>{spring-security-version}</version>
-  </dependency>
-  <dependency>
-	<groupId>org.springframework.security</groupId>
-	<artifactId>spring-security-config</artifactId>
-	<version>{spring-security-version}</version>
-  </dependency>
-  <dependency>
-	<groupId>org.thymeleaf.extras</groupId>
-	<artifactId>thymeleaf-extras-springsecurity5</artifactId>	<1>
-	<version>2.1.2.RELEASE</version>
-  </dependency>
-</dependencies>
-----
-
-<1> We are using https://www.thymeleaf.org/[Thymeleaf] for our view template engine
-and need to add an additional dependency for the https://github.com/thymeleaf/thymeleaf-extras-springsecurity[Thymeleaf - Spring Security integration module].
-
-After you have completed this, you need to ensure that STS knows about the updated dependencies by:
-
-* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application
-* Select *Maven->Update project...*
-* Ensure the project is selected, and click *OK*
-
-=== Creating your Spring Security configuration
-
-The next step is to create a Spring Security configuration.
-
-* Right click the _spring-security-samples-{starter-config-type}-{starter-appname}_ project in the Package Explorer view
-* Select *New->Class*
-* Enter _org.springframework.security.samples.config_ for the *Package*
-* Enter _SecurityConfig_ for the *Name*
-* Click *Finish*
-* Replace the file with the following contents:
-
-[[security-config-java]]
-.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
-[source,java]
-----
-package org.springframework.security.samples.config;
-
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
-import org.springframework.security.config.annotation.web.builders.HttpSecurity;
-import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
-import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
-
-@EnableWebSecurity
-public class SecurityConfig extends WebSecurityConfigurerAdapter {
-
-	@Override
-	protected void configure(HttpSecurity http) throws Exception {
-		http
-			.authorizeRequests()
-				.antMatchers("/css/**", "/index").permitAll()		<1>
-				.antMatchers("/user/**").hasRole("USER")			<2>
-				.and()
-			.formLogin()
-				.loginPage("/login").failureUrl("/login-error");	<3>
-	}
-
-	@Autowired
-	public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
-		auth
-			.inMemoryAuthentication()
-				.withUser("user").password("password").roles("USER");
-	}
-}
-----
-
-<1> requests matched against _/css/**_ and _/index_ are fully accessible
-<2> requests matched against _/user/**_ require a user to be authenticated and must be associated to the _USER_ role
-<3> form-based authentication is enabled with a custom login page and failure url
-
-
-NOTE: The name of the configureGlobal method is not important. However, it is important to only configure AuthenticationManagerBuilder in a class annotated with either `@EnableWebSecurity`, `@EnableGlobalMethodSecurity`, or `@EnableGlobalAuthentication`. Doing otherwise has unpredictable results.
-
-[[servlet-api-integration]]
-The <<security-config-java,SecurityConfig>> will:
-
-* Require authentication to requests matched against _/user/**_
-* Specifies the URL to send users to for form-based login
-* Allow the user with the *Username* _user_ and the *Password* _password_ to authenticate with form based authentication
-* Allow the user to logout
-* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention
-* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection
-* Security Header integration
-** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests
-** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration
-** Cache Control (can be overridden later by your application to allow caching of your static resources)
-** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration
-** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking]
-* Integrate with the following Servlet API methods
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest#getRemoteUser()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.html#getUserPrincipal()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.html#isUserInRole(java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[HttpServletRequest.html#login(java.lang.String, java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[HttpServletRequest.html#logout()]
-
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc
deleted file mode 100644
index 7dc183a393..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-javaconfig.asc
+++ /dev/null
@@ -1,92 +0,0 @@
-== Securing the application
-
-Before securing your application, it is important to ensure that the existing application works as we did in <<running-the-{starter-appname}-application>>. Now that the application runs without security, we are ready to add security to our application. This section demonstrates the minimal steps to add Spring Security to our application.
-
-=== Updating your dependencies
-
-include::../{include-maven-repository}[]
-
-In order to use Spring Security you must add the necessary dependencies. For the sample we will add the following Spring Security dependencies:
-
-.pom.xml
-[source,xml]
-[subs="verbatim,attributes"]
-----
-<dependencies>
-  <!-- ... other dependency elements ... -->
-  <dependency>
-    <groupId>org.springframework.security</groupId>
-    <artifactId>spring-security-web</artifactId>
-    <version>{spring-security-version}</version>
-  </dependency>
-  <dependency>
-    <groupId>org.springframework.security</groupId>
-    <artifactId>spring-security-config</artifactId>
-    <version>{spring-security-version}</version>
-  </dependency>
-</dependencies>
-----
-
-After you have completed this, you need to ensure that STS knows about the updated dependencies by:
-
-* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application
-* Select *Maven->Update project...*
-* Ensure the project is selected, and click *OK*
-
-=== Creating your Spring Security configuration
-
-The next step is to create a Spring Security configuration.
-
-* Right click the _spring-security-samples-{starter-config-type}-{starter-appname}_ project in the Package Explorer view
-* Select *New->Class*
-* Enter _org.springframework.security.samples.config_ for the *Package*
-* Enter _SecurityConfig_ for the *Name*
-* Click *Finish*
-* Replace the file with the following contents:
-
-[[security-config-java]]
-.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
-[source,java]
-----
-package org.springframework.security.samples.config;
-
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
-import org.springframework.security.config.annotation.web.configuration.*;
-
-@EnableWebSecurity
-public class SecurityConfig {
-
-    @Autowired
-    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
-        auth
-            .inMemoryAuthentication()
-                .withUser("user").password("password").roles("USER");
-    }
-}
-----
-
-NOTE: The name of the configureGlobal method is not important. However, it is important to only configure AuthenticationManagerBuilder in a class annotated with either `@EnableWebSecurity`, `@EnableGlobalMethodSecurity`, or `@EnableGlobalAuthentication`. Doing otherwise has unpredictable results.
-
-[[servlet-api-integration]]
-The <<security-config-java,SecurityConfig>> will:
-
-* Require authentication to every URL in your application
-* Generate a login form for you
-* Allow the user with the *Username* _user_ and the *Password* _password_ to authenticate with form based authentication
-* Allow the user to logout
-* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention
-* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection
-* Security Header integration
-** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests
-** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration
-** Cache Control (can be overridden later by your application to allow caching of your static resources)
-** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration
-** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking]
-* Integrate with the following Servlet API methods
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest#getRemoteUser()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.html#getUserPrincipal()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.html#isUserInRole(java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[HttpServletRequest.html#login(java.lang.String, java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[HttpServletRequest.html#logout()]
-
diff --git a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc b/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc
deleted file mode 100644
index 0d47daf040..0000000000
--- a/docs/guides/src/docs/asciidoc/_hello-includes/secure-the-application-xml.asc
+++ /dev/null
@@ -1,89 +0,0 @@
-== Securing the application
-
-Before securing your application, it is important to ensure that the existing application works as we did in <<running-the-{starter-appname}-application>>. Now that the application runs without security, we are ready to add security to our application. This section demonstrates the minimal steps to add Spring Security to our application.
-
-=== Updating your dependencies
-
-include::../{include-maven-repository}[]
-
-In order to use Spring Security you must add the necessary dependencies. For the sample we will add the following Spring Security dependencies:
-
-.pom.xml
-[source,xml]
-[subs="verbatim,attributes"]
-----
-<dependencies>
-  <!-- ... other dependency elements ... -->
-  <dependency>
-    <groupId>org.springframework.security</groupId>
-    <artifactId>spring-security-web</artifactId>
-    <version>{spring-security-version}</version>
-  </dependency>
-  <dependency>
-    <groupId>org.springframework.security</groupId>
-    <artifactId>spring-security-config</artifactId>
-    <version>{spring-security-version}</version>
-  </dependency>
-</dependencies>
-----
-
-After you have completed this, you need to ensure that STS knows about the updated dependencies by:
-
-* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application
-* Select *Maven->Update project...*
-* Ensure the project is selected, and click *OK*
-
-=== Creating your Spring Security configuration
-
-The next step is to create a Spring Security configuration.
-
-* In the Package Explorer view, right click on the folder _src/main/webapp_
-* Select *New->Folder*
-* Enter _WEB-INF/spring_ for the *Folder name*
-* Then right click on the new folder _WEB-INF/spring_
-* Select *New->File*
-* Enter _security.xml_ for the *File name*
-* Click *Finish*
-* Replace the contents of the file with the following:
-
-[[security-config-xml]]
-.src/main/webapp/WEB-INF/spring/security.xml
-[source,xml]
-----
-<b:beans xmlns="http://www.springframework.org/schema/security"
-		 xmlns:b="http://www.springframework.org/schema/beans"
-		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-		 xsi:schemaLocation="http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
-						http://www.springframework.org/schema/security https://www.springframework.org/schema/security/spring-security.xsd">
-
-	<http />
-
-	<user-service>
-		<user name="user" password="password" authorities="ROLE_USER" />
-	</user-service>
-
-</b:beans>
-----
-
-[[servlet-api-integration]]
-The <<security-config-xml,security-config-xml>> will:
-
-* Require authentication to every URL in your application
-* Generate a login form for you
-* Allow the user with the *Username* _user_ and the *Password* _password_ to authenticate with form based authentication
-* Allow the user to logout
-* https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attack] prevention
-* https://en.wikipedia.org/wiki/Session_fixation[Session Fixation] protection
-* Security Header integration
-** https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security[HTTP Strict Transport Security] for secure requests
-** https://msdn.microsoft.com/en-us/library/ie/gg622941(v=vs.85).aspx[X-Content-Type-Options] integration
-** Cache Control (can be overridden later by your application to allow caching of your static resources)
-** https://msdn.microsoft.com/en-us/library/dd565647(v=vs.85).aspx[X-XSS-Protection] integration
-** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking]
-* Integrate with the following Servlet API methods
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest#getRemoteUser()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.html#getUserPrincipal()]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.html#isUserInRole(java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[HttpServletRequest.html#login(java.lang.String, java.lang.String)]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[HttpServletRequest.html#logout()]
-
diff --git a/docs/guides/src/docs/asciidoc/_includes/maven-repository-milestone.asc b/docs/guides/src/docs/asciidoc/_includes/maven-repository-milestone.asc
deleted file mode 100644
index 9414018722..0000000000
--- a/docs/guides/src/docs/asciidoc/_includes/maven-repository-milestone.asc
+++ /dev/null
@@ -1,14 +0,0 @@
-In order to resolve Spring Security milestones and release candidates add the Spring Milestone repository. For our example, the repository has already been added for you. In the event you were working on another application, you would need to ensure you add the following to your pom:
-
-.pom.xml
-[source,xml]
-----
-<repositories>
-  <!-- ... possibly other repository elements ... -->
-  <repository>
-    <id>spring-milestone</id>
-    <name>Spring Milestone Repository</name>
-    <url>https://repo.spring.io/milestone</url>
-  </repository>
-</repositories>
-----
\ No newline at end of file
diff --git a/docs/guides/src/docs/asciidoc/_includes/maven-repository-release.asc b/docs/guides/src/docs/asciidoc/_includes/maven-repository-release.asc
deleted file mode 100644
index a61938c847..0000000000
--- a/docs/guides/src/docs/asciidoc/_includes/maven-repository-release.asc
+++ /dev/null
@@ -1 +0,0 @@
-Spring Security GA releases are included within Maven Central, so no additional Maven repositories are necessary.
\ No newline at end of file
diff --git a/docs/guides/src/docs/asciidoc/_includes/maven-repository-snapshot.asc b/docs/guides/src/docs/asciidoc/_includes/maven-repository-snapshot.asc
deleted file mode 100644
index 8a1c04f964..0000000000
--- a/docs/guides/src/docs/asciidoc/_includes/maven-repository-snapshot.asc
+++ /dev/null
@@ -1,14 +0,0 @@
-In order to resolve Spring Security SNAPSHOT dependencies add the Spring Snapshot repository. For our example, the repository has already been added for you. In the event you were working on another application, you would need to ensure you add the following to your pom:
-
-.pom.xml
-[source,xml]
-----
-<repositories>
-  <!-- ... possibly other repository elements ... -->
-  <repository>
-    <id>spring-snapshot</id>
-    <name>Spring Snapshot Repository</name>
-    <url>https://repo.spring.io/snapshot</url>
-  </repository>
-</repositories>
-----
\ No newline at end of file
diff --git a/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample-boot.asc b/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample-boot.asc
deleted file mode 100644
index d73db251f2..0000000000
--- a/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample-boot.asc
+++ /dev/null
@@ -1,46 +0,0 @@
-////
-
-Variables:
-
-starter-appname: the name of the module users should start with to complete the exercise
-starter-config-type: the type of configuration the starter sample uses: javaconfig, xml, boot
-completed-appname: the name of the module that contains the completed application
-completed-config-type: the type of configuration the completed sample uses: javaconfig, xml, boot
-download-url: the URL to download the Spring Security distribution
-
-////
-
-== Setting up the sample
-
-This section outlines how to setup a workspace within https://spring.io/tools[Eclipse IDE with Spring Tools] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.
-
-=== Obtaining the sample project
-
-Clone the {gh-samples-url}[Spring Security Samples project] to a known location and remember it as _SPRING_SECURITY_HOME_.
-[NOTE]
-====
-These samples are being migrated to a separate project, however, you can still find
-the not migrated samples in an older branch of the {gh-old-samples-url}[Spring Security repository].
-====
-
-=== Import the {starter-appname} sample application
-
-In order to follow along, we encourage you to import the {starter-appname} sample application into your IDE. You may use any IDE you prefer, but the instructions in this guide will assume you are using Spring Tool Suite (STS).
-
-TIP: The completed sample application can be found at _SPRING_SECURITY_HOME_/samples/{completed-config-type}/{completed-appname}
-
-* If you do not have STS installed, download STS from https://spring.io/tools
-* Start STS and import the sample application into STS using the following steps:
-** *File->Import*
-** *Existing Maven Projects*
-** Click *Next >*
-** Click *Browse...*
-** Navigate to the samples (i.e. _SPRING_SECURITY_HOME_/samples/{starter-config-type}/{starter-appname}) and click *OK*
-** Click *Finish*
-
-=== Running the {starter-appname} application
-
-In the following exercise we will be modifying the _spring-security-samples-{starter-config-type}-{starter-appname}_  application. Before we make any changes, it is best to verify that the sample works properly. Perform the following steps to ensure that _spring-security-samples-{starter-config-type}-{starter-appname}_  works.
-
-* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application
-* Select *Run As->Spring Boot App*
diff --git a/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc b/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc
deleted file mode 100644
index c0586953f2..0000000000
--- a/docs/guides/src/docs/asciidoc/_includes/setting-up-the-sample.asc
+++ /dev/null
@@ -1,48 +0,0 @@
-////
-
-Variables:
-
-starter-appname: the name of the module users should start with to complete the exercise
-starter-config-type: the type of configuration the starter sample uses: javaconfig, xml, boot
-completed-appname: the name of the module that contains the completed application
-completed-config-type: the type of configuration the completed sample uses: javaconfig, xml, boot
-download-url: the URL to download the Spring Security distribution
-
-////
-
-== Setting up the sample
-
-This section outlines how to setup a workspace within https://spring.io/tools[Eclipse IDE with Spring Tools] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.
-
-=== Obtaining the sample project
-
-Clone the {gh-samples-url}[Spring Security Samples project] to a known location and remember it as _SPRING_SECURITY_HOME_.
-[NOTE]
-====
-These samples are being migrated to a separate project, however, you can still find
-the not migrated samples in an older branch of the {gh-old-samples-url}[Spring Security repository].
-====
-
-=== Import the {starter-appname} sample application
-
-In order to follow along, we encourage you to import the {starter-appname} sample application into your IDE. You may use any IDE you prefer, but the instructions in this guide will assume you are using Spring Tool Suite (STS).
-
-TIP: The completed sample application can be found at _SPRING_SECURITY_HOME_/samples/{completed-config-type}/{completed-appname}
-
-* If you do not have STS installed, download STS from https://spring.io/tools
-* Start STS and import the sample application into STS using the following steps:
-** *File->Import*
-** *Existing Maven Projects*
-** Click *Next >*
-** Click *Browse...*
-** Navigate to the samples (i.e. _SPRING_SECURITY_HOME_/samples/{starter-config-type}/{starter-appname}) and click *OK*
-** Click *Finish*
-
-=== Running the {starter-appname} application
-
-In the following exercise we will be modifying the _spring-security-samples-{starter-config-type}-{starter-appname}_  application. Before we make any changes, it is best to verify that the sample works properly. Perform the following steps to ensure that _spring-security-samples-{starter-config-type}-{starter-appname}_  works.
-
-* Right click on the _spring-security-samples-{starter-config-type}-{starter-appname}_ application
-* Select *Run As->Run on Server*
-* Select the latest tc Server
-* Click *Finish*
diff --git a/docs/guides/src/docs/asciidoc/form-javaconfig.asc b/docs/guides/src/docs/asciidoc/form-javaconfig.asc
deleted file mode 100644
index c8281e9b86..0000000000
--- a/docs/guides/src/docs/asciidoc/form-javaconfig.asc
+++ /dev/null
@@ -1,249 +0,0 @@
-= Creating a Custom Login Form
-:author: Rob Winch
-:starter-appname: hellomvc
-:starter-config-type: javaconfig
-:completed-appname: form
-:completed-config-type: javaconfig
-:include-dir: _includes
-
-This guide builds off of link:hellomvc-javaconfig.html[Hello Spring MVC Security Java Config] to explain how to configure and use a custom login form with Spring Security Java Configuration.
-
-include::{include-dir}/setting-up-the-sample.asc[]
-
-Verify the application is working:
-
-* A page displaying a user's inbox can be seen at http://localhost:8080/sample/ after authenticating with the *username* _user_ and the *password* _password_.
-* Try clicking on the Compose link and creating a message. The message details should be displayed.
-* Now click on the Inbox link and see the message listed. You can click on the summary link to see the details displayed again.
-
-
-= Overriding the default configure(HttpSecurity) method
-
-As we saw in link:hellomvc-javaconfig.html[Hello Spring MVC Security Java Config], Spring Security's `WebSecurityConfigurerAdapter` provides some convenient defaults to get our application
-up and running quickly. However, our login form does not look like the rest of our application. Let's see how we can update our configuration to use a custom form.
-
-== Default configure(HttpSecurity)
-
-The default configuration for the configure(HttpSecurity) method can be seen below:
-
-[source,java]
-----
-protected void configure(HttpSecurity http) throws Exception {
-    http
-        .authorizeRequests()
-            .anyRequest().authenticated() <1>
-            .and()
-        .formLogin()                      <2>
-            .and()
-        .httpBasic();                     <3>
-}
-----
-
-The configuration ensures that:
-
-<1> every request requires the user to be authenticated
-<2> form based authentication is supported
-<3> HTTP Basic Authentication is supported
-
-== Configuring a custom login page
-
-We will want to ensure we compensate for overriding these defaults in our updates. Open up the `SecurityConfig` and insert the configure method as shown below:
-
-.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
-[source,java]
-----
-// ...
-
-import org.springframework.security.config.annotation.web.builders.HttpSecurity;
-
-@EnableWebSecurity
-public class SecurityConfig extends WebSecurityConfigurerAdapter {
-
-    @Override
-    protected void configure(HttpSecurity http) throws Exception {
-        http
-            .authorizeRequests()
-                .anyRequest().authenticated()
-                .and()
-            .formLogin()
-                .loginPage("/login");
-    }
-
-    // ...
-}
-----
-
-The line `loginPage("/login")` instructs Spring Security
-
-* when authentication is required, redirect the browser to */login*
-* we are in charge of rendering the login page when */login* is requested
-* when authentication attempt fails, redirect the browser to */login?error* (since we have not specified otherwise)
-* we are in charge of rendering a failure page when */login?error* is requested
-* when we successfully logout, redirect the browser to */login?logout* (since we have not specified otherwise)
-* we are in charge of rendering a logout confirmation page when */login?logout* is requested
-
-Go ahead and start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. In many browsers you will see an error similar to *This webpage has a redirect loop*. What is happening?
-
-== Granting access to unauthenticated users
-
-The issue is that Spring Security is protecting access to our custom login page. In particular the following is happening:
-
-* We make a request to our web application
-* Spring Security sees that we are not authenticated
-* We are redirected to */login*
-* The browser requests */login*
-* Spring Security sees that we are not authenticated
-* We are redirected to */login* ...
-
-To fix this we need to instruct Spring Security to allow anyone to access the */login* URL. We can easily do this with the following updates:
-
-.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
-[source,java]
-----
-// ...
-
-@EnableWebSecurity
-public class SecurityConfig extends WebSecurityConfigurerAdapter {
-
-    @Override
-    protected void configure(HttpSecurity http) throws Exception {
-        http
-            .authorizeRequests()
-                .anyRequest().authenticated()
-                .and()
-            .formLogin()
-                .loginPage("/login")
-                .permitAll();
-    }
-
-    // ...
-}
-----
-
-The method `formLogin().permitAll()` statement instructs Spring Security to allow any access to any URL (i.e. */login* and */login?error*) associated to `formLogin()`.
-
-NOTE: Granting access to the `formLogin()` URLs is not done by default since Spring Security needs to make certain assumptions about what is allowed and what is not. To be secure, it is best to ensure granting access to resources is explicit.
-
-Start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. You should now get a 500 error stating **Error resolving template "login"**.
-
-= Creating a login page
-
-Within Spring Web MVC there are two steps to creating our login page:
-
-* Creating a controller
-* Creating a view
-
-== Configuring a login view controller
-
-Within Spring Web MVC, the first step is to ensure that we have a controller that can point to our view. Since our project adds the *javaconfig/messages* project as a dependency and it contains a view controller for */login* we do not need to create a controller within our application. For reference, you can see the configuration below:
-
-[source,java]
-----
-// ...
-
-@EnableWebMvc
-@ComponentScan("org.springframework.security.samples.mvc")
-public class WebMvcConfiguration implements WebMvcConfigurer {
-
-    // ...
-
-    @Override
-    public void addViewControllers(ViewControllerRegistry registry) {
-        registry.addViewController("/login").setViewName("login");
-        registry.setOrder(Ordered.HIGHEST_PRECEDENCE);
-    }
-}
-----
-
-== Creating a login view
-
-Our existing configuration means that all we need to do is create a *login.html* file with the following contents:
-
-.src/main/resources/views/login.html
-[source,xml]
-----
-<html xmlns:th="https://www.thymeleaf.org">
-  <head th:include="layout :: head(title=~{::title},links=~{})">
-    <title>Please Login</title>
-  </head>
-  <body th:include="layout :: body" th:with="content=~{::content}">
-    <div th:fragment="content">
-        <form name="f" th:action="@{/login}" method="post">               <1>
-            <fieldset>
-                <legend>Please Login</legend>
-                <div th:if="${param.error}" class="alert alert-error">    <2>
-                    Invalid username and password.
-                </div>
-                <div th:if="${param.logout}" class="alert alert-success"> <3>
-                    You have been logged out.
-                </div>
-                <label for="username">Username</label>
-                <input type="text" id="username" name="username"/>        <4>
-                <label for="password">Password</label>
-                <input type="password" id="password" name="password"/>    <5>
-                <div class="form-actions">
-                    <button type="submit" class="btn">Log in</button>
-                </div>
-            </fieldset>
-        </form>
-    </div>
-  </body>
-</html>
-----
-
-<1> The URL we submit our username and password to is the same URL as our login form (i.e. */login*), but a *POST* instead of a *GET*.
-<2> When authentication fails, the browser is redirected to */login?error* so we can display an error message by detecting if the parameter *error* is non-null.
-<3> When we are successfully logged out, the browser is redirected to */login?logout* so we can display an logout success message by detecting if the parameter *logout* is non-null.
-<4> The username should be present on the HTTP parameter username
-<5> The password should be present on the HTTP parameter password
-
-IMPORTANT: Do not display details about why authentication failed. For example, we do not want to display that the user does not exist as this will tell an attacker that they should try a different username.
-
-TIP: We use Thymeleaf to automatically add the CSRF token to our form. If we were not using Thymeleaf or Spring MVCs taglib we could also manually add the CSRF token using `<input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>`.
-
-Start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. We now see our login page, but it does not look very pretty. The issue is that we have not granted access to the css files.
-
-== Grant access to remaining resources
-
-We need to update our configuration to allow anyone to access our resources and our logout pages. Update the configuration as shown below:
-
-.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
-[source,java]
-----
-// ...
-
-@EnableWebSecurity
-public class SecurityConfig extends WebSecurityConfigurerAdapter {
-
-    @Override
-    protected void configure(HttpSecurity http) throws Exception {
-        http
-            .authorizeRequests()
-                .antMatchers("/resources/**").permitAll() <1>
-                .anyRequest().authenticated()
-                .and()
-            .formLogin()
-                .loginPage("/login")
-                .permitAll()
-                .and()
-            .logout()                                    <2>
-                .permitAll();
-    }
-
-    // ...
-}
-----
-
-<1> This allows anyone to access a URL that begins with */resources/*. Since this is where our css, javascript, and images are stored all our static resources are viewable by anyone.
-<2> As you might expect, `logout().permitAll()` allows any user to request logout and view logout success URL.
-
-
-Restart the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. We now see a custom login page that looks like the rest of our application.
-
-* Try entering an invalid username and password. You will see our error message is displayed.
-* Try entering a valid username (user) and password (password). You will be authenticated successfully.
-* Try clicking the Log Out button. You will see our logout success message
-
-== Conclusion
-
-You should now know how to add a custom login form using Spring Security's Java Configuration. To learn more refer to the link:index.html[Spring Security Guides index page].
diff --git a/docs/guides/src/docs/asciidoc/hellomvc-javaconfig.asc b/docs/guides/src/docs/asciidoc/hellomvc-javaconfig.asc
deleted file mode 100644
index c913e2c4ad..0000000000
--- a/docs/guides/src/docs/asciidoc/hellomvc-javaconfig.asc
+++ /dev/null
@@ -1,127 +0,0 @@
-= Hello Spring MVC Security Java Config
-:author: Rob Winch
-:starter-appname: insecuremvc
-:starter-config-type: xml
-:completed-appname: hellomvc
-:completed-config-type: javaconfig
-:include-dir: _includes
-:hello-include-dir: _hello-includes
-
-This guide provides instructions on how to add Spring Security to an existing Spring MVC application without the use of XML.
-
-include::{include-dir}/setting-up-the-sample.asc[]
-
-Verify the application is working:
-
-* A page displaying a user's inbox can be seen at http://localhost:8080/sample/
-* Try clicking on the Compose link and creating a message. The message details should be displayed.
-* Now click on the Inbox link and see the message listed. You can click on the summary link to see the details displayed again.
-
-
-include::{hello-include-dir}/secure-the-application-javaconfig.asc[]
-
-=== Registering Spring Security with the war
-
-We have created the Spring Security configuration, but we still need to register it with the war. This can be done using the following steps:
-
-* Right click the _spring-security-samples-{starter-config-type}-{starter-appname}_ project the Package Explorer view
-* Select *New->Class*
-* Enter _org.springframework.security.samples.config_ for the *Package*
-* Enter MessageSecurityWebApplicationInitializer for the *Name*
-* Click *Finish*
-* Replace the file with the following contents:
-
-.src/main/java/org/springframework/security/samples/config/MessageSecurityWebApplicationInitializer.java
-[source,java]
-----
-package org.springframework.security.samples.config;
-
-import org.springframework.security.web.context.*;
-
-public class MessageSecurityWebApplicationInitializer
-      extends AbstractSecurityWebApplicationInitializer {
-}
-----
-
-The `MessageSecurityWebApplicationInitializer` will automatically register the springSecurityFilterChain Filter for every URL in your application. If Filters are added within other `WebApplicationInitializer` instances we can use `@Order` to control the ordering of the Filter instances.
-
-=== Verify SecurityConfig is loaded
-
-Just because <<security-config-java,SecurityConfig>> exists, does not mean that our Spring application knows about it. In this instance, our Spring root application context is initialized using MessageWebApplicationInitializer which is included with our spring-security-samples-javaconfig-messages project. You can find a snippet of it below:
-
-[[message-web-application-inititializer-java]]
-.MessageWebApplicationInitializer.java
-[source,java]
-----
-public class MessageWebApplicationInitializer extends
-        AbstractAnnotationConfigDispatcherServletInitializer {
-
-    @Override
-    protected Class<?>[] getRootConfigClasses() {
-        return new Class[] { RootConfiguration.class };
-    }
-
-    // ... other overrides ...
-}
-----
-
-You will notice it is loading the `RootConfiguration` class which is also included in our spring-security-samples-javaconfig-messages project.
-
-[[root-configuration-java]]
-.RootConfiguration.java
-[source,java]
-----
-@Configuration
-@ComponentScan
-public class RootConfiguration {
-}
-----
-
-The `@ComponentScan` is loading all configuration within the same package (and child packages) as `RootConfiguration`. Since <<security-config-java,SecurityConfig>> is in this package, it will be loaded with our existing setup and there is nothing more to do.
-
-NOTE: Had <<security-config-java,SecurityConfig>> not been loaded, we could have used an `@Import(SecurityConfig.class)` above the class definition of <<root-configuration-java,RootConfiguration>> or added <<security-config-java,SecurityConfig>> as one of the results for `getRootConfigClasses()`.
-
-include::{hello-include-dir}/exploring-the-secured-application-javaconfig.asc[]
-
-==== Displaying the user name
-
-Now that we have authenticated, let's see how our application is displaying the username if the user is authenticated.
-
-.messages/src/main/resources/views/layout.html
-[source,html]
-----
-<div th:if="${#httpServletRequest.remoteUser != null}">
-    <p th:text="${#httpServletRequest.remoteUser}">
-      sample_user
-    </p>
-</div>
-----
-
-In our samples we use https://www.thymeleaf.org/[Thymeleaf], but any view technology will work. Any technology can inspect the `HttpServletRequest#getRemoteUser()` to view the current user since Spring Security integrates with the <<servlet-api-integration,Servlet API methods>>.
-
-WARNING: The Thymeleaf ensures the username is escaped to avoid https://en.wikipedia.org/wiki/Cross-site_scripting[XSS vulnerabilities] Regardless of how an application renders user inputed values, it should ensure that the values are properly escaped.
-
-==== Logging out
-
-We can view the user name, but how are we able to log out? Below you can see how we are able to log out.
-
-.messages/src/main/resources/views/layout.html
-[source,html]
-----
-<form th:action="@{/logout}" method="post">
-    <input type="submit" value="Log out" />
-</form>
-----
-
-In order to help protect against https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attacks], by default, Spring Security Java Configuration log out requires:
-
-* the HTTP method must be a POST
-* the CSRF token must be added to the request. Since we have used `@EnableWebSecurity` and are using Thymeleaf, the CSRF token is automatically added as a hidden input for you (view the source to see it).
-
-NOTE: If you were not using Spring MVC taglibs or Thymeleaf, you can access the CsrfToken on the ServletRequest using the attribute _csrf.  You can find an example of including the CSRF token in a JSP within the link:helloworld-javaconfig.html[Hello Spring Security Java Config].
-
-Restart the application server and click the Log out button and see that the application logs you out successfully.
-
-== Conclusion
-
-You should now know how to secure your application using Spring Security without using any XML. Next, we will see how to link:form-javaconfig.html[customize our login form].
diff --git a/docs/guides/src/docs/asciidoc/helloworld-boot.asc b/docs/guides/src/docs/asciidoc/helloworld-boot.asc
deleted file mode 100644
index cc75981d58..0000000000
--- a/docs/guides/src/docs/asciidoc/helloworld-boot.asc
+++ /dev/null
@@ -1,97 +0,0 @@
-= Hello Spring Security with Boot
-:author: Joe Grandja
-:starter-appname: insecure
-:starter-config-type: boot
-:completed-appname: helloworld
-:completed-config-type: boot
-:include-dir: _includes
-:hello-include-dir: _hello-includes
-
-This guide provides instructions on how to add Spring Security to an existing Spring Boot application.
-
-include::{include-dir}/setting-up-the-sample-boot.asc[]
-
-Verify the application is working by navigating to http://localhost:8080/
-
-Click on the *_secured pages_* link and verify the page states *TODO Secure this*
-
-Once you have verified the application runs, stop the application server using the following steps:
-
-* In the _Boot Dashboard_ view select the running application
-* Click the stop button (a red square) to stop the application
-
-include::{hello-include-dir}/secure-the-application-boot.asc[]
-
-include::{hello-include-dir}/exploring-the-secured-application-boot.asc[]
-
-==== Displaying the user name
-
-Now that we have authenticated, let's update the application to display the username. Update the complete content of */index.html* with the following:
-
-.src/main/resources/templates/index.html
-[source,html]
-----
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org" xmlns:sec="https://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
-    <head>
-        <title>Hello Spring Security</title>
-        <meta charset="utf-8" />
-        <link rel="stylesheet" href="/css/main.css" th:href="@{/css/main.css}" />
-    </head>
-    <body>
-        <div th:fragment="logout" class="logout" sec:authorize="isAuthenticated()">		<1>
-            Logged in user: <span sec:authentication="name"></span> |					<2>
-            Roles: <span sec:authentication="principal.authorities"></span>				<3>
-            <div>
-                <form action="#" th:action="@{/logout}" method="post">					<4>
-                    <input type="submit" value="Logout" />
-                </form>
-            </div>
-        </div>
-        <h1>Hello Spring Security</h1>
-        <p>This is an unsecured page, but you can access the secured pages after authenticating.</p>
-        <ul>
-            <li>Go to the <a href="/user/index" th:href="@{/user/index}">secured pages</a></li>
-        </ul>
-    </body>
-</html>
-----
-
-NOTE: We are using https://www.thymeleaf.org/[Thymeleaf] for our view template engine and
-https://github.com/thymeleaf/thymeleaf-extras-springsecurity[Thymeleaf - Spring Security integration modules]
-in order to utilize the _sec:authentication_ and _sec:authorize_ attributes.
-
-<1> Displays the Thymeleaf fragment (DOM Node) if the current user has been authenticated.
-<2> Displays the name of the currently authenticated principal.
-<3> Displays the authorities of the currently authenticated principal.
-<4> The logout form.
-
-TIP: Thymeleaf will automatically add the CSRF token to our logout form. If we were not using Thymeleaf or Spring MVCs taglib we could also manually add the CSRF token using `<input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>`.
-
-==== Update the _secured_ page
-
-The last step is to update the _secured_ page to also display the currently authenticated principal. Update the complete content of */user/index.html* with the following:
-
-.src/main/resources/templates/user/index.html
-[source,html]
-----
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org">
-    <head>
-        <title>Hello Spring Security</title>
-        <meta charset="utf-8" />
-        <link rel="stylesheet" href="/css/main.css" th:href="@{/css/main.css}" />
-    </head>
-    <body>
-        <div th:substituteby="index::logout"></div>
-        <h1>This is a secured page!</h1>
-        <p><a href="/index" th:href="@{/index}">Back to home page</a></p>
-    </body>
-</html>
-----
-
-Start up the server and try visiting http://localhost:8080/ to see the updates to our application.
-
-== Conclusion
-
-You should now know how to secure your application using Spring Security with an existing Spring Boot application . To learn more refer to the link:index.html[Spring Security Guides index page].
diff --git a/docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc b/docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc
deleted file mode 100644
index d418e918a2..0000000000
--- a/docs/guides/src/docs/asciidoc/helloworld-javaconfig.asc
+++ /dev/null
@@ -1,113 +0,0 @@
-= Hello Spring Security Java Config
-:author: Rob Winch
-:starter-appname: insecure
-:starter-config-type: xml
-:completed-appname: helloworld
-:completed-config-type: javaconfig
-:include-dir: _includes
-:hello-include-dir: _hello-includes
-
-This guide provides instructions on how to add Spring Security to an existing application without the use of XML.
-
-include::{include-dir}/setting-up-the-sample.asc[]
-
-Verify the application is working by ensuring a page stating *TODO Secure this* is displayed at http://localhost:8080/sample/
-
-Once you have verified the application runs, stop the application server using the following steps:
-
-* In the Servers view select the latest tc Server
-* Click the stop button (a red square) to stop the application server
-
-include::{hello-include-dir}/secure-the-application-javaconfig.asc[]
-
-=== Registering Spring Security with the war
-
-We have created the Spring Security configuration, but we still need to register it with the war. This can be done using the following steps:
-
-* Navigate to the *Package Explorer* view
-* Right click the *org.springframework.security.samples.config* package within the *spring-security-samples-{starter-config-type}-{starter-appname}* project
-* Select *New->Class*
-* Enter _SecurityWebApplicationInitializer_ for the *Name*
-* Click *Finish*
-* Replace the file with the following contents:
-
-.src/main/java/org/springframework/security/samples/config/SecurityWebApplicationInitializer.java
-[source,java]
-----
-package org.springframework.security.samples.config;
-
-import org.springframework.security.web.context.*;
-
-public class SecurityWebApplicationInitializer
-      extends AbstractSecurityWebApplicationInitializer {
-
-    public SecurityWebApplicationInitializer() {
-        super(SecurityConfig.class);
-    }
-}
-----
-
-The `SecurityWebApplicationInitializer` will do the following things:
-
-* Automatically register the springSecurityFilterChain Filter for every URL in your application
-* Add a ContextLoaderListener that loads the <<security-config-java,SecurityConfig>>.
-
-NOTE: Since we were not already using Spring, this is a simple way to add our <<security-config-java,SecurityConfig>>. If we were already using Spring, then we should add our <<security-config-java,SecurityConfig>> with the reset of our Spring configuration (i.e. a subclass of AbstractContextLoaderInitializer or AbstractDispatcherServletInitializer) and use the default constructor instead.
-
-include::{hello-include-dir}/exploring-the-secured-application-javaconfig.asc[]
-
-==== Displaying the user name
-
-Now that we have authenticated, let's update the application to display the username. Update the body of index.jsp to be the following:
-
-.src/main/webapp/index.jsp
-[source,html]
-----
-<body>
-  <div class="container">
-    <h1>This is secured!</h1>
-    <p>
-      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
-    </p>
-  </div>
-</body>
-----
-
-WARNING: The `<c:out />` tag ensures the username is escaped to avoid https://en.wikipedia.org/wiki/Cross-site_scripting[XSS vulnerabilities] Regardless of how an application renders user inputed values, it should ensure that the values are properly escaped.
-
-Refresh the page at http://localhost:8080/sample/ and you will see the user name displayed. This works because Spring Security integrates with the <<servlet-api-integration,Servlet API methods>>
-
-==== Logging out
-
-Now that we can view the user name, let's update the application to allow logging out. Update the body of index.jsp to contain a log out form as shown below:
-
-.src/main/webapp/index.jsp
-[source,html]
-----
-<body>
-  <div class="container">
-    <h1>This is secured!</h1>
-    <p>
-      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
-    </p>
-    <c:url var="logoutUrl" value="/logout"/>
-    <form class="form-inline" action="${logoutUrl}" method="post">
-      <input type="submit" value="Log out" />
-      <input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>
-    </form>
-  </div>
-</body>
-----
-
-In order to help protect against https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attacks], by default, Spring Security Java Configuration log out requires:
-
-* the HTTP method must be a POST
-* the CSRF token must be added to the request. You can access it on the ServletRequest using the attribute _csrf as illustrated above.
-
-NOTE: If you were using Spring MVC's tag library or Thymeleaf, the CSRF token is automatically added as a hidden input for you.
-
-Refresh the page at http://localhost:8080/sample/ and you will see the log out button. Click the logout button and see that the application logs you out successfully.
-
-== Conclusion
-
-You should now know how to secure your application using Spring Security without using any XML. To learn more refer to the link:index.html[Spring Security Guides index page].
diff --git a/docs/guides/src/docs/asciidoc/helloworld-xml.asc b/docs/guides/src/docs/asciidoc/helloworld-xml.asc
deleted file mode 100644
index c04f05a5fe..0000000000
--- a/docs/guides/src/docs/asciidoc/helloworld-xml.asc
+++ /dev/null
@@ -1,136 +0,0 @@
-= Hello Spring Security Xml Config
-:author: Joe Grandja
-:starter-appname: insecure
-:starter-config-type: xml
-:completed-appname: helloworld
-:completed-config-type: xml
-:include-dir: _includes
-:hello-include-dir: _hello-includes
-
-This guide provides instructions on how to add Spring Security to an existing application using XML configuration.
-
-include::{include-dir}/setting-up-the-sample.asc[]
-
-Verify the application is working by ensuring a page stating *TODO Secure this* is displayed at http://localhost:8080/sample/
-
-Once you have verified the application runs, stop the application server using the following steps:
-
-* In the Servers view select the latest tc Server
-* Click the stop button (a red square) to stop the application server
-
-include::{hello-include-dir}/secure-the-application-xml.asc[]
-
-=== Registering Spring Security with the war
-
-We have created the Spring Security configuration, but we still need to register it with the war. This can be done using the following steps:
-
-* In the Package Explorer view, right click on the folder _src/main/webapp/WEB-INF_
-* Select *New->File*
-* Enter _web.xml_ for the *File name*
-* Click *Finish*
-* Replace the contents of the file with the following:
-
-.src/main/webapp/WEB-INF/web.xml
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
-		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-		 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
-  https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
-
-	<!--
-	  - Location of the XML file that defines the root application context
-	  - Applied by ContextLoaderListener.
-	  -->
-	<context-param>
-		<param-name>contextConfigLocation</param-name>
-		<param-value>
-			/WEB-INF/spring/*.xml
-		</param-value>
-	</context-param>
-
-
-	<filter>
-		<filter-name>springSecurityFilterChain</filter-name>
-		<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
-	</filter>
-	<filter-mapping>
-		<filter-name>springSecurityFilterChain</filter-name>
-		<url-pattern>/*</url-pattern>
-	</filter-mapping>
-
-	<!--
-	  - Loads the root application context of this web app at startup.
-	  - The application context is then available via
-	  - WebApplicationContextUtils.getWebApplicationContext(servletContext).
-	-->
-	<listener>
-		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
-	</listener>
-
-</web-app>
-----
-
-The _web.xml_ will do the following things:
-
-* Registers the `springSecurityFilterChain` Filter for every URL in your application
-* Adds a `ContextLoaderListener` that loads the <<security-config-xml,security-config-xml>>.
-
-include::{hello-include-dir}/exploring-the-secured-application-xml.asc[]
-
-==== Displaying the user name
-
-Now that we have authenticated, let's update the application to display the username. Update the body of index.jsp to be the following:
-
-.src/main/webapp/index.jsp
-[source,html]
-----
-<body>
-  <div class="container">
-    <h1>This is secured!</h1>
-    <p>
-      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
-    </p>
-  </div>
-</body>
-----
-
-WARNING: The `<c:out />` tag ensures the username is escaped to avoid https://en.wikipedia.org/wiki/Cross-site_scripting[XSS vulnerabilities] Regardless of how an application renders user inputed values, it should ensure that the values are properly escaped.
-
-Refresh the page at http://localhost:8080/sample/ and you will see the user name displayed. This works because Spring Security integrates with the <<servlet-api-integration,Servlet API methods>>
-
-==== Logging out
-
-Now that we can view the user name, let's update the application to allow logging out. Update the body of index.jsp to contain a log out form as shown below:
-
-.src/main/webapp/index.jsp
-[source,html]
-----
-<body>
-  <div class="container">
-    <h1>This is secured!</h1>
-    <p>
-      Hello <b><c:out value="${pageContext.request.remoteUser}"/></b>
-    </p>
-    <c:url var="logoutUrl" value="/logout"/>
-    <form class="form-inline" action="${logoutUrl}" method="post">
-      <input type="submit" value="Log out" />
-      <input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>
-    </form>
-  </div>
-</body>
-----
-
-In order to help protect against https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF attacks], by default, Spring Security Xml Configuration log out requires:
-
-* the HTTP method must be a POST
-* the CSRF token must be added to the request. You can access it on the ServletRequest using the attribute _csrf as illustrated above.
-
-NOTE: If you were using Spring MVC's tag library or Thymeleaf, the CSRF token is automatically added as a hidden input for you.
-
-Refresh the page at http://localhost:8080/sample/ and you will see the log out button. Click the logout button and see that the application logs you out successfully.
-
-== Conclusion
-
-You should now know how to secure your application using Spring Security with XML. To learn more refer to the link:index.html[Spring Security Guides index page].
diff --git a/docs/guides/src/docs/asciidoc/index.asc b/docs/guides/src/docs/asciidoc/index.asc
deleted file mode 100644
index bf721d86a3..0000000000
--- a/docs/guides/src/docs/asciidoc/index.asc
+++ /dev/null
@@ -1,17 +0,0 @@
-= Spring Security Guides
-Rob Winch, Joe Grandja
-
-These are step by step guides on how to use Spring Security.
-
-== Hello World
-
-These are the most basic starting points for using a web based application.
-
-* link:helloworld-javaconfig.html[Hello Spring Security Java Config] - demonstrates how to integrate Spring Security with an existing application using Java-based configuration
-* link:helloworld-boot.html[Hello Spring Security with Boot] - demonstrates how to integrate Spring Security with an existing Spring Boot application
-* link:helloworld-xml.html[Hello Spring Security Xml Config] - demonstrates how to integrate Spring Security with an existing application using Xml-based configuration
-* link:hellomvc-javaconfig.html[Hello Spring MVC Security Java Config] - demonstrates how to integrate Spring Security with an existing Spring MVC application
-
-== Simple Customization
-
-* link:form-javaconfig.html[Creating a custom login form] - demonstrates how to create a custom login form
diff --git a/docs/manual/spring-security-docs-manual.gradle b/docs/manual/spring-security-docs-manual.gradle
deleted file mode 100644
index 6b0647cb9c..0000000000
--- a/docs/manual/spring-security-docs-manual.gradle
+++ /dev/null
@@ -1,62 +0,0 @@
-apply plugin: 'io.spring.convention.docs'
-apply plugin: 'io.spring.convention.management-configuration'
-apply plugin: 'io.spring.convention.repository'
-apply plugin: 'java'
-
-asciidoctor {
-	attributes([stylesheet: 'css/style.css'])
-	resources {
-		from(sourceDir) {
-			include "css/**"
-		}
-	}
-}
-
-asciidoctorj {
-	def docsTag = snapshotBuild ? 'current' : project.version
-	def ghTag = snapshotBuild ? 'main' : project.version
-	def ghUrl = "https://github.com/spring-projects/spring-security/tree/$ghTag"
-	def ghOldSamplesUrl = "https://github.com/spring-projects/spring-security/tree/5.4.x/samples"
-	def ghSamplesUrl = "https://github.com/spring-projects/spring-security-samples/tree/$samplesBranch"
-	def securityDocsUrl = "https://docs.spring.io/spring-security/site/docs/$docsTag"
-	def securityApiUrl = "$securityDocsUrl/api/"
-	def securityReferenceUrl = "$securityDocsUrl/reference/html5/"
-	def springFrameworkApiUrl = "https://docs.spring.io/spring-framework/docs/$springFrameworkVersion/javadoc-api/"
-	def springFrameworkReferenceUrl = "https://docs.spring.io/spring-framework/docs/$springFrameworkVersion/reference/html/"
-	attributes 'spring-security-version' : project.version,
-		'spring-boot-version' : springBootVersion,
-		revnumber : project.version,
-		'gh-url': ghUrl,
-		'gh-samples-url': ghSamplesUrl,
-		'gh-old-samples-url': ghOldSamplesUrl,
-		'security-api-url': securityApiUrl,
-		'security-reference-url': securityReferenceUrl,
-		'spring-framework-api-url': springFrameworkApiUrl,
-		'spring-framework-reference-url': springFrameworkReferenceUrl
-	attributeProvider resolvedVersions(project.configurations.testRuntimeClasspath)
-}
-
-docsZip {
-	from(project(':spring-security-docs-guides').asciidoctor) {
-		into 'guides'
-	}
-}
-
-dependencies {
-	management platform(project(":spring-security-dependencies"))
-	testImplementation "com.unboundid:unboundid-ldapsdk"
-	testImplementation "org.apache.directory.server:apacheds-core"
-	testImplementation "org.springframework:spring-core"
-}
-
-def resolvedVersions(Configuration configuration) {
-	return {
-		configuration.resolvedConfiguration
-			.resolvedArtifacts
-			.collectEntries { [(it.name + "-version"): it.moduleVersion.id.version] }
-	}
-}
-
-repositories {
-	maven { url "https://repo.spring.io/release" }
-}
diff --git a/docs/manual/src/docs/asciidoc/Guardfile b/docs/manual/src/docs/asciidoc/Guardfile
deleted file mode 100644
index 076f37d0f4..0000000000
--- a/docs/manual/src/docs/asciidoc/Guardfile
+++ /dev/null
@@ -1,12 +0,0 @@
-require 'asciidoctor'
-require 'erb'
-
-guard 'shell' do
-  watch(/^.*\.adoc$/) {|m|
-    Asciidoctor.render_file(m[0], :to_dir => "build/", :safe => Asciidoctor::SafeMode::UNSAFE, :attributes=> {'idprefix' => '', 'idseparator' => '-', 'copycss' => '', 'icons' => 'font', 'source-highlighter' => 'prettify', 'sectanchors' => '', 'doctype' => 'book','toc2' => '', 'spring-security-version' => '3.2.0.CI-SNAPSHOT','spring-version' => '3.2.0.RELEASE','spring4-version' => '4.0.0.RELEASE', 'revnumber' => '3.2.0.CI-SNAPSHOT', 'numbered'=>'' })
-  }
-end
-
-guard 'livereload' do
-  watch(%r{build/.+\.(css|js|html)$})
-end
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/authentication/supported.adoc b/docs/manual/src/docs/asciidoc/_includes/about/authentication/supported.adoc
deleted file mode 100644
index 85bd943456..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/about/authentication/supported.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-[[authentication-support]]
-= Authentication Support
-
-Spring Security provides built in support for authenticating users.
-Refer to the sections on authentication for <<servlet-authentication,Servlet>> and WebFlux for details on what is supported for each stack.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/features.adoc b/docs/manual/src/docs/asciidoc/_includes/about/features.adoc
deleted file mode 100644
index c08113ae5e..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/about/features.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[features]]
-= Features
-
-Spring Security provides comprehensive support for <<authentication,authentication>>, authorization, and protection against <<exploits,common exploits>>.
-It also provides integration with other libraries to simplify its usage.
-
-include::authentication/index.adoc[leveloffset=+1]
-
-include::exploits/index.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/index.adoc b/docs/manual/src/docs/asciidoc/_includes/about/index.adoc
deleted file mode 100644
index 9345d31731..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/about/index.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= Introduction
-
-This section discusses the logistics of Spring Security.
-
-include::prerequisites.adoc[leveloffset=+1]
-
-include::community.adoc[leveloffset=+1]
-
-include::whats-new.adoc[]
-
-include::getting-spring-security.adoc[leveloffset=+1]
-
-include::features.adoc[leveloffset=+1]
-
-include::modules.adoc[leveloffset=+1]
-
-include::samples.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/content.adoc b/docs/manual/src/docs/asciidoc/_includes/content.adoc
deleted file mode 100644
index 2cabae6ea5..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/content.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-= Book Title
-Rob Winch
-
-[abstract]
-This is the actual content.
-
-== First Section
-
-And off we go.
\ No newline at end of file
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc
deleted file mode 100644
index 6d5c8c66a8..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= Protection Against Exploits
-
-include::csrf.adoc[leveloffset=+1]
-
-include::headers.adoc[leveloffset=+1]
-
-include::http.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc
deleted file mode 100644
index 497e239786..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= Reactive Applications
-
-include::webflux.adoc[leveloffset=+1]
-
-include::exploits/index.adoc[leveloffset=+1]
-
-include::oauth2/index.adoc[leveloffset=+1]
-
-include::registered-oauth2-authorized-client.adoc[leveloffset=+1]
-
-include::x509.adoc[leveloffset=+1]
-
-include::logout.adoc[leveloffset=+1]
-
-include::webclient.adoc[leveloffset=+1]
-
-include::method.adoc[leveloffset=+1]
-
-include::cors.adoc[leveloffset=+1]
-
-include::test.adoc[leveloffset=+1]
-
-include::rsocket.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc
deleted file mode 100644
index c58f3fb3ab..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[webflux-oauth2]]
-= OAuth2 WebFlux
-
-Spring Security provides OAuth2 and WebFlux integration for reactive applications.
-
-include::login.adoc[leveloffset=+1]
-
-include::access-token.adoc[leveloffset=+1]
-
-include::resource-server.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc
deleted file mode 100644
index 5f01cc38d0..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-
-= Appendix
-
-include::database-schema.adoc[leveloffset=+1]
-
-include::namespace.adoc[]
-
-include::faq.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc
deleted file mode 100644
index 1ccac8c584..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[servlet-delegatingfilterproxy]]
-= DelegatingFilterProxy
-
-Spring provides a `Filter` implementation named {spring-framework-api-url}org/springframework/web/filter/DelegatingFilterProxy.html[`DelegatingFilterProxy`] that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
-The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
-`DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.
-
-Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filters-review,``Filter``s and the `FilterChain`>>.
-
-.DelegatingFilterProxy
-[[servlet-delegatingfilterproxy-figure]]
-image::{figures}/delegatingfilterproxy.png[]
-
-`DelegatingFilterProxy` looks up __Bean Filter~0~__ from the `ApplicationContext` and then invokes __Bean Filter~0~__.
-The pseudo code of `DelegatingFilterProxy` can be seen below.
-
-.`DelegatingFilterProxy` Pseudo Code
-====
-.Java
-[source,java,role="primary",subs="+quotes,+macros"]
-----
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
-	// Lazily get Filter that was registered as a Spring Bean
-	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
-	Filter delegate = getFilterBean(someBeanName);
-	// delegate work to the Spring Bean
-	delegate.doFilter(request, response);
-}
-----
-
-.Kotlin
-[source,kotlin,role="secondary",subs="+quotes,+macros"]
-----
-fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
-	// Lazily get Filter that was registered as a Spring Bean
-	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
-	val delegate: Filter = getFilterBean(someBeanName)
-	// delegate work to the Spring Bean
-	delegate.doFilter(request, response)
-}
-----
-====
-
-Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances up.
-This is important because the container needs to register the `Filter` instances before the container can startup.
-However, Spring typically uses a `ContextLoaderListener` to load the Spring Beans which will not be done until after the `Filter` instances need to be registered.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc
deleted file mode 100644
index 941c1fb122..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[servlet-exceptiontranslationfilter]]
-= Handling Security Exceptions
-:figures: images/servlet/architecture
-:icondir: images/icons
-
-
-The {security-api-url}org/springframework/security/web/access/ExceptionTranslationFilter.html[`ExceptionTranslationFilter`] allows translation of {security-api-url}org/springframework/security/access/AccessDeniedException.html[`AccessDeniedException`] and {security-api-url}/org/springframework/security/core/AuthenticationException.html[`AuthenticationException`] into HTTP responses.
-
-`ExceptionTranslationFilter` is inserted into the <<servlet-filterchainproxy>> as one of the <<servlet-security-filters>>.
-
-image::{figures}/exceptiontranslationfilter.png[]
-
-
-* image:{icondir}/number_1.png[] First, the `ExceptionTranslationFilter` invokes `FilterChain.doFilter(request, response)` to invoke the rest of the application.
-* image:{icondir}/number_2.png[] If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__.
-** The <<servlet-authentication-securitycontextholder>> is cleared out.
-** The `HttpServletRequest` is saved in the {security-api-url}org/springframework/security/web/savedrequest/RequestCache.html[`RequestCache`].
-When the user successfully authenticates, the `RequestCache` is used to replay the original request.
-// FIXME: add link to authentication success
-** The `AuthenticationEntryPoint` is used to request credentials from the client.
-For example, it might redirect to a log in page or send a `WWW-Authenticate` header.
-// FIXME: link to AuthenticationEntryPoint
-* image:{icondir}/number_3.png[] Otherwise if it is an `AccessDeniedException`, then __Access Denied__.
-The `AccessDeniedHandler` is invoked to handle access denied.
-// FIXME: link to AccessDeniedHandler
-
-[NOTE]
-====
-If the application does not throw an `AccessDeniedException` or an `AuthenticationException`, then `ExceptionTranslationFilter` does not do anything.
-====
-
-The pseudocode for `ExceptionTranslationFilter` looks something like this:
-
-.ExceptionTranslationFilter pseudocode
-[source,java]
-----
-try {
-	filterChain.doFilter(request, response); // <1>
-} catch (AccessDeniedException | AuthenticationException ex) {
-	if (!authenticated || ex instanceof AuthenticationException) {
-		startAuthentication(); // <2>
-	} else {
-		accessDenied(); // <3>
-	}
-}
-----
-<1> You will recall from <<servlet-filters-review>> that invoking `FilterChain.doFilter(request, response)` is the equivalent of invoking the rest of the application.
-This means that if another part of the application, (i.e. <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> or method security) throws an `AuthenticationException` or `AccessDeniedException` it will be caught and handled here.
-<2> If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__.
-<3> Otherwise, __Access Denied__
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filter-chain-proxy.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filter-chain-proxy.adoc
deleted file mode 100644
index 0b15efeec9..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filter-chain-proxy.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[servlet-filterchainproxy]]
-= FilterChainProxy
-
-Spring Security's Servlet support is contained within `FilterChainProxy`.
-`FilterChainProxy` is a special `Filter` provided by Spring Security that allows delegating to many `Filter` instances through <<servlet-securityfilterchain,`SecurityFilterChain`>>.
-Since `FilterChainProxy` is a Bean, it is typically wrapped in a <<servlet-delegatingfilterproxy>>.
-
-.FilterChainProxy
-[[servlet-filterchainproxy-figure]]
-image::{figures}/filterchainproxy.png[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filters.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filters.adoc
deleted file mode 100644
index 37509ac256..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/filters.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[servlet-filters-review]]
-= A Review of ``Filter``s
-
-Spring Security's Servlet support is based on Servlet ``Filter``s, so it is helpful to look at the role of ``Filter``s generally first.
-The picture below shows the typical layering of the handlers for a single HTTP request.
-
-.FilterChain
-[[servlet-filterchain-figure]]
-image::{figures}/filterchain.png[]
-
-The client sends a request to the application, and the container creates a `FilterChain` which contains the ``Filter``s and `Servlet` that should process the `HttpServletRequest` based on the path of the request URI.
-In a Spring MVC application the `Servlet` is an instance of {spring-framework-reference-url}web.html#mvc-servlet[`DispatcherServlet`].
-At most one `Servlet` can handle a single `HttpServletRequest` and `HttpServletResponse`.
-However, more than one `Filter` can be used to:
-
-* Prevent downstream ``Filter``s or the `Servlet` from being invoked.
-In this instance the `Filter` will typically write the `HttpServletResponse`.
-* Modify the `HttpServletRequest` or `HttpServletResponse` used by the downstream ``Filter``s and `Servlet`
-
-The power of the `Filter` comes from the `FilterChain` that is passed into it.
-
-.`FilterChain` Usage Example
-====
-.Java
-[source,java,role="primary"]
-----
-public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
-	// do something before the rest of the application
-    chain.doFilter(request, response); // invoke the rest of the application
-    // do something after the rest of the application
-}
-----
-
-.Kotlin
-[source,kotlin,role="secondary"]
-----
-fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
-    // do something before the rest of the application
-    chain.doFilter(request, response) // invoke the rest of the application
-    // do something after the rest of the application
-}
-----
-====
-
-Since a `Filter` only impacts downstream ``Filter``s and the `Servlet`, the order each `Filter` is invoked is extremely important.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/index.adoc
deleted file mode 100644
index 38b639f9b2..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/index.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[servlet-architecture]]
-= Servlet Security: The Big Picture
-:figures: images/servlet/architecture
-
-This section discusses Spring Security's high level architecture within Servlet based applications.
-We build on this high level understanding within <<servlet-authentication>>, <<servlet-authorization>>, <<servlet-exploits>> sections of the reference.
-// FIXME: Add links to other sections of architecture
-
-include::filters.adoc[leveloffset=+1]
-
-include::delegating-filter-proxy.adoc[leveloffset=+1]
-
-include::filter-chain-proxy.adoc[leveloffset=+1]
-
-include::security-filter-chain.adoc[leveloffset=+1]
-
-include::security-filters.adoc[leveloffset=+1]
-
-include::exception-translation-filter.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filter-chain.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filter-chain.adoc
deleted file mode 100644
index 508e9e3d21..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filter-chain.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[servlet-securityfilterchain]]
-= SecurityFilterChain
-
-{security-api-url}org/springframework/security/web/SecurityFilterChain.html[`SecurityFilterChain`] is used by <<servlet-filterchainproxy>> to determine which Spring Security ``Filter``s should be invoked for this request.
-
-.SecurityFilterChain
-[[servlet-securityfilterchain-figure]]
-image::{figures}/securityfilterchain.png[]
-
-The <<servlet-security-filters,Security Filters>> in `SecurityFilterChain` are typically Beans, but they are registered with `FilterChainProxy` instead of <<servlet-delegatingfilterproxy>>.
-`FilterChainProxy` provides a number of advantages to registering directly with the Servlet container or <<servlet-delegatingfilterproxy>>.
-First, it provides a starting point for all of Spring Security's Servlet support.
-For that reason, if you are attempting to troubleshoot Spring Security's Servlet support, adding a debug point in `FilterChainProxy` is a great place to start.
-
-Second, since `FilterChainProxy` is central to Spring Security usage it can perform tasks that are not viewed as optional.
-// FIXME: Add a link to SecurityContext
-For example, it clears out the `SecurityContext` to avoid memory leaks.
-It also applies Spring Security's <<servlet-httpfirewall,`HttpFirewall`>> to protect applications against certain types of attacks.
-
-In addition, it provides more flexibility in determining when a `SecurityFilterChain` should be invoked.
-In a Servlet container, ``Filter``s are invoked based upon the URL alone.
-// FIXME: Link to RequestMatcher
-However, `FilterChainProxy` can determine invocation based upon anything in the `HttpServletRequest` by leveraging the `RequestMatcher` interface.
-
-In fact, `FilterChainProxy` can be used to determine which `SecurityFilterChain` should be used.
-This allows providing a totally separate configuration for different _slices_ of your application.
-
-.Multiple SecurityFilterChain
-[[servlet-multi-securityfilterchain-figure]]
-image::{figures}/multi-securityfilterchain.png[]
-
-In the <<servlet-multi-securityfilterchain-figure>> Figure `FilterChainProxy` decides which `SecurityFilterChain` should be used.
-Only the first `SecurityFilterChain` that matches will be invoked.
-If a URL of `/api/messages/` is requested, it will first match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so only `SecurityFilterChain~0~` will be invoked even though it also matches on ``SecurityFilterChain~n~``.
-If a URL of `/messages/` is requested, it will not match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so `FilterChainProxy` will continue trying each `SecurityFilterChain`.
-Assuming that no other, `SecurityFilterChain` instances match `SecurityFilterChain~n~` will be invoked.
-// FIXME add link to pattern matching
-
-Notice that `SecurityFilterChain~0~` has only three security ``Filter``s instances configured.
-However, `SecurityFilterChain~n~` has four security ``Filter``s configured.
-It is important to note that each `SecurityFilterChain` can be unique and configured in isolation.
-In fact, a `SecurityFilterChain` might have zero security ``Filter``s if the application wants Spring Security to ignore certain requests.
-// FIXME: add link to configuring multiple `SecurityFilterChain` instances
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filters.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filters.adoc
deleted file mode 100644
index 408ec40637..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filters.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[servlet-security-filters]]
-= Security Filters
-
-The Security Filters are inserted into the <<servlet-filterchainproxy>> with the <<servlet-securityfilterchain>> API.
-The <<servlet-filters-review,order of ``Filter``>>s matters.
-It is typically not necessary to know the ordering of Spring Security's ``Filter``s.
-However, there are times that it is beneficial to know the ordering
-
-Below is a comprehensive list of Spring Security Filter ordering:
-
-* ChannelProcessingFilter
-* WebAsyncManagerIntegrationFilter
-* SecurityContextPersistenceFilter
-* HeaderWriterFilter
-* CorsFilter
-* CsrfFilter
-* LogoutFilter
-* OAuth2AuthorizationRequestRedirectFilter
-* Saml2WebSsoAuthenticationRequestFilter
-* X509AuthenticationFilter
-* AbstractPreAuthenticatedProcessingFilter
-* CasAuthenticationFilter
-* OAuth2LoginAuthenticationFilter
-* Saml2WebSsoAuthenticationFilter
-* <<servlet-authentication-usernamepasswordauthenticationfilter,`UsernamePasswordAuthenticationFilter`>>
-* OpenIDAuthenticationFilter
-* DefaultLoginPageGeneratingFilter
-* DefaultLogoutPageGeneratingFilter
-* ConcurrentSessionFilter
-* <<servlet-authentication-digest,`DigestAuthenticationFilter`>>
-* BearerTokenAuthenticationFilter
-* <<servlet-authentication-basic,`BasicAuthenticationFilter`>>
-* RequestCacheAwareFilter
-* SecurityContextHolderAwareRequestFilter
-* JaasApiIntegrationFilter
-* RememberMeAuthenticationFilter
-* AnonymousAuthenticationFilter
-* OAuth2AuthorizationCodeGrantFilter
-* SessionManagementFilter
-* <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>>
-* <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>>
-* SwitchUserFilter
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc
deleted file mode 100644
index a3a8a48d18..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[servlet-authentication-abstractprocessingfilter]]
-= AbstractAuthenticationProcessingFilter
-:figures: images/servlet/authentication/architecture
-:icondir: images/icons
-
-{security-api-url}org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.html[`AbstractAuthenticationProcessingFilter`] is used as a base `Filter` for authenticating a user's credentials.
-Before the credentials can be authenticated, Spring Security typically requests the credentials using <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
-
-Next, the `AbstractAuthenticationProcessingFilter` can authenticate any authentication requests that are submitted to it.
-
-image::{figures}/abstractauthenticationprocessingfilter.png[]
-
-image:{icondir}/number_1.png[] When the user submits their credentials, the `AbstractAuthenticationProcessingFilter` creates an <<servlet-authentication-authentication,`Authentication`>> from the `HttpServletRequest` to be authenticated.
-The type of `Authentication` created depends on the subclass of `AbstractAuthenticationProcessingFilter`.
-For example, <<servlet-authentication-usernamepasswordauthenticationfilter,`UsernamePasswordAuthenticationFilter`>> creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`.
-
-image:{icondir}/number_2.png[] Next, the <<servlet-authentication-authentication,`Authentication`>> is passed into the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to be authenticated.
-
-image:{icondir}/number_3.png[] If authentication fails, then __Failure__
-
-* The <<servlet-authentication-securitycontextholder>> is cleared out.
-* `RememberMeServices.loginFail` is invoked.
-If remember me is not configured, this is a no-op.
-// FIXME: link to rememberme
-* `AuthenticationFailureHandler` is invoked.
-// FIXME: link to AuthenticationFailureHandler
-
-image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
-
-* `SessionAuthenticationStrategy` is notified of a new log in.
-// FIXME: Add link to SessionAuthenticationStrategy
-* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
-Later the `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession`.
-// FIXME: link securitycontextpersistencefilter
-* `RememberMeServices.loginSuccess` is invoked.
-If remember me is not configured, this is a no-op.
-// FIXME: link to rememberme
-* `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`.
-* `AuthenticationSuccessHandler` is invoked.
-// FIXME: link to AuthenticationSuccessHandler
-
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc
deleted file mode 100644
index cdc00dddbc..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[servlet-authentication-authenticationentrypoint]]
-= Request Credentials with `AuthenticationEntryPoint`
-
-
-{security-api-url}org/springframework/security/web/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`] is used to send an HTTP response that requests credentials from a client.
-
-Sometimes a client will proactively include credentials such as a username/password to request a resource.
-In these cases, Spring Security does not need to provide an HTTP response that requests credentials from the client since they are already included.
-
-In other cases, a client will make an unauthenticated request to a resource that they are not authorized to access.
-In this case, an implementation of `AuthenticationEntryPoint` is used to request credentials from the client.
-The `AuthenticationEntryPoint` implementation might perform a <<servlet-authentication-form,redirect to a log in page>>, respond with an <<servlet-authentication-basic,WWW-Authenticate>> header, etc.
-
-
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-manager.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-manager.adoc
deleted file mode 100644
index 5c85382b71..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-manager.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[servlet-authentication-authenticationmanager]]
-= AuthenticationManager
-
-{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform  <<authentication,authentication>>.
-The <<servlet-authentication-authentication,`Authentication`>> that is returned is then set on the <<servlet-authentication-securitycontextholder>> by the controller (i.e. <<servlet-security-filters,Spring Security's ``Filters``s>>) that invoked the `AuthenticationManager`.
-If you are not integrating with __Spring Security's ``Filters``s__ you can set the `SecurityContextHolder` directly and are not required to use an `AuthenticationManager`.
-
-While the implementation of `AuthenticationManager` could be anything, the most common implementation is <<servlet-authentication-providermanager,`ProviderManager`>>.
-// FIXME: add configuration
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-provider.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-provider.adoc
deleted file mode 100644
index c7cb0b7b6c..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-provider.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-[[servlet-authentication-authenticationprovider]]
-= AuthenticationProvider
-
-Multiple {security-api-url}org/springframework/security/authentication/AuthenticationProvider.html[``AuthenticationProvider``s] can be injected into <<servlet-authentication-providermanager,`ProviderManager`>>.
-Each `AuthenticationProvider` performs a specific type of authentication.
-For example, <<servlet-authentication-daoauthenticationprovider,`DaoAuthenticationProvider`>> supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication.adoc
deleted file mode 100644
index 878ecc2481..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[servlet-authentication-authentication]]
-= Authentication
-
-The {security-api-url}org/springframework/security/core/Authentication.html[`Authentication`] serves two main purposes within Spring Security:
-
-* An input to <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to provide the credentials a user has provided to authenticate.
-When used in this scenario, `isAuthenticated()` returns `false`.
-* Represents the currently authenticated user.
-The current `Authentication` can be obtained from the <<servlet-authentication-securitycontext>>.
-
-The `Authentication` contains:
-
-* `principal` - identifies the user.
-When authenticating with a username/password this is often an instance of <<servlet-authentication-userdetails,`UserDetails`>>.
-* `credentials` - often a password.
-In many cases this will be cleared after the user is authenticated to ensure it is not leaked.
-* `authorities` - the <<servlet-authentication-granted-authority,``GrantedAuthority``s>> are high level permissions the user is granted.
-A few examples are roles or scopes.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/granted-authority.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/granted-authority.adoc
deleted file mode 100644
index 19b45cd049..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/granted-authority.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[servlet-authentication-granted-authority]]
-= GrantedAuthority
-{security-api-url}org/springframework/security/core/GrantedAuthority.html[``GrantedAuthority``s] are high level permissions the user is granted. A few examples are roles or scopes.
-
-``GrantedAuthority``s can be obtained from the <<servlet-authentication-authentication,`Authentication.getAuthorities()`>> method.
-This method provides a `Collection` of `GrantedAuthority` objects.
-A `GrantedAuthority` is, not surprisingly, an authority that is granted to the principal.
-Such authorities are usually "roles", such as `ROLE_ADMINISTRATOR` or `ROLE_HR_SUPERVISOR`.
-These roles are later on configured for web authorization, method authorization and domain object authorization.
-Other parts of Spring Security are capable of interpreting these authorities, and expect them to be present.
-When using username/password based authentication ``GrantedAuthority``s are usually loaded by the <<servlet-authentication-userdetailsservice,`UserDetailsService`>>.
-
-Usually the `GrantedAuthority` objects are application-wide permissions.
-They are not specific to a given domain object.
-Thus, you wouldn't likely have a `GrantedAuthority` to represent a permission to `Employee` object number 54, because if there are thousands of such authorities you would quickly run out of memory (or, at the very least, cause the application to take a long time to authenticate a user).
-Of course, Spring Security is expressly designed to handle this common requirement, but you'd instead use the project's domain object security capabilities for this purpose.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/index.adoc
deleted file mode 100644
index 4df295e609..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/index.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-include::security-context-holder.adoc[leveloffset=+1]
-
-include::security-context.adoc[leveloffset=+1]
-
-include::authentication.adoc[leveloffset=+1]
-
-include::granted-authority.adoc[leveloffset=+1]
-
-include::authentication-manager.adoc[leveloffset=+1]
-
-include::provider-manager.adoc[leveloffset=+1]
-
-include::authentication-provider.adoc[leveloffset=+1]
-
-include::authentication-entry-point.adoc[leveloffset=+1]
-
-// FIXME: authenticationsuccesshandler
-// FIXME: authenticationfailurehandler
-
-include::abstract-authentication-processing-filter.adoc[leveloffset=+1]
-
-// daoauthenticationprovider (goes in username/password)
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/provider-manager.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/provider-manager.adoc
deleted file mode 100644
index 4ed8cb4615..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/provider-manager.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[servlet-authentication-providermanager]]
-= ProviderManager
-:figures: images/servlet/authentication/architecture
-
-{security-api-url}org/springframework/security/authentication/ProviderManager.html[`ProviderManager`] is the most commonly used implementation of <<servlet-authentication-authenticationmanager,`AuthenticationManager`>>.
-`ProviderManager` delegates to a `List` of <<servlet-authentication-authenticationprovider,``AuthenticationProvider``s>>.
-// FIXME: link to AuthenticationProvider
-Each `AuthenticationProvider` has an opportunity to indicate that authentication should be successful, fail, or indicate it cannot make a decision and allow a downstream `AuthenticationProvider` to decide.
-If none of the configured ``AuthenticationProvider``s can authenticate, then authentication will fail with a `ProviderNotFoundException` which is a special `AuthenticationException` that indicates the `ProviderManager` was not configured to support the type of `Authentication` that was passed into it.
-
-image::{figures}/providermanager.png[]
-
-In practice each `AuthenticationProvider` knows how to perform a specific type of authentication.
- For example, one `AuthenticationProvider` might be able to validate a username/password, while another might be able to authenticate a SAML assertion.
-This allows each `AuthenticationProvider` to do a very specific type of authentication, while supporting multiple types of authentication and only exposing a single `AuthenticationManager` bean.
-
-`ProviderManager` also allows configuring an optional parent `AuthenticationManager` which is consulted in the event that no `AuthenticationProvider` can perform authentication.
-The parent can be any type of `AuthenticationManager`, but it is often an instance of `ProviderManager`.
-
-image::{figures}/providermanager-parent.png[]
-
-In fact, multiple `ProviderManager` instances might share the same parent `AuthenticationManager`.
-This is somewhat common in scenarios where there are multiple <<servlet-securityfilterchain,`SecurityFilterChain`>> instances that have some authentication in common (the shared parent `AuthenticationManager`), but also different authentication mechanisms (the different `ProviderManager` instances).
-
-image::{figures}/providermanagers-parent.png[]
-
-[[servlet-authentication-providermanager-erasing-credentials]]
-By default `ProviderManager` will attempt to clear any sensitive credentials information from the `Authentication` object which is returned by a successful authentication request.
-This prevents information like passwords being retained longer than necessary in the `HttpSession`.
-
-This may cause issues when you are using a cache of user objects, for example, to improve performance in a stateless application.
-If the `Authentication` contains a reference to an object in the cache (such as a `UserDetails` instance) and this has its credentials removed, then it will no longer be possible to authenticate against the cached value.
-You need to take this into account if you are using a cache.
-An obvious solution is to make a copy of the object first, either in the cache implementation or in the `AuthenticationProvider` which creates the returned `Authentication` object.
-Alternatively, you can disable the `eraseCredentialsAfterAuthentication` property on `ProviderManager`.
-See the {security-api-url}org/springframework/security/authentication/ProviderManager.html[Javadoc] for more information.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc
deleted file mode 100644
index 60198d48f6..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[servlet-authentication-securitycontextholder]]
-= SecurityContextHolder
-
-:figures: images/servlet/authentication/architecture
-
-At the heart of Spring Security's authentication model is the `SecurityContextHolder`.
-It contains the <<servlet-authentication-securitycontext>>.
-
-image::{figures}/securitycontextholder.png[]
-
-The `SecurityContextHolder` is where Spring Security stores the details of who is <<authentication,authenticated>>.
-Spring Security does not care how the `SecurityContextHolder` is populated.
-If it contains a value, then it is used as the currently authenticated user.
-
-The simplest way to indicate a user is authenticated is to set the `SecurityContextHolder` directly.
-
-.Setting `SecurityContextHolder`
-====
-.Java
-[source,java,role="primary"]
-----
-SecurityContext context = SecurityContextHolder.createEmptyContext(); // <1>
-Authentication authentication =
-    new TestingAuthenticationToken("username", "password", "ROLE_USER"); // <2>
-context.setAuthentication(authentication);
-
-SecurityContextHolder.setContext(context); // <3>
-----
-
-.Kotlin
-[source,kotlin,role="secondary"]
-----
-val context: SecurityContext = SecurityContextHolder.createEmptyContext() // <1>
-val authentication: Authentication = TestingAuthenticationToken("username", "password", "ROLE_USER") // <2>
-context.authentication = authentication
-
-SecurityContextHolder.setContext(context) // <3>
-----
-====
-
-<1> We start by creating an empty `SecurityContext`.
-It is important to create a new `SecurityContext` instance instead of using `SecurityContextHolder.getContext().setAuthentication(authentication)` to avoid race conditions across multiple threads.
-<2> Next we create a new <<servlet-authentication-authentication,`Authentication`>> object.
-Spring Security does not care what type of `Authentication` implementation is set on the `SecurityContext`.
-Here we use `TestingAuthenticationToken` because it is very simple.
-A more common production scenario is `UsernamePasswordAuthenticationToken(userDetails, password, authorities)`.
-<3> Finally, we set the `SecurityContext` on the `SecurityContextHolder`.
-Spring Security will use this information for <<servlet-authorization,authorization>>.
-
-If you wish to obtain information about the authenticated principal, you can do so by accessing the `SecurityContextHolder`.
-
-.Access Currently Authenticated User
-====
-.Java
-[source,java,role="primary"]
-----
-SecurityContext context = SecurityContextHolder.getContext();
-Authentication authentication = context.getAuthentication();
-String username = authentication.getName();
-Object principal = authentication.getPrincipal();
-Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();
-----
-
-.Kotlin
-[source,kotlin,role="secondary"]
-----
-val context = SecurityContextHolder.getContext()
-val authentication = context.authentication
-val username = authentication.name
-val principal = authentication.principal
-val authorities = authentication.authorities
-----
-====
-
-// FIXME: add links to HttpServletRequest.getRemoteUser() and @CurrentSecurityContext @AuthenticationPrincipal
-
-By default the `SecurityContextHolder` uses a `ThreadLocal` to store these details, which means that the `SecurityContext` is always available to methods in the same thread, even if the `SecurityContext` is not explicitly passed around as an argument to those methods.
-Using a `ThreadLocal` in this way is quite safe if care is taken to clear the thread after the present principal's request is processed.
-Spring Security's <<servlet-filterchainproxy,FilterChainProxy>> ensures that the `SecurityContext` is always cleared.
-
-Some applications aren't entirely suitable for using a `ThreadLocal`, because of the specific way they work with threads.
-For example, a Swing client might want all threads in a Java Virtual Machine to use the same security context.
-`SecurityContextHolder` can be configured with a strategy on startup to specify how you would like the context to be stored.
-For a standalone application you would use the `SecurityContextHolder.MODE_GLOBAL` strategy.
-Other applications might want to have threads spawned by the secure thread also assume the same security identity.
-This is achieved by using `SecurityContextHolder.MODE_INHERITABLETHREADLOCAL`.
-You can change the mode from the default `SecurityContextHolder.MODE_THREADLOCAL` in two ways.
-The first is to set a system property, the second is to call a static method on `SecurityContextHolder`.
-Most applications won't need to change from the default, but if you do, take a look at the Javadoc for `SecurityContextHolder` to learn more.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context.adoc
deleted file mode 100644
index 955cf70d28..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-[[servlet-authentication-securitycontext]]
-= SecurityContext
-
-The {security-api-url}org/springframework/security/core/context/SecurityContext.html[`SecurityContext`] is obtained from the <<servlet-authentication-securitycontextholder>>.
-The `SecurityContext` contains an <<servlet-authentication-authentication>> object.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/index.adoc
deleted file mode 100644
index abd8e400c4..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/index.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[servlet-authentication]]
-= Authentication
-
-Spring Security provides comprehensive support for <<authentication>>.
-This section discusses:
-
-[[servlet-authentication-architecture]]
-*Architecture Components*
-
-This section describes the main architectural components of Spring Security's used in Servlet authentication.
-If you need concrete flows that explain how these pieces fit together, look at the <<servlet-authentication-mechanisms,Authentication Mechanism>> specific sections.
-
-* <<servlet-authentication-securitycontextholder>> - the `SecurityContextHolder` is where Spring Security stores the details of who is <<authentication,authenticated>>.
-* <<servlet-authentication-securitycontext>> - is obtained from the `SecurityContextHolder` and contains the `Authentication` of the currently authenticated user.
-* <<servlet-authentication-authentication>> - can be the input to `AuthenticationManager` to provide the credentials a user has provided to authenticate or the current user from the `SecurityContext`.
-* <<servlet-authentication-granted-authority>> - an authority that is granted to the principal on the `Authentication` (i.e. roles, scopes, etc.)
-* <<servlet-authentication-authenticationmanager>> - the API that defines how Spring Security's Filters perform  <<authentication,authentication>>.
-* <<servlet-authentication-providermanager>> - the most common implementation of `AuthenticationManager`.
-* <<servlet-authentication-authenticationprovider>> - used by `ProviderManager` to perform a specific type of authentication.
-* <<servlet-authentication-authenticationentrypoint>> - used for requesting credentials from a client (i.e. redirecting to a log in page, sending a `WWW-Authenticate` response, etc.)
-* <<servlet-authentication-abstractprocessingfilter>> - a base `Filter` used for authentication.
-This also gives a good idea of the high level flow of authentication and how pieces work together.
-
-[[servlet-authentication-mechanisms]]
-*Authentication Mechanisms*
-
-// FIXME: brief description
-
-* <<servlet-authentication-unpwd,Username and Password>> - how to authenticate with a username/password
-* <<oauth2login,OAuth 2.0 Login>> - OAuth 2.0 Log In with OpenID Connect and non-standard OAuth 2.0 Login (i.e. GitHub)
-* <<servlet-saml2,SAML 2.0 Login>> - SAML 2.0 Log In
-* <<servlet-cas,Central Authentication Server (CAS)>> - Central Authentication Server (CAS) Support
-* <<servlet-rememberme, Remember Me>> - how to remember a user past session expiration
-* <<servlet-jaas, JAAS Authentication>> - authenticate with JAAS
-* <<servlet-openid,OpenID>> - OpenID Authentication (not to be confused with OpenID Connect)
-* <<servlet-preauth>> - authenticate with an external mechanism such as https://www.siteminder.com/[SiteMinder] or Java EE security but still use Spring Security for authorization and protection against common exploits.
-* <<servlet-x509,X509 Authentication>> - X509 Authentication
-
-// FIXME: Add other mechanisms
-
-// We intentionally do not increase leveloffset, this is just for organization vs document structure
-include::architecture/index.adoc[]
-
-include::unpwd/index.adoc[leveloffset=+1]
-
-include::session-management.adoc[]
-
-include::rememberme.adoc[]
-
-include::openid.adoc[]
-
-include::anonymous.adoc[]
-
-include::preauth.adoc[]
-
-include::jaas.adoc[]
-
-include::cas.adoc[]
-
-include::x509.adoc[]
-
-include::runas.adoc[]
-
-include::logout.adoc[]
-
-include::events.adoc[]
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
deleted file mode 100644
index 3818a019ac..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/dao-authentication-provider.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[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`.
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
deleted file mode 100644
index 415d828118..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/index.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[servlet-authentication-unpwd]]
-= Username/Password Authentication
-:figures: images/servlet/authentication/unpwd
-:icondir: images/icons
-
-One of the most common ways to authenticate a user is by validating a username and password.
-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>>
-* Custom data stores with <<servlet-authentication-userdetailsservice>>
-* LDAP storage with <<servlet-authentication-ldap>>
-
-include::form.adoc[leveloffset=+1]
-
-include::basic.adoc[leveloffset=+1]
-
-include::digest.adoc[leveloffset=+1]
-
-include::in-memory.adoc[leveloffset=+1]
-
-include::jdbc.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
deleted file mode 100644
index 73f9e1f2e1..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/password-encoder.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-[[servlet-authentication-password-storage]]
-= PasswordEncoder
-
-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>>.
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
deleted file mode 100644
index d56626b37e..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-[[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`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc
deleted file mode 100644
index bc955238c2..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[servlet-exploits]]
-= Protection Against Exploits
-
-include::csrf.adoc[leveloffset=+1]
-
-include::headers.adoc[leveloffset=+1]
-
-include::http.adoc[leveloffset=+1]
-
-include::firewall.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc
deleted file mode 100644
index fa8d861b0b..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/index.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-= Servlet Applications
-
-Spring Security integrates with the Servlet Container by using a standard Servlet `Filter`. This means it works with any application that runs in a Servlet Container. More concretely, you do not need to use Spring in your Servlet-based application to take advantage of Spring Security.
-
-include::hello/index.adoc[leveloffset=+1]
-
-include::architecture/index.adoc[leveloffset=+1]
-
-include::authentication/index.adoc[leveloffset=+1]
-
-include::authorization/index.adoc[leveloffset=+1]
-
-include::oauth2/index.adoc[leveloffset=+1]
-
-include::saml2/index.adoc[leveloffset=+1]
-
-include::exploits/index.adoc[leveloffset=+1]
-
-include::integrations/index.adoc[leveloffset=+1]
-
-include::java-configuration/index.adoc[leveloffset=+1]
-
-include::kotlin-configuration/index.adoc[leveloffset=+1]
-
-include::namespace/index.adoc[leveloffset=+1]
-
-include::test/index.adoc[leveloffset=+1]
-
-include::crypto/index.adoc[leveloffset=+1]
-
-include::appendix/index.adoc[leveloffset=+1]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/index.adoc
deleted file mode 100644
index 90b9783a1f..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/index.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= Integrations
-
-include::servlet-api.adoc[]
-
-include::data.adoc[]
-
-include::concurrency.adoc[]
-
-include::jackson.adoc[]
-
-include::localization.adoc[]
-
-include::mvc.adoc[]
-
-include::websocket.adoc[]
-
-include::cors.adoc[]
-
-include::jsp-taglibs.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/index.adoc
deleted file mode 100644
index 99ed0947d9..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/index.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= OAuth2
-
-include::oauth2-login.adoc[]
-
-include::oauth2-client.adoc[]
-
-include::oauth2-resourceserver.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/index.adoc
deleted file mode 100644
index e872f5d9d8..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-[[servlet-saml2]]
-= SAML2
-
-include::saml2-login.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/test/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/test/index.adoc
deleted file mode 100644
index da7d74db4a..0000000000
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/test/index.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[test]]
-= Testing
-
-This section describes the testing support provided by Spring Security.
-
-[TIP]
-====
-To use the Spring Security test support, you must include `spring-security-test-{spring-security-version}.jar` as a dependency of your project.
-====
-
-include::method.adoc[]
-
-include::mockmvc.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/css/style.css b/docs/manual/src/docs/asciidoc/css/style.css
deleted file mode 100644
index 45650c46df..0000000000
--- a/docs/manual/src/docs/asciidoc/css/style.css
+++ /dev/null
@@ -1,5 +0,0 @@
-@import 'spring.css';
-
-a code {
-	color: #097dff;
-}
diff --git a/docs/manual/src/docs/asciidoc/index-docinfo.xml b/docs/manual/src/docs/asciidoc/index-docinfo.xml
deleted file mode 100644
index 9a041505ba..0000000000
--- a/docs/manual/src/docs/asciidoc/index-docinfo.xml
+++ /dev/null
@@ -1,11 +0,0 @@
-<productname>Spring Security</productname>
-<releaseinfo>{spring-security-version}</releaseinfo>
-<copyright>
-	<year>2004-2019</year>
-</copyright>
-<legalnotice>
-	<para>Copies of this document may be made for your own use and for distribution to
-	others, provided that you do not charge any fee for such copies and further provided
-	that each copy contains this Copyright Notice, whether distributed in print or
-	electronically.</para>
-</legalnotice>
diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc
deleted file mode 100644
index 5536b762e4..0000000000
--- a/docs/manual/src/docs/asciidoc/index.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= Spring Security Reference
-Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert; Joe Grandja; Jay Bryant; Eddú Meléndez; Josh Cummings; Dave Syer; Eleftheria Stein
-:include-dir: _includes
-:source-indent: 0
-:tabsize: 4
-:toc: left
-
-// FIXME: Add links for authentication, authorization, common attacks
-Spring Security is a framework that provides authentication, authorization, and protection against common attacks.
-// FIXME: Add links for imperative and reactive applications
-With first class support for both imperative and reactive applications, it is the de-facto standard for securing Spring-based applications.
-
-include::{include-dir}/about/index.adoc[]
-
-include::{include-dir}/servlet/index.adoc[]
-
-include::{include-dir}/reactive/index.adoc[]
-
-
diff --git a/docs/manual/src/docs/asciidoc/images/Authentication.gif b/docs/modules/ROOT/assets/images/Authentication.gif
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/Authentication.gif
rename to docs/modules/ROOT/assets/images/Authentication.gif
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_1.png b/docs/modules/ROOT/assets/images/icons/number_1.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_1.png
rename to docs/modules/ROOT/assets/images/icons/number_1.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_10.png b/docs/modules/ROOT/assets/images/icons/number_10.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_10.png
rename to docs/modules/ROOT/assets/images/icons/number_10.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_2.png b/docs/modules/ROOT/assets/images/icons/number_2.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_2.png
rename to docs/modules/ROOT/assets/images/icons/number_2.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_3.png b/docs/modules/ROOT/assets/images/icons/number_3.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_3.png
rename to docs/modules/ROOT/assets/images/icons/number_3.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_4.png b/docs/modules/ROOT/assets/images/icons/number_4.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_4.png
rename to docs/modules/ROOT/assets/images/icons/number_4.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_5.png b/docs/modules/ROOT/assets/images/icons/number_5.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_5.png
rename to docs/modules/ROOT/assets/images/icons/number_5.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_6.png b/docs/modules/ROOT/assets/images/icons/number_6.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_6.png
rename to docs/modules/ROOT/assets/images/icons/number_6.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_7.png b/docs/modules/ROOT/assets/images/icons/number_7.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_7.png
rename to docs/modules/ROOT/assets/images/icons/number_7.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_8.png b/docs/modules/ROOT/assets/images/icons/number_8.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_8.png
rename to docs/modules/ROOT/assets/images/icons/number_8.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/number_9.png b/docs/modules/ROOT/assets/images/icons/number_9.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/number_9.png
rename to docs/modules/ROOT/assets/images/icons/number_9.png
diff --git a/docs/manual/src/docs/asciidoc/images/icons/numbers.odg b/docs/modules/ROOT/assets/images/icons/numbers.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/icons/numbers.odg
rename to docs/modules/ROOT/assets/images/icons/numbers.odg
diff --git a/docs/manual/src/docs/asciidoc/images/note.png b/docs/modules/ROOT/assets/images/note.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/note.png
rename to docs/modules/ROOT/assets/images/note.png
diff --git a/docs/manual/src/docs/asciidoc/images/palette.otg b/docs/modules/ROOT/assets/images/palette.otg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/palette.otg
rename to docs/modules/ROOT/assets/images/palette.otg
diff --git a/docs/manual/src/docs/asciidoc/images/s2-banner-rhs.png b/docs/modules/ROOT/assets/images/s2-banner-rhs.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/s2-banner-rhs.png
rename to docs/modules/ROOT/assets/images/s2-banner-rhs.png
diff --git a/docs/manual/src/docs/asciidoc/images/s2_box_logo.png b/docs/modules/ROOT/assets/images/s2_box_logo.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/s2_box_logo.png
rename to docs/modules/ROOT/assets/images/s2_box_logo.png
diff --git a/docs/manual/src/docs/asciidoc/images/security-interception.graffle b/docs/modules/ROOT/assets/images/security-interception.graffle
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/security-interception.graffle
rename to docs/modules/ROOT/assets/images/security-interception.graffle
diff --git a/docs/manual/src/docs/asciidoc/images/security-interception.png b/docs/modules/ROOT/assets/images/security-interception.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/security-interception.png
rename to docs/modules/ROOT/assets/images/security-interception.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/delegatingfilterproxy.odg b/docs/modules/ROOT/assets/images/servlet/architecture/delegatingfilterproxy.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/delegatingfilterproxy.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/delegatingfilterproxy.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/delegatingfilterproxy.png b/docs/modules/ROOT/assets/images/servlet/architecture/delegatingfilterproxy.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/delegatingfilterproxy.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/delegatingfilterproxy.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/exceptiontranslationfilter.odg b/docs/modules/ROOT/assets/images/servlet/architecture/exceptiontranslationfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/exceptiontranslationfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/exceptiontranslationfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/exceptiontranslationfilter.png b/docs/modules/ROOT/assets/images/servlet/architecture/exceptiontranslationfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/exceptiontranslationfilter.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/exceptiontranslationfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.gif b/docs/modules/ROOT/assets/images/servlet/architecture/filterchain.gif
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.gif
rename to docs/modules/ROOT/assets/images/servlet/architecture/filterchain.gif
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.odg b/docs/modules/ROOT/assets/images/servlet/architecture/filterchain.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/filterchain.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.png b/docs/modules/ROOT/assets/images/servlet/architecture/filterchain.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchain.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/filterchain.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchainproxy.odg b/docs/modules/ROOT/assets/images/servlet/architecture/filterchainproxy.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchainproxy.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/filterchainproxy.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchainproxy.png b/docs/modules/ROOT/assets/images/servlet/architecture/filterchainproxy.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/filterchainproxy.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/filterchainproxy.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/multi-securityfilterchain.odg b/docs/modules/ROOT/assets/images/servlet/architecture/multi-securityfilterchain.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/multi-securityfilterchain.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/multi-securityfilterchain.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/multi-securityfilterchain.png b/docs/modules/ROOT/assets/images/servlet/architecture/multi-securityfilterchain.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/multi-securityfilterchain.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/multi-securityfilterchain.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/securityfilterchain.odg b/docs/modules/ROOT/assets/images/servlet/architecture/securityfilterchain.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/securityfilterchain.odg
rename to docs/modules/ROOT/assets/images/servlet/architecture/securityfilterchain.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/architecture/securityfilterchain.png b/docs/modules/ROOT/assets/images/servlet/architecture/securityfilterchain.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/architecture/securityfilterchain.png
rename to docs/modules/ROOT/assets/images/servlet/architecture/securityfilterchain.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.odg b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.png b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/abstractauthenticationprocessingfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager-parent.odg b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager-parent.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager-parent.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager-parent.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager-parent.png b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager-parent.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager-parent.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager-parent.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager.odg b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager.png b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanager.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanager.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanagers-parent.odg b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanagers-parent.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanagers-parent.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanagers-parent.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanagers-parent.png b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanagers-parent.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/providermanagers-parent.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/providermanagers-parent.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/securitycontextholder.odg b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/securitycontextholder.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/securitycontextholder.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/securitycontextholder.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/securitycontextholder.png b/docs/modules/ROOT/assets/images/servlet/authentication/architecture/securitycontextholder.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/architecture/securitycontextholder.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/architecture/securitycontextholder.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationentrypoint.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationentrypoint.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.odg b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.png b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/basicauthenticationfilter.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/basicauthenticationfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.odg b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/daoauthenticationprovider.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/daoauthenticationprovider.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.png b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/daoauthenticationprovider.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/daoauthenticationprovider.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/daoauthenticationprovider.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/loginurlauthenticationentrypoint.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png b/docs/modules/ROOT/assets/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png
rename to docs/modules/ROOT/assets/images/servlet/authentication/unpwd/usernamepasswordauthenticationfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/access-decision-voting.graffle b/docs/modules/ROOT/assets/images/servlet/authorization/access-decision-voting.graffle
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/access-decision-voting.graffle
rename to docs/modules/ROOT/assets/images/servlet/authorization/access-decision-voting.graffle
diff --git a/docs/manual/src/docs/asciidoc/images/access-decision-voting.png b/docs/modules/ROOT/assets/images/servlet/authorization/access-decision-voting.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/access-decision-voting.png
rename to docs/modules/ROOT/assets/images/servlet/authorization/access-decision-voting.png
diff --git a/docs/manual/src/docs/asciidoc/images/after-invocation.graffle b/docs/modules/ROOT/assets/images/servlet/authorization/after-invocation.graffle
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/after-invocation.graffle
rename to docs/modules/ROOT/assets/images/servlet/authorization/after-invocation.graffle
diff --git a/docs/manual/src/docs/asciidoc/images/after-invocation.png b/docs/modules/ROOT/assets/images/servlet/authorization/after-invocation.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/after-invocation.png
rename to docs/modules/ROOT/assets/images/servlet/authorization/after-invocation.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authorization/filtersecurityinterceptor.odg b/docs/modules/ROOT/assets/images/servlet/authorization/filtersecurityinterceptor.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authorization/filtersecurityinterceptor.odg
rename to docs/modules/ROOT/assets/images/servlet/authorization/filtersecurityinterceptor.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/authorization/filtersecurityinterceptor.png b/docs/modules/ROOT/assets/images/servlet/authorization/filtersecurityinterceptor.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/authorization/filtersecurityinterceptor.png
rename to docs/modules/ROOT/assets/images/servlet/authorization/filtersecurityinterceptor.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/beareraccessdeniedhandler.odg b/docs/modules/ROOT/assets/images/servlet/oauth2/beareraccessdeniedhandler.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/beareraccessdeniedhandler.odg
rename to docs/modules/ROOT/assets/images/servlet/oauth2/beareraccessdeniedhandler.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearerauthenticationentrypoint.odg b/docs/modules/ROOT/assets/images/servlet/oauth2/bearerauthenticationentrypoint.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearerauthenticationentrypoint.odg
rename to docs/modules/ROOT/assets/images/servlet/oauth2/bearerauthenticationentrypoint.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearerauthenticationentrypoint.png b/docs/modules/ROOT/assets/images/servlet/oauth2/bearerauthenticationentrypoint.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearerauthenticationentrypoint.png
rename to docs/modules/ROOT/assets/images/servlet/oauth2/bearerauthenticationentrypoint.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearertokenauthenticationfilter.odg b/docs/modules/ROOT/assets/images/servlet/oauth2/bearertokenauthenticationfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearertokenauthenticationfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/oauth2/bearertokenauthenticationfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearertokenauthenticationfilter.png b/docs/modules/ROOT/assets/images/servlet/oauth2/bearertokenauthenticationfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/bearertokenauthenticationfilter.png
rename to docs/modules/ROOT/assets/images/servlet/oauth2/bearertokenauthenticationfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/jwtauthenticationprovider.odg b/docs/modules/ROOT/assets/images/servlet/oauth2/jwtauthenticationprovider.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/jwtauthenticationprovider.odg
rename to docs/modules/ROOT/assets/images/servlet/oauth2/jwtauthenticationprovider.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/jwtauthenticationprovider.png b/docs/modules/ROOT/assets/images/servlet/oauth2/jwtauthenticationprovider.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/jwtauthenticationprovider.png
rename to docs/modules/ROOT/assets/images/servlet/oauth2/jwtauthenticationprovider.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/opaquetokenauthenticationprovider.odg b/docs/modules/ROOT/assets/images/servlet/oauth2/opaquetokenauthenticationprovider.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/opaquetokenauthenticationprovider.odg
rename to docs/modules/ROOT/assets/images/servlet/oauth2/opaquetokenauthenticationprovider.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/oauth2/opaquetokenauthenticationprovider.png b/docs/modules/ROOT/assets/images/servlet/oauth2/opaquetokenauthenticationprovider.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/oauth2/opaquetokenauthenticationprovider.png
rename to docs/modules/ROOT/assets/images/servlet/oauth2/opaquetokenauthenticationprovider.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/opensamlauthenticationprovider.odg b/docs/modules/ROOT/assets/images/servlet/saml2/opensamlauthenticationprovider.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/opensamlauthenticationprovider.odg
rename to docs/modules/ROOT/assets/images/servlet/saml2/opensamlauthenticationprovider.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/opensamlauthenticationprovider.png b/docs/modules/ROOT/assets/images/servlet/saml2/opensamlauthenticationprovider.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/opensamlauthenticationprovider.png
rename to docs/modules/ROOT/assets/images/servlet/saml2/opensamlauthenticationprovider.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationfilter.odg b/docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationfilter.png b/docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationfilter.png
rename to docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationrequestfilter.odg b/docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationrequestfilter.odg
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationrequestfilter.odg
rename to docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationrequestfilter.odg
diff --git a/docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationrequestfilter.png b/docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationrequestfilter.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/servlet/saml2/saml2webssoauthenticationrequestfilter.png
rename to docs/modules/ROOT/assets/images/servlet/saml2/saml2webssoauthenticationrequestfilter.png
diff --git a/docs/manual/src/docs/asciidoc/images/tip.png b/docs/modules/ROOT/assets/images/tip.png
similarity index 100%
rename from docs/manual/src/docs/asciidoc/images/tip.png
rename to docs/modules/ROOT/assets/images/tip.png
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000000..7445e37651
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,105 @@
+* xref:index.adoc[Overview]
+* xref:prerequisites.adoc[Prerequisites]
+* xref:community.adoc[Community]
+* xref:whats-new.adoc[What's New]
+* xref:getting-spring-security.adoc[Getting Spring Security]
+* xref:features/index.adoc[Features]
+** xref:features/authentication/index.adoc[Authentication]
+*** xref:features/authentication/password-storage.adoc[Password Storage]
+** xref:features/exploits/index.adoc[Protection Against Exploits]
+*** xref:features/exploits/csrf.adoc[CSRF]
+*** xref:features/exploits/headers.adoc[HTTP Headers]
+*** xref:features/exploits/http.adoc[HTTP Requests]
+** xref:features/integrations/index.adoc[Integrations]
+*** xref:features/integrations/cryptography.adoc[Cryptography]
+*** xref:features/integrations/data.adoc[Spring Data]
+*** xref:features/integrations/concurrency.adoc[Java's Concurrency APIs]
+*** xref:features/integrations/jackson.adoc[Jackson]
+*** xref:features/integrations/localization.adoc[Localization]
+* xref:modules.adoc[Project Modules]
+* xref:samples.adoc[Samples]
+* xref:servlet/index.adoc[Servlet Applications]
+** xref:servlet/getting-started.adoc[Getting Started]
+** xref:servlet/architecture.adoc[Architecture]
+** xref:servlet/authentication/index.adoc[Authentication]
+*** xref:servlet/authentication/architecture.adoc[Authentication Architecture]
+*** xref:servlet/authentication/passwords/index.adoc[Username/Password]
+**** Reading Username/Password
+***** xref:servlet/authentication/passwords/form.adoc[Form]
+***** xref:servlet/authentication/passwords/basic.adoc[Basic]
+***** xref:servlet/authentication/passwords/digest.adoc[Digest]
+**** Password Storage
+***** xref:servlet/authentication/passwords/in-memory.adoc[In Memory]
+***** xref:servlet/authentication/passwords/jdbc.adoc[JDBC]
+***** xref:servlet/authentication/passwords/user-details.adoc[UserDetails]
+***** xref:servlet/authentication/passwords/user-details-service.adoc[UserDetailsService]
+***** xref:servlet/authentication/passwords/password-encoder.adoc[PasswordEncoder]
+***** xref:servlet/authentication/passwords/dao-authentication-provider.adoc[DaoAuthenticationProvider]
+***** xref:servlet/authentication/passwords/ldap.adoc[LDAP]
+*** xref:servlet/authentication/session-management.adoc[Session Management]
+*** xref:servlet/authentication/rememberme.adoc[Remember Me]
+*** xref:servlet/authentication/openid.adoc[OpenID]
+*** xref:servlet/authentication/anonymous.adoc[Anonymous]
+*** xref:servlet/authentication/preauth.adoc[Pre-Authentication]
+*** xref:servlet/authentication/jaas.adoc[JAAS]
+*** xref:servlet/authentication/cas.adoc[CAS]
+*** xref:servlet/authentication/x509.adoc[X509]
+*** xref:servlet/authentication/runas.adoc[Run-As]
+*** xref:servlet/authentication/logout.adoc[Logout]
+*** xref:servlet/authentication/events.adoc[Authentication Events]
+** xref:servlet/authorization/index.adoc[Authorization]
+*** xref:servlet/authorization/architecture.adoc[Authorization Architecture]
+*** xref:servlet/authorization/authorize-requests.adoc[Authorize HTTP Requests]
+*** xref:servlet/authorization/expression-based.adoc[Expression-Based Access Control]
+*** xref:servlet/authorization/secure-objects.adoc[Secure Object Implementations]
+*** xref:servlet/authorization/method-security.adoc[Method Security]
+*** xref:servlet/authorization/acls.adoc[Domain Object Security ACLs]
+** xref:servlet/oauth2/index.adoc[OAuth2]
+*** xref:servlet/oauth2/oauth2-login.adoc[OAuth2 Log In]
+*** xref:servlet/oauth2/oauth2-client.adoc[OAuth2 Client]
+*** xref:servlet/oauth2/oauth2-resourceserver.adoc[OAuth2 Resource Server]
+** xref:servlet/saml2/index.adoc[SAML2]
+** xref:servlet/exploits/index.adoc[Protection Against Exploits]
+*** xref:servlet/exploits/csrf.adoc[]
+*** xref:servlet/exploits/headers.adoc[]
+*** xref:servlet/exploits/http.adoc[]
+*** xref:servlet/exploits/firewall.adoc[]
+** xref:servlet/integrations/index.adoc[Integrations]
+*** xref:servlet/integrations/servlet-api.adoc[Servlet APIs]
+*** xref:servlet/integrations/mvc.adoc[Spring MVC]
+*** xref:servlet/integrations/websocket.adoc[WebSocket]
+*** xref:servlet/integrations/cors.adoc[Spring's CORS Support]
+*** xref:servlet/integrations/jsp-taglibs.adoc[JSP Taglib]
+** Configuration
+*** xref:servlet/configuration/java.adoc[Java Configuration]
+*** xref:servlet/configuration/kotlin.adoc[Kotlin Configuration]
+*** xref:servlet/configuration/xml-namespace.adoc[Namespace Configuration]
+** xref:servlet/test/index.adoc[Testing]
+*** xref:servlet/test/method.adoc[Method Security]
+*** xref:servlet/test/mockmvc.adoc[MockMvc Support]
+** xref:servlet/appendix/index.adoc[Appendix]
+*** xref:servlet/appendix/database-schema.adoc[Database Schemas]
+*** xref:servlet/appendix/namespace.adoc[XML Namespace]
+*** xref:servlet/appendix/faq.adoc[FAQ]
+* xref:reactive/index.adoc[Reactive Applications]
+** xref:reactive/getting-started.adoc[Getting Started]
+** Authentication
+*** xref:reactive/authentication/x509.adoc[X.509 Authentication]
+*** xref:reactive/authentication/logout.adoc[Logout]
+** Authorization
+*** xref:reactive/authorization/method.adoc[EnableReactiveMethodSecurity]
+** xref:reactive/oauth2/index.adoc[OAuth2]
+*** xref:reactive/oauth2/login.adoc[OAuth 2.0 Login]
+*** xref:reactive/oauth2/access-token.adoc[OAuth2 Client]
+*** xref:reactive/oauth2/resource-server.adoc[OAuth 2.0 Resource Server]
+*** xref:reactive/registered-oauth2-authorized-client.adoc[@RegisteredOAuth2AuthorizedClient]
+** xref:reactive/exploits/index.adoc[Protection Against Exploits]
+*** xref:reactive/exploits/csrf.adoc[CSRF]
+*** xref:reactive/exploits/headers.adoc[Headers]
+*** xref:reactive/exploits/http.adoc[HTTP Requests]
+** Integrations
+*** xref:reactive/integrations/cors.adoc[CORS]
+*** xref:reactive/integrations/rsocket.adoc[RSocket]
+*** xref:reactive/integrations/webclient.adoc[WebClient]
+** xref:reactive/test.adoc[Testing]
+** xref:reactive/configuration/webflux.adoc[WebFlux Security]
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/community.adoc b/docs/modules/ROOT/pages/community.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/about/community.adoc
rename to docs/modules/ROOT/pages/community.adoc
index 893d17727b..ee21f4ea20 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/community.adoc
+++ b/docs/modules/ROOT/pages/community.adoc
@@ -11,7 +11,7 @@ If you need help with Spring Security, we are here to help.
 The following are some of the best ways to get help:
 
 * Read through this documentation.
-* Try one of our many <<samples,sample applications>>.
+* Try one of our many xref:samples.adoc#samples[sample applications].
 * Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag.
 * Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/authentication/index.adoc b/docs/modules/ROOT/pages/features/authentication/index.adoc
similarity index 54%
rename from docs/manual/src/docs/asciidoc/_includes/about/authentication/index.adoc
rename to docs/modules/ROOT/pages/features/authentication/index.adoc
index 2d7cf93798..fb4cc5cab9 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/authentication/index.adoc
+++ b/docs/modules/ROOT/pages/features/authentication/index.adoc
@@ -5,8 +5,7 @@ Spring Security provides comprehensive support for https://en.wikipedia.org/wiki
 Authentication is how we verify the identity of who is trying to access a particular resource.
 A common way to authenticate users is by requiring the user to enter a username and password.
 Once authentication is performed we know the identity and can perform authorization.
-// FIXME: Link authorization to authorization
 
-include::supported.adoc[leveloffset=+1]
-
-include::password-storage.adoc[leveloffset=+1]
+Spring Security provides built in support for authenticating users.
+This section is dedicated to generic authentication support that applies in both Servlet and WebFlux environments.
+Refer to the sections on authentication for xref:servlet/authentication/index.adoc#servlet-authentication[Servlet] and WebFlux for details on what is supported for each stack.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc b/docs/modules/ROOT/pages/features/authentication/password-storage.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc
rename to docs/modules/ROOT/pages/features/authentication/password-storage.adoc
diff --git a/docs/modules/ROOT/pages/features/authorization/index.adoc b/docs/modules/ROOT/pages/features/authorization/index.adoc
new file mode 100644
index 0000000000..d3c1d39328
--- /dev/null
+++ b/docs/modules/ROOT/pages/features/authorization/index.adoc
@@ -0,0 +1,14 @@
+[[authorization]]
+= Authorization
+
+Spring Security provides comprehensive support for https://en.wikipedia.org/wiki/Authorization[authorization].
+Authorization is determining who is allowed to access a particular resource.
+Spring Security provides https://en.wikipedia.org/wiki/Defense_in_depth_(computing)[defense in depth] by allowing for request based authorization and method based authorization.
+
+[[authorization-request]]
+== Request Based Authorization
+
+Spring Security provides authorization based upon the request for both xref:servlet/authorization/index.adoc[Servlet] and WebFlux environments.
+
+[[authorization-method]]
+== Method Based Authorization
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc b/docs/modules/ROOT/pages/features/exploits/csrf.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc
rename to docs/modules/ROOT/pages/features/exploits/csrf.adoc
index 026faecde6..8c9517363e 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc
+++ b/docs/modules/ROOT/pages/features/exploits/csrf.adoc
@@ -14,7 +14,7 @@ In the following sections we will explore:
 [NOTE]
 ====
 This portion of the documentation discusses the general topic of CSRF protection.
-Refer to the relevant sections for specific information on CSRF protection for <<servlet-csrf,servlet>> and <<webflux-csrf,WebFlux>> based applications.
+Refer to the relevant sections for specific information on CSRF protection for xref:servlet/exploits/csrf.adoc#servlet-csrf[servlet] and xref:reactive/exploits/csrf.adoc#webflux-csrf[WebFlux] based applications.
 ====
 
 [[csrf-explained]]
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc b/docs/modules/ROOT/pages/features/exploits/headers.adoc
similarity index 85%
rename from docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc
rename to docs/modules/ROOT/pages/features/exploits/headers.adoc
index 565272a29c..be19d3028c 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc
+++ b/docs/modules/ROOT/pages/features/exploits/headers.adoc
@@ -4,7 +4,7 @@
 [NOTE]
 ====
 This portion of the documentation discusses the general topic of Security HTTP Response Headers.
-Refer to the relevant sections for specific information on Security HTTP Response Headers <<servlet-headers,servlet>> and <<webflux-headers,WebFlux>> based applications.
+Refer to the relevant sections for specific information on Security HTTP Response Headers xref:servlet/exploits/headers.adoc#servlet-headers[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers[WebFlux] based applications.
 ====
 
 There are many https://owasp.org/www-project-secure-headers/#div-headers[HTTP response headers] that can be used to increase the security of web applications.
@@ -16,7 +16,7 @@ If necessary, Spring Security can also be configured to provide <<headers-custom
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-default,servlet>> and <<webflux-headers-default,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-default[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-default[webflux] based applications.
 ====
 
 Spring Security provides a default set of security related HTTP response headers to provide secure defaults.
@@ -53,7 +53,7 @@ For additional details on each of these headers, refer to the corresponding sect
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-cache-control,servlet>> and <<webflux-headers-cache-control,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-cache-control[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-cache-control[webflux] based applications.
 ====
 
 Spring Security's default is to disable caching to protect user's content.
@@ -81,7 +81,7 @@ This allows for applications to ensure that static resources like CSS and JavaSc
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-content-type-options,servlet>> and <<webflux-headers-content-type-options,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-content-type-options[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-content-type-options[webflux] based applications.
 ====
 
 Historically browsers, including Internet Explorer, would try to guess the content type of a request using https://en.wikipedia.org/wiki/Content_sniffing[content sniffing].
@@ -114,7 +114,7 @@ X-Content-Type-Options: nosniff
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-hsts,servlet>> and <<webflux-headers-hsts,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-hsts[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-hsts[webflux] based applications.
 ====
 
 When you type in your bank's website, do you enter mybank.example.com or do you enter https://mybank.example.com[]?
@@ -154,7 +154,7 @@ For more details on HSTS preload please see https://hstspreload.org.
 
 [NOTE]
 ====
-In order to remain passive Spring Security still provides <<servlet-headers-hpkp,support for HPKP in servlet environments>>, but for the reasons listed above HPKP is no longer recommended by the security team.
+In order to remain passive Spring Security still provides xref:servlet/exploits/headers.adoc#servlet-headers-hpkp[support for HPKP in servlet environments], but for the reasons listed above HPKP is no longer recommended by the security team.
 ====
 
 https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning[HTTP Public Key Pinning (HPKP)] specifies to a web client which public key to use with certain web server to prevent Man in the Middle (MITM) attacks with forged certificates.
@@ -170,7 +170,7 @@ Is HTTP Public Key Pinning Dead?] and https://scotthelme.co.uk/im-giving-up-on-h
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-frame-options,servlet>> and <<webflux-headers-frame-options,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-frame-options[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-frame-options[webflux] based applications.
 ====
 
 Allowing your website to be added to a frame can be a security issue.
@@ -200,7 +200,7 @@ X-Frame-Options: DENY
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to customize the defaults for both <<servlet-headers-xss-protection,servlet>> and <<webflux-headers-xss-protection,webflux>> based applications.
+Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-xss-protection[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-xss-protection[webflux] based applications.
 ====
 
 Some browsers have built in support for filtering out https://www.owasp.org/index.php/Testing_for_Reflected_Cross_site_scripting_(OWASP-DV-001)[reflected XSS attacks].
@@ -223,7 +223,7 @@ X-XSS-Protection: 1; mode=block
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to configure both <<servlet-headers-csp,servlet>> and <<webflux-headers-csp,webflux>> based applications.
+Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-csp[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-csp[webflux] based applications.
 ====
 
 https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] is a mechanism that web applications can leverage to mitigate content injection vulnerabilities, such as cross-site scripting (XSS).
@@ -299,7 +299,7 @@ https://www.w3.org/TR/CSP2/[W3C Candidate Recommendation]
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to configure both <<servlet-headers-referrer,servlet>> and <<webflux-headers-referrer,webflux>> based applications.
+Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-referrer[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-referrer[webflux] based applications.
 ====
 
 https://www.w3.org/TR/referrer-policy[Referrer Policy] is a mechanism that web applications can leverage to manage the referrer field, which contains the last
@@ -322,7 +322,7 @@ The Referrer-Policy response header instructs the browser to let the destination
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to configure both <<servlet-headers-feature,servlet>> and <<webflux-headers-feature,webflux>> based applications.
+Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-feature[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-feature[webflux] based applications.
 ====
 
 https://wicg.github.io/feature-policy/[Feature Policy] is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
@@ -344,7 +344,7 @@ These policies restrict what APIs the site can access or modify the browser's de
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to configure both <<servlet-headers-permissions,servlet>> and <<webflux-headers-permissions,webflux>> based applications.
+Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-permissions[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-permissions[webflux] based applications.
 ====
 
 https://w3c.github.io/webappsec-permissions-policy/[Permissions Policy] is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
@@ -366,7 +366,7 @@ These policies restrict what APIs the site can access or modify the browser's de
 
 [NOTE]
 ====
-Refer to the relevant sections to see how to configure both <<servlet-headers-clear-site-data,servlet>> and <<webflux-headers-clear-site-data,webflux>> based applications.
+Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-clear-site-data[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-clear-site-data[webflux] based applications.
 ====
 
 https://www.w3.org/TR/clear-site-data/[Clear Site Data] is a mechanism by which any browser-side data - cookies, local storage, and the like - can be removed when an HTTP response contains this header:
@@ -384,7 +384,7 @@ This is a nice clean-up action to perform on logout.
 
 [NOTE]
 ====
-Refer to the relevant section to see how to configure <<servlet-headers-custom,servlet>> based applications.
+Refer to the relevant section to see how to configure xref:servlet/exploits/headers.adoc#servlet-headers-custom[servlet] based applications.
 ====
 
 Spring Security has mechanisms to make it convenient to add the more common security headers to your application.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc b/docs/modules/ROOT/pages/features/exploits/http.adoc
similarity index 87%
rename from docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc
rename to docs/modules/ROOT/pages/features/exploits/http.adoc
index 44a4e59692..fcffae7a25 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc
+++ b/docs/modules/ROOT/pages/features/exploits/http.adoc
@@ -9,12 +9,12 @@ However, it does provide a number of features that help with HTTPS usage.
 [[http-redirect]]
 == Redirect to HTTPS
 
-When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both <<servlet-http-redirect,Servlet>> and <<webflux-http-redirect,WebFlux>> environments.
+When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both xref:servlet/exploits/http.adoc#servlet-http-redirect[Servlet] and xref:reactive/exploits/http.adoc#webflux-http-redirect[WebFlux] environments.
 
 [[http-hsts]]
 == Strict Transport Security
 
-Spring Security provides support for <<headers-hsts,Strict Transport Security>> and enables it by default.
+Spring Security provides support for xref:features/exploits/headers.adoc#headers-hsts[Strict Transport Security] and enables it by default.
 
 [[http-proxy-server]]
 == Proxy Server Configuration
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc b/docs/modules/ROOT/pages/features/exploits/index.adoc
similarity index 65%
rename from docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc
rename to docs/modules/ROOT/pages/features/exploits/index.adoc
index bb8abc73dc..6aa70077ee 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc
+++ b/docs/modules/ROOT/pages/features/exploits/index.adoc
@@ -5,8 +5,6 @@ Spring Security provides protection against common exploits.
 Whenever possible, the protection is enabled by default.
 Below you will find high level description of the various exploits that Spring Security protects against.
 
-include::csrf.adoc[leveloffset=+1]
-
-include::headers.adoc[leveloffset=+1]
-
-include::http.adoc[leveloffset=+1]
+* xref:features/exploits/csrf.adoc[CSRF]
+* xref:features/exploits/headers.adoc[HTTP Headers]
+* xref:features/exploits/http.adoc[HTTP Requests]
diff --git a/docs/modules/ROOT/pages/features/index.adoc b/docs/modules/ROOT/pages/features/index.adoc
new file mode 100644
index 0000000000..5775de1d1f
--- /dev/null
+++ b/docs/modules/ROOT/pages/features/index.adoc
@@ -0,0 +1,6 @@
+[[features]]
+= Features
+
+Spring Security provides comprehensive support for xref:features/authentication/index.adoc[authentication], xref:features/authorization/index.adoc[authorization], and protection against xref:features/exploits/index.adoc#exploits[common exploits].
+It also provides integration with other libraries to simplify its usage.
+
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/concurrency.adoc b/docs/modules/ROOT/pages/features/integrations/concurrency.adoc
similarity index 94%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/concurrency.adoc
rename to docs/modules/ROOT/pages/features/integrations/concurrency.adoc
index a2ac3fe2a2..fbb049c9e9 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/concurrency.adoc
+++ b/docs/modules/ROOT/pages/features/integrations/concurrency.adoc
@@ -1,13 +1,13 @@
 [[concurrency]]
-== Concurrency Support
+= Concurrency Support
 
 In most environments, Security is stored on a per `Thread` basis.
 This means that when work is done on a new `Thread`, the `SecurityContext` is lost.
 Spring Security provides some infrastructure to help make this much easier for users.
 Spring Security provides low level abstractions for working with Spring Security in multi-threaded environments.
-In fact, this is what Spring Security builds on to integration with <<servletapi-start-runnable>> and <<mvc-async>>.
+In fact, this is what Spring Security builds on to integration with xref:servlet/integrations/servlet-api.adoc#servletapi-start-runnable[AsyncContext.start(Runnable)] and xref:servlet/integrations/mvc.adoc#mvc-async[Spring MVC Async Integration].
 
-=== DelegatingSecurityContextRunnable
+== DelegatingSecurityContextRunnable
 
 One of the most fundamental building blocks within Spring Security's concurrency support is the `DelegatingSecurityContextRunnable`.
 It wraps a delegate `Runnable` in order to initialize the `SecurityContextHolder` with a specified `SecurityContext` for the delegate.
@@ -44,7 +44,7 @@ fun run() {
 
 While very simple, it makes it seamless to transfer the SecurityContext from one Thread to another.
 This is important since, in most cases, the SecurityContextHolder acts on a per Thread basis.
-For example, you might have used Spring Security's <<nsa-global-method-security>> support to secure one of your services.
+For example, you might have used Spring Security's xref:servlet/appendix/namespace.adoc#nsa-global-method-security[<global-method-security>] support to secure one of your services.
 You can now easily transfer the `SecurityContext` of the current `Thread` to the `Thread` that invokes the secured service.
 An example of how you might do this can be found below:
 
@@ -122,7 +122,7 @@ Thread(wrappedRunnable).start()
 The code we have is simple to use, but it still requires knowledge that we are using Spring Security.
 In the next section we will take a look at how we can utilize `DelegatingSecurityContextExecutor` to hide the fact that we are using Spring Security.
 
-=== DelegatingSecurityContextExecutor
+== DelegatingSecurityContextExecutor
 
 In the previous section we found that it was easy to use the `DelegatingSecurityContextRunnable`, but it was not ideal since we had to be aware of Spring Security in order to use it.
 Let's take a look at how `DelegatingSecurityContextExecutor` can shield our code from any knowledge that we are using Spring Security.
@@ -244,7 +244,7 @@ val executor = DelegatingSecurityContextExecutor(delegateExecutor)
 Now anytime `executor.execute(Runnable)` is executed the `SecurityContext` is first obtained by the `SecurityContextHolder` and then that `SecurityContext` is used to create our `DelegatingSecurityContextRunnable`.
 This means that we are running our `Runnable` with the same user that was used to invoke the `executor.execute(Runnable)` code.
 
-=== Spring Security Concurrency Classes
+== Spring Security Concurrency Classes
 
 Refer to the Javadoc for additional integrations with both the Java concurrent APIs and the Spring Task abstractions.
 They are quite self-explanatory once you understand the previous code.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc b/docs/modules/ROOT/pages/features/integrations/cryptography.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc
rename to docs/modules/ROOT/pages/features/integrations/cryptography.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/data.adoc b/docs/modules/ROOT/pages/features/integrations/data.adoc
similarity index 88%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/data.adoc
rename to docs/modules/ROOT/pages/features/integrations/data.adoc
index 2e618b11f5..c37f96d302 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/data.adoc
+++ b/docs/modules/ROOT/pages/features/integrations/data.adoc
@@ -1,11 +1,11 @@
 [[data]]
-== Spring Data Integration
+= Spring Data Integration
 
 Spring Security provides Spring Data integration that allows referring to the current user within your queries.
 It is not only useful but necessary to include the user in the queries to support paged results since filtering the results afterwards would not scale.
 
 [[data-configuration]]
-=== Spring Data & Spring Security Configuration
+== Spring Data & Spring Security Configuration
 
 To use this support, add `org.springframework.security:spring-security-data` dependency and provide a bean of type `SecurityEvaluationContextExtension`.
 In Java Configuration, this would look like:
@@ -38,7 +38,7 @@ In XML Configuration, this would look like:
 ----
 
 [[data-query]]
-=== Security Expressions within @Query
+== Security Expressions within @Query
 
 Now Spring Security can be used within your queries.
 For example:
@@ -67,4 +67,4 @@ interface MessageRepository : PagingAndSortingRepository<Message?, Long?> {
 
 This checks to see if the `Authentication.getPrincipal().getId()` is equal to the recipient of the `Message`.
 Note that this example assumes you have customized the principal to be an Object that has an id property.
-By exposing the `SecurityEvaluationContextExtension` bean, all of the <<common-expressions,Common Security Expressions>> are available within the Query.
+By exposing the `SecurityEvaluationContextExtension` bean, all of the xref:servlet/authorization/expression-based.adoc#common-expressions[Common Security Expressions] are available within the Query.
diff --git a/docs/modules/ROOT/pages/features/integrations/index.adoc b/docs/modules/ROOT/pages/features/integrations/index.adoc
new file mode 100644
index 0000000000..96f151b5fc
--- /dev/null
+++ b/docs/modules/ROOT/pages/features/integrations/index.adoc
@@ -0,0 +1,13 @@
+[[integrations]]
+= Integrations
+
+Spring Security provides integrations with numerous frameworks and APIs.
+In this section, we discuss generic integrations that are not specific to Servlet or Reactive environments.
+To see specific integrations, refer to the xref:servlet/integrations/index.adoc[Servlet] and xref:servlet/integrations/index.adoc[Reactive] Integrations sections.
+// FIXME add link to reactive integrations
+
+* xref:features/integrations/cryptography.adoc[Cryptography]
+* xref:features/integrations/data.adoc[Spring Data]
+* xref:features/integrations/concurrency.adoc[Java's Concurrency APIs]
+* xref:features/integrations/jackson.adoc[Jackson]
+* xref:features/integrations/localization.adoc[Localization]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jackson.adoc b/docs/modules/ROOT/pages/features/integrations/jackson.adoc
similarity index 91%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jackson.adoc
rename to docs/modules/ROOT/pages/features/integrations/jackson.adoc
index b78a880998..e1c407763b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jackson.adoc
+++ b/docs/modules/ROOT/pages/features/integrations/jackson.adoc
@@ -1,5 +1,5 @@
 [[jackson]]
-== Jackson Support
+= Jackson Support
 
 Spring Security provides Jackson support for persisting Spring Security related classes.
 This can improve the performance of serializing Spring Security related classes when working with distributed sessions (i.e. session replication, Spring Session, etc).
@@ -42,6 +42,6 @@ The following Spring Security modules provide Jackson support:
 
 - spring-security-core (`CoreJackson2Module`)
 - spring-security-web (`WebJackson2Module`, `WebServletJackson2Module`, `WebServerJackson2Module`)
-- <<oauth2client, spring-security-oauth2-client>> (`OAuth2ClientJackson2Module`)
+- xref:servlet/oauth2/oauth2-client.adoc#oauth2client[ spring-security-oauth2-client] (`OAuth2ClientJackson2Module`)
 - spring-security-cas (`CasJackson2Module`)
 ====
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/localization.adoc b/docs/modules/ROOT/pages/features/integrations/localization.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/localization.adoc
rename to docs/modules/ROOT/pages/features/integrations/localization.adoc
index 0f8f9b402e..e1fc22b9a2 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/localization.adoc
+++ b/docs/modules/ROOT/pages/features/integrations/localization.adoc
@@ -1,5 +1,5 @@
 [[localization]]
-== Localization
+= Localization
 Spring Security supports localization of exception messages that end users are likely to see.
 If your application is designed for English-speaking users, you don't need to do anything as by default all Security messages are in English.
 If you need to support other locales, everything you need to know is contained in this section.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc b/docs/modules/ROOT/pages/getting-spring-security.adoc
similarity index 95%
rename from docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc
rename to docs/modules/ROOT/pages/getting-spring-security.adoc
index 51f77fe29f..f99e18860f 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc
+++ b/docs/modules/ROOT/pages/getting-spring-security.adoc
@@ -2,7 +2,7 @@
 = Getting Spring Security
 
 This section discusses all you need to know about getting the Spring Security binaries.
-See <<community-source>> for how to obtain the source code.
+See xref:community.adoc#community-source[Source Code] for how to obtain the source code.
 
 == Release Numbering
 
@@ -72,7 +72,7 @@ You can do so by adding a Maven property, as the following example shows:
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
 
 [[getting-maven-no-boot]]
 === Maven Without Spring Boot
@@ -118,7 +118,7 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
 
 Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
 Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
@@ -236,7 +236,7 @@ ext['spring.version']='{spring-core-version}'
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
 
 === Gradle Without Spring Boot
 
@@ -274,7 +274,7 @@ dependencies {
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
 
 Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
 Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000000..84f9f83499
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,15 @@
+= Spring Security
+
+Spring Security is a framework that provides xref:features/authentication/index.adoc[authentication], xref:features/authorization/index.adoc[authorization], and xref:features/exploits/index.adoc[protection against common attacks].
+With first class support for securing both xref:servlet/index.adoc[imperative] and xref:reactive/index.adoc[reactive] applications, it is the de-facto standard for securing Spring-based applications.
+
+For a complete list of features, see the xref:features/index.adoc[Features] section of the reference.
+
+== Getting Started
+
+If you are ready to start securing an application see the Getting Started sections for xref:servlet/getting-started.adoc[servlet] and xref:reactive/getting-started.adoc[reactive]. These sections will walk you through creating your first Spring Security applications.
+
+If you want to understand how Spring Security works, you can refer to the xref:servlet/architecture.adoc[Architecture] section.
+// FIXME add link to reactive architecture
+
+If you have any questions, there is a wonderful xref:community.adoc[community] that would love to help you!
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/modules.adoc b/docs/modules/ROOT/pages/modules.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/about/modules.adoc
rename to docs/modules/ROOT/pages/modules.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/prerequisites.adoc b/docs/modules/ROOT/pages/prerequisites.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/about/prerequisites.adoc
rename to docs/modules/ROOT/pages/prerequisites.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/logout.adoc b/docs/modules/ROOT/pages/reactive/authentication/logout.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/logout.adoc
rename to docs/modules/ROOT/pages/reactive/authentication/logout.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/x509.adoc b/docs/modules/ROOT/pages/reactive/authentication/x509.adoc
similarity index 93%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/x509.adoc
rename to docs/modules/ROOT/pages/reactive/authentication/x509.adoc
index cb1c4e0a47..880632b060 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/x509.adoc
+++ b/docs/modules/ROOT/pages/reactive/authentication/x509.adoc
@@ -1,7 +1,7 @@
 [[reactive-x509]]
 = Reactive X.509 Authentication
 
-Similar to <<servlet-x509,Servlet X.509 authentication>>, reactive x509 authentication filter allows extracting an authentication token from a certificate provided by a client.
+Similar to xref:servlet/authentication/x509.adoc#servlet-x509[Servlet X.509 authentication], reactive x509 authentication filter allows extracting an authentication token from a certificate provided by a client.
 
 Below is an example of a reactive x509 security configuration:
 ====
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/method.adoc b/docs/modules/ROOT/pages/reactive/authorization/method.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/method.adoc
rename to docs/modules/ROOT/pages/reactive/authorization/method.adoc
index 21a183fd34..dc04d46be6 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/method.adoc
+++ b/docs/modules/ROOT/pages/reactive/authorization/method.adoc
@@ -162,7 +162,7 @@ It is important to note that any of the expressions in standard method security
 However, at this time we only support return type of `Boolean` or `boolean` of the expression.
 This means that the expression must not block.
 
-When integrating with <<jc-webflux>>, the Reactor Context is automatically established by Spring Security according to the authenticated user.
+When integrating with xref:reactive/configuration/webflux.adoc#jc-webflux[WebFlux Security], the Reactor Context is automatically established by Spring Security according to the authenticated user.
 
 ====
 .Java
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/webflux.adoc b/docs/modules/ROOT/pages/reactive/configuration/webflux.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/webflux.adoc
rename to docs/modules/ROOT/pages/reactive/configuration/webflux.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc
similarity index 89%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc
rename to docs/modules/ROOT/pages/reactive/exploits/csrf.adoc
index c3a92fea4f..6762324171 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc
+++ b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc
@@ -1,7 +1,7 @@
 [[webflux-csrf]]
 = Cross Site Request Forgery (CSRF) for WebFlux Environments
 
-This section discusses Spring Security's <<csrf,Cross Site Request Forgery (CSRF)>> support for WebFlux environments.
+This section discusses Spring Security's xref:features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] support for WebFlux environments.
 
 [[webflux-csrf-using]]
 == Using Spring Security CSRF Protection
@@ -14,7 +14,7 @@ The steps to using Spring Security's CSRF protection are outlined below:
 [[webflux-csrf-idempotent]]
 === Use proper HTTP verbs
 The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs.
-This is covered in detail in <<csrf-protection-idempotent,Safe Methods Must be Idempotent>>.
+This is covered in detail in xref:features/exploits/csrf.adoc#csrf-protection-idempotent[Safe Methods Must be Idempotent].
 
 [[webflux-csrf-configure]]
 === Configure CSRF Protection
@@ -73,7 +73,7 @@ If you do not need the ability to read the cookie with JavaScript directly, it i
 [[webflux-csrf-configure-disable]]
 ==== Disable CSRF Protection
 CSRF protection is enabled by default.
-However, it is simple to disable CSRF protection if it <<csrf-when,makes sense for your application>>.
+However, it is simple to disable CSRF protection if it xref:features/exploits/csrf.adoc#csrf-when[makes sense for your application].
 
 The Java configuration below will disable CSRF protection.
 
@@ -109,7 +109,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain
 [[webflux-csrf-include]]
 === Include the CSRF Token
 
-In order for the <<csrf-protection-stp,synchronizer token pattern>> to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request.
+In order for the xref:features/exploits/csrf.adoc#csrf-protection-stp[synchronizer token pattern] to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request.
 This must be included in a part of the request (i.e. form parameter, HTTP header, etc) that is not automatically included in the HTTP request by the browser.
 
 Spring Security's https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/server/csrf/CsrfWebFilter.html[CsrfWebFilter] exposes a https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfToken.html[Mono<CsrfToken>] as a `ServerWebExchange` attribute named `org.springframework.security.web.server.csrf.CsrfToken`.
@@ -272,19 +272,19 @@ An example of doing this with Thymeleaf is shown below:
 == CSRF Considerations
 There are a few special considerations to consider when implementing protection against CSRF attacks.
 This section discusses those considerations as it pertains to WebFlux environments.
-Refer to <<csrf-considerations>> for a more general discussion.
+Refer to xref:features/exploits/csrf.adoc#csrf-considerations[CSRF Considerations] for a more general discussion.
 
 
 [[webflux-considerations-csrf-login]]
 === Logging In
 
-It is important to <<csrf-considerations-login,require CSRF for log in>> requests to protect against forging log in attempts.
+It is important to xref:features/exploits/csrf.adoc#csrf-considerations-login[require CSRF for log in] requests to protect against forging log in attempts.
 Spring Security's WebFlux support does this out of the box.
 
 [[webflux-considerations-csrf-logout]]
 === Logging Out
 
-It is important to <<csrf-considerations-logout,require CSRF for log out>> requests to protect against forging log out attempts.
+It is important to xref:features/exploits/csrf.adoc#csrf-considerations-logout[require CSRF for log out] requests to protect against forging log out attempts.
 By default Spring Security's `LogoutWebFilter` only processes HTTP post requests.
 This ensures that log out requires a CSRF token and that a malicious user cannot forcibly log out your users.
 
@@ -333,7 +333,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain
 By default Spring Security stores the CSRF token in the `WebSession`.
 This can lead to a situation where the session expires which means there is not an expected CSRF token to validate against.
 
-We've already discussed <<csrf-considerations-login,general solutions>> to session timeouts.
+We've already discussed xref:features/exploits/csrf.adoc#csrf-considerations-login[general solutions] to session timeouts.
 This section discusses the specifics of CSRF timeouts as it pertains to the WebFlux support.
 
 It is simple to change storage of the expected CSRF token to be in a cookie.
@@ -344,7 +344,7 @@ For details, refer to the <<webflux-csrf-configure-custom-repository>> section.
 // FIXME: We need a WebFlux multipart body vs action story. WebFlux always has multipart enabled.
 [[webflux-csrf-considerations-multipart]]
 === Multipart (file upload)
-We have <<csrf-considerations-multipart,already discussed>> how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem.
 This section discusses how to implement placing the CSRF token in the <<webflux-csrf-considerations-multipart-body,body>> and <<webflux-csrf-considerations-multipart-url,url>> within a WebFlux application.
 
 [NOTE]
@@ -355,7 +355,7 @@ More information about using multipart forms with Spring can be found within the
 [[webflux-csrf-considerations-multipart-body]]
 ==== Place CSRF Token in the Body
 
-We have <<csrf-considerations-multipart,already discussed>> the trade-offs of placing the CSRF token in the body.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] the trade-offs of placing the CSRF token in the body.
 
 In a WebFlux application, this can be configured with the following configuration:
 
@@ -391,7 +391,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain
 [[webflux-csrf-considerations-multipart-url]]
 ==== Include CSRF Token in URL
 
-We have <<csrf-considerations-multipart,already discussed>> the trade-offs of placing the CSRF token in the URL.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] the trade-offs of placing the CSRF token in the URL.
 Since the `CsrfToken` is exposed as an `ServerHttpRequest` <<webflux-csrf-include,request attribute>>, we can use that to create an `action` with the CSRF token in it.
 An example with Thymeleaf is shown below:
 
@@ -407,6 +407,6 @@ An example with Thymeleaf is shown below:
 
 [[webflux-csrf-considerations-override-method]]
 === HiddenHttpMethodFilter
-We have <<csrf-considerations-override-method,already discussed>> overriding the HTTP method.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-override-method[already discussed] overriding the HTTP method.
 
 In a Spring WebFlux application, overriding the HTTP method is done using https://docs.spring.io/spring-framework/docs/5.2.x/javadoc-api/org/springframework/web/filter/reactive/HiddenHttpMethodFilter.html[HiddenHttpMethodFilter].
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/headers.adoc b/docs/modules/ROOT/pages/reactive/exploits/headers.adoc
similarity index 89%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/exploits/headers.adoc
rename to docs/modules/ROOT/pages/reactive/exploits/headers.adoc
index a076a2fedb..9b61d12b3a 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/headers.adoc
+++ b/docs/modules/ROOT/pages/reactive/exploits/headers.adoc
@@ -1,17 +1,17 @@
 [[webflux-headers]]
 = Security HTTP Response Headers
 
-<<headers,Security HTTP Response Headers>> can be used to increase the security of web applications.
+xref:features/exploits/headers.adoc#headers[Security HTTP Response Headers] can be used to increase the security of web applications.
 This section is dedicated to WebFlux based support for Security HTTP Response Headers.
 
 [[webflux-headers-default]]
 == Default Security Headers
 
-Spring Security provides a <<headers-default,default set of Security HTTP Response Headers>> to provide secure defaults.
+Spring Security provides a xref:features/exploits/headers.adoc#headers-default[default set of Security HTTP Response Headers] to provide secure defaults.
 While each of these headers are considered best practice, it should be noted that not all clients utilize the headers, so additional testing is encouraged.
 
 You can customize specific headers.
-For example, assume that you want the defaults except you wish to specify `SAMEORIGIN` for <<servlet-headers-frame-options,X-Frame-Options>>.
+For example, assume that you want the defaults except you wish to specify `SAMEORIGIN` for xref:servlet/exploits/headers.adoc#servlet-headers-frame-options[X-Frame-Options].
 
 You can easily do this with the following Configuration:
 
@@ -85,7 +85,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 [[webflux-headers-cache-control]]
 == Cache Control
 
-Spring Security includes <<headers-cache-control,Cache Control>> headers by default.
+Spring Security includes xref:features/exploits/headers.adoc#headers-cache-control[Cache Control] headers by default.
 
 However, if you actually want to cache specific responses, your application can selectively add them to the https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/server/reactive/ServerHttpResponse.html[ServerHttpResponse] to override the header set by Spring Security.
 This is useful to ensure things like CSS, JavaScript, and images are properly cached.
@@ -131,7 +131,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 
 [[webflux-headers-content-type-options]]
 == Content Type Options
-Spring Security includes <<headers-content-type-options,Content-Type>> headers by default.
+Spring Security includes xref:features/exploits/headers.adoc#headers-content-type-options[Content-Type] headers by default.
 However, you can disable it with:
 
 .Content Type Options Disabled
@@ -169,7 +169,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 
 [[webflux-headers-hsts]]
 == HTTP Strict Transport Security (HSTS)
-Spring Security provides the <<headers-hsts,Strict Transport Security>> header by default.
+Spring Security provides the xref:features/exploits/headers.adoc#headers-hsts[Strict Transport Security] header by default.
 However, you can customize the results explicitly.
 For example, the following is an example of explicitly providing HSTS:
 
@@ -214,7 +214,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 
 [[webflux-headers-frame-options]]
 == X-Frame-Options
-By default, Spring Security disables rendering within an iframe using <<headers-frame-options,X-Frame-Options>>.
+By default, Spring Security disables rendering within an iframe using xref:features/exploits/headers.adoc#headers-frame-options[X-Frame-Options].
 
 You can customize frame options to use the same origin using the following:
 
@@ -293,7 +293,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 
 [[webflux-headers-csp]]
 == Content Security Policy (CSP)
-Spring Security does not add <<headers-csp,Content Security Policy>> by default, because a reasonable default is impossible to know without context of the application.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-csp[Content Security Policy] by default, because a reasonable default is impossible to know without context of the application.
 The web application author must declare the security policy(s) to enforce and/or monitor for the protected resources.
 
 For example, given the following security policy:
@@ -385,7 +385,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 [[webflux-headers-referrer]]
 == Referrer Policy
 
-Spring Security does not add <<headers-referrer,Referrer Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-referrer[Referrer Policy] headers by default.
 You can enable the Referrer Policy header using configuration as shown below:
 
 .Referrer Policy Configuration
@@ -427,7 +427,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 [[webflux-headers-feature]]
 == Feature Policy
 
-Spring Security does not add <<headers-feature,Feature Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-feature[Feature Policy] headers by default.
 The following `Feature-Policy` header:
 
 .Feature-Policy Example
@@ -475,7 +475,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 [[webflux-headers-permissions]]
 == Permissions Policy
 
-Spring Security does not add <<headers-permissions,Permissions Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-permissions[Permissions Policy] headers by default.
 The following `Permissions-Policy` header:
 
 .Permissions-Policy Example
@@ -527,7 +527,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 [[webflux-headers-clear-site-data]]
 == Clear Site Data
 
-Spring Security does not add <<headers-clear-site-data,Clear-Site-Data>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default.
 The following Clear-Site-Data header:
 
 .Clear-Site-Data Example
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc b/docs/modules/ROOT/pages/reactive/exploits/http.adoc
similarity index 84%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc
rename to docs/modules/ROOT/pages/reactive/exploits/http.adoc
index 387a05a719..e7a07bb20b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc
+++ b/docs/modules/ROOT/pages/reactive/exploits/http.adoc
@@ -1,7 +1,7 @@
 [[webflux-http]]
 = HTTP
 
-All HTTP based communication should be protected <<http,using TLS>>.
+All HTTP based communication should be protected xref:features/exploits/http.adoc#http[using TLS].
 
 Below you can find details around WebFlux specific features that assist with HTTPS usage.
 
@@ -79,9 +79,9 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain
 [[webflux-hsts]]
 == Strict Transport Security
 
-Spring Security provides support for <<servlet-headers-hsts,Strict Transport Security>> and enables it by default.
+Spring Security provides support for xref:servlet/exploits/headers.adoc#servlet-headers-hsts[Strict Transport Security] and enables it by default.
 
 [[webflux-http-proxy-server]]
 == Proxy Server Configuration
 
-Spring Security <<http-proxy-server,integrates with proxy servers>>.
+Spring Security xref:features/exploits/http.adoc#http-proxy-server[integrates with proxy servers].
diff --git a/docs/modules/ROOT/pages/reactive/exploits/index.adoc b/docs/modules/ROOT/pages/reactive/exploits/index.adoc
new file mode 100644
index 0000000000..200d037f57
--- /dev/null
+++ b/docs/modules/ROOT/pages/reactive/exploits/index.adoc
@@ -0,0 +1,8 @@
+= Protection Against Exploits
+
+Spring Security provides protection against numerous exploits.
+This section discusses WebFlux specific support for:
+
+* xref:reactive/exploits/csrf.adoc[CSRF]
+* xref:reactive/exploits/headers.adoc[Headers]
+* xref:reactive/exploits/http.adoc[HTTP Requests]
diff --git a/docs/modules/ROOT/pages/reactive/getting-started.adoc b/docs/modules/ROOT/pages/reactive/getting-started.adoc
new file mode 100644
index 0000000000..aac4095a4c
--- /dev/null
+++ b/docs/modules/ROOT/pages/reactive/getting-started.adoc
@@ -0,0 +1,80 @@
+[[getting-started]]
+= Getting Started with WebFlux Applications
+
+This section covers the minimum setup for how to use Spring Security with Spring Boot in a reactive application.
+
+[NOTE]
+====
+The completed application can be found {gh-samples-url}/reactive/webflux/java/hello-security[in our samples repository].
+For your convenience, you can download a minimal Reactive Spring Boot + Spring Security application by https://start.spring.io/starter.zip?type=maven-project&language=java&packaging=jar&jvmVersion=1.8&groupId=example&artifactId=hello-security&name=hello-security&description=Hello%20Security&packageName=example.hello-security&dependencies=webflux,security[clicking here].
+====
+
+[[dependencies]]
+== Updating Dependencies
+
+You can add Spring Security to your Spring Boot project by adding `spring-boot-starter-security`.
+
+====
+.Maven
+[source,xml,role="primary"]
+----
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-security</artifactId>
+</dependency>
+----
+
+.Gradle
+[source,groovy,role="secondary"]
+----
+    implementation 'org.springframework.boot:spring-boot-starter-security'
+----
+====
+
+
+[[servlet-hello-starting]]
+== Starting Hello Spring Security Boot
+
+You can now https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-running-with-the-maven-plugin[run the Spring Boot application] by using the Maven Plugin's `run` goal.
+The following example shows how to do so (and the beginning of the output from doing so):
+
+.Running Spring Boot Application
+
+====
+.Maven
+[source,bash,role="primary"]
+----
+$ ./mvnw spring-boot:run
+...
+INFO 23689 --- [  restartedMain] .s.s.UserDetailsServiceAutoConfiguration :
+
+Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336
+
+...
+----
+
+.Gradle
+[source,bash,role="secondary"]
+----
+$ ./gradlew bootRun
+...
+INFO 23689 --- [  restartedMain] .s.s.UserDetailsServiceAutoConfiguration :
+
+Using generated security password: 8e557245-73e2-4286-969a-ff57fe326336
+
+...
+----
+====
+
+[[authenticating]]
+== Authenticating
+
+You can access the application at http://localhost:8080/ which will redirect the browser to the default log in page. You can provide the default username of `user` with the randomly generated password that is logged to the console. The browser is then taken to the orginally requested page.
+
+To log out you can visit http://localhost:8080/logout and then confirming you wish to log out.
+
+[[auto-configuration]]
+== Spring Boot Auto Configuration
+
+Spring Boot automatically adds Spring Security which requires all requests be authenticated. It also generates a user with a randomly generated password that is logged to the console which can be used to authenticate using form or basic authentication.
+
diff --git a/docs/modules/ROOT/pages/reactive/index.adoc b/docs/modules/ROOT/pages/reactive/index.adoc
new file mode 100644
index 0000000000..812fa7adef
--- /dev/null
+++ b/docs/modules/ROOT/pages/reactive/index.adoc
@@ -0,0 +1,4 @@
+= Reactive Applications
+
+Reactive applications work very differently than xref:servlet/index.adoc#servlet-applications[Servlet Applications].
+This section discusses how Spring Security works with reactive applications which are typically written using Spring's WebFlux.
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/cors.adoc b/docs/modules/ROOT/pages/reactive/integrations/cors.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/cors.adoc
rename to docs/modules/ROOT/pages/reactive/integrations/cors.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/rsocket.adoc b/docs/modules/ROOT/pages/reactive/integrations/rsocket.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/rsocket.adoc
rename to docs/modules/ROOT/pages/reactive/integrations/rsocket.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/webclient.adoc b/docs/modules/ROOT/pages/reactive/integrations/webclient.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/webclient.adoc
rename to docs/modules/ROOT/pages/reactive/integrations/webclient.adoc
index 181ac58b2c..270420a4fa 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/webclient.adoc
+++ b/docs/modules/ROOT/pages/reactive/integrations/webclient.adoc
@@ -3,7 +3,7 @@
 [NOTE]
 ====
 The following documentation is for use within Reactive environments.
-For Servlet environments, refer to <<oauth2Client-webclient-servlet, WebClient for Servlet>> environments.
+For Servlet environments, refer to xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-webclient-servlet[ WebClient for Servlet] environments.
 ====
 
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/access-token.adoc b/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc
similarity index 84%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/access-token.adoc
rename to docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc
index ac732704a2..27d272c089 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/access-token.adoc
+++ b/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc
@@ -49,4 +49,4 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
 ----
 ====
 
-You can now leverage Spring Security's <<webclient>> or <<webflux-roac,@RegisteredOAuth2AuthorizedClient>> support to obtain and use the access token.
+You can now leverage Spring Security's <<webclient>> or xref:reactive/registered-oauth2-authorized-client.adoc#webflux-roac[@RegisteredOAuth2AuthorizedClient] support to obtain and use the access token.
diff --git a/docs/modules/ROOT/pages/reactive/oauth2/index.adoc b/docs/modules/ROOT/pages/reactive/oauth2/index.adoc
new file mode 100644
index 0000000000..eb3f150f7f
--- /dev/null
+++ b/docs/modules/ROOT/pages/reactive/oauth2/index.adoc
@@ -0,0 +1,8 @@
+[[webflux-oauth2]]
+= OAuth2 WebFlux
+
+Spring Security provides OAuth2 and WebFlux integration for reactive applications.
+
+* xref:reactive/oauth2/login.adoc[OAuth 2.0 Login] - Authenticating with OAuth 2.0
+* xref:reactive/oauth2/access-token.adoc[OAuth2 Client] - Making requests to an OAuth2 Resource Server as an OAuth2 Client
+* xref:reactive/oauth2/resource-server.adoc[OAuth 2.0 Resource Server] - protecting a REST endpoint using OAuth 2.0
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc b/docs/modules/ROOT/pages/reactive/oauth2/login.adoc
similarity index 93%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc
rename to docs/modules/ROOT/pages/reactive/oauth2/login.adoc
index ecbe18dc0f..a16160c0ff 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc
+++ b/docs/modules/ROOT/pages/reactive/oauth2/login.adoc
@@ -39,11 +39,11 @@ The redirect URI is the path in the application that the end-user's user-agent i
 In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`.
 
 TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`.
-The *_registrationId_* is a unique identifier for the <<oauth2Client-client-registration,ClientRegistration>>.
+The *_registrationId_* is a unique identifier for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration].
 For our example, the `registrationId` is `google`.
 
-IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check <<http-proxy-server,Proxy Server Configuration>> to ensure the application is correctly configured.
-Also, see the supported <<oauth2Client-auth-code-redirect-uri, `URI` template variables>> for `redirect-uri`.
+IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check xref:features/exploits/http.adoc#http-proxy-server[Proxy Server Configuration] to ensure the application is correctly configured.
+Also, see the supported xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-code-redirect-uri[ `URI` template variables] for `redirect-uri`.
 
 [[webflux-oauth2-login-sample-config]]
 === Configure `application.yml`
@@ -68,7 +68,7 @@ spring:
 .OAuth Client properties
 ====
 <1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties.
-<2> Following the base property prefix is the ID for the <<oauth2Client-client-registration,ClientRegistration>>, such as google.
+<2> Following the base property prefix is the ID for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration], such as google.
 ====
 
 . Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc
rename to docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc
index 8f45337314..443b54aff7 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc
+++ b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc
@@ -896,7 +896,7 @@ fun jwtDecoder(): ReactiveJwtDecoder {
 
 [[webflux-oauth2resourceserver-opaque-minimaldependencies]]
 === Minimal Dependencies for Introspection
-As described in <<oauth2resourceserver-jwt-minimaldependencies,Minimal Dependencies for JWT>> most of Resource Server support is collected in `spring-security-oauth2-resource-server`.
+As described in xref:servlet/oauth2/oauth2-resourceserver.adoc#oauth2resourceserver-jwt-minimaldependencies[Minimal Dependencies for JWT] most of Resource Server support is collected in `spring-security-oauth2-resource-server`.
 However unless a custom <<webflux-oauth2resourceserver-opaque-introspector-bean,`ReactiveOpaqueTokenIntrospector`>> is provided, the Resource Server will fallback to ReactiveOpaqueTokenIntrospector.
 Meaning that both `spring-security-oauth2-resource-server` and `oauth2-oidc-sdk` are necessary in order to have a working minimal Resource Server that supports opaque Bearer Tokens.
 Please refer to `spring-security-oauth2-resource-server` in order to determin the correct version for `oauth2-oidc-sdk`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/registered-oauth2-authorized-client.adoc b/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc
similarity index 87%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/registered-oauth2-authorized-client.adoc
rename to docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc
index 30beaf7807..b8cc5c6367 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/registered-oauth2-authorized-client.adoc
+++ b/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc
@@ -8,7 +8,7 @@ Spring Security allows resolving an access token using `@RegisteredOAuth2Authori
 A working example can be found in {gh-samples-url}/reactive/webflux/java/oauth2/webclient[*OAuth 2.0 WebClient WebFlux sample*].
 ====
 
-After configuring Spring Security for <<webflux-oauth2-login,OAuth2 Login>> or as an <<webflux-oauth2-client,OAuth2 Client>>, an `OAuth2AuthorizedClient` can be resolved using the following:
+After configuring Spring Security for xref:reactive/oauth2/login.adoc#webflux-oauth2-login[OAuth2 Login] or as an xref:reactive/oauth2/access-token.adoc#webflux-oauth2-client[OAuth2 Client], an `OAuth2AuthorizedClient` can be resolved using the following:
 
 ====
 .Java
diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/test.adoc b/docs/modules/ROOT/pages/reactive/test.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/reactive/test.adoc
rename to docs/modules/ROOT/pages/reactive/test.adoc
index d341dea14a..53156d110a 100644
--- a/docs/manual/src/docs/asciidoc/_includes/reactive/test.adoc
+++ b/docs/modules/ROOT/pages/reactive/test.adoc
@@ -4,7 +4,7 @@
 [[test-erms]]
 == Testing Reactive Method Security
 
-For example, we can test our example from <<jc-erms>> using the same setup and annotations we did in <<test-method>>.
+For example, we can test our example from xref:reactive/authorization/method.adoc#jc-erms[EnableReactiveMethodSecurity] using the same setup and annotations we did in xref:servlet/test/method.adoc#test-method[Testing Method Security].
 Here is a minimal sample of what we can do:
 
 ====
@@ -381,7 +381,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"
 ----
 ====
 
-Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+Spring Security does the necessary work to make sure that the `OidcUser` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation].
 
 Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into a mock `ServerOAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<webflux-testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>..
@@ -600,7 +600,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"
 ----
 ====
 
-Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation].
 
 Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in a mock `ServerOAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<webflux-testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/samples.adoc b/docs/modules/ROOT/pages/samples.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/about/samples.adoc
rename to docs/modules/ROOT/pages/samples.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/database-schema.adoc b/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/appendix/database-schema.adoc
rename to docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc
index ab840e131f..f6cf413b68 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/database-schema.adoc
+++ b/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc
@@ -78,7 +78,7 @@ If you write your own or choose to implement `AuthenticationProvider` without a
 
 
 == Persistent Login (Remember-Me) Schema
-This table is used to store data used by the more secure <<remember-me-persistent-token,persistent token>> remember-me implementation.
+This table is used to store data used by the more secure xref:servlet/authentication/rememberme.adoc#remember-me-persistent-token[persistent token] remember-me implementation.
 If you are using `JdbcTokenRepositoryImpl` either directly or through the namespace, then you will need this table.
 Remember to adjust this schema to match the database dialect you are using.
 
@@ -96,7 +96,7 @@ create table persistent_logins (
 
 [[dbschema-acl]]
 == ACL Schema
-There are four tables used by the Spring Security <<domain-acls,ACL>> implementation.
+There are four tables used by the Spring Security xref:servlet/authorization/acls.adoc#domain-acls[ACL] implementation.
 
 . `acl_sid` stores the security identities recognised by the ACL system.
 These can be unique principals or authorities which may apply to multiple principals.
@@ -367,7 +367,7 @@ END;
 
 [[dbschema-oauth2-client]]
 == OAuth 2.0 Client Schema
-The JDBC implementation of <<oauth2Client-authorized-repo-service, OAuth2AuthorizedClientService>> (`JdbcOAuth2AuthorizedClientService`) requires a table for persisting `OAuth2AuthorizedClient`(s).
+The JDBC implementation of xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-authorized-repo-service[ OAuth2AuthorizedClientService] (`JdbcOAuth2AuthorizedClientService`) requires a table for persisting `OAuth2AuthorizedClient`(s).
 You will need to adjust this schema to match the database dialect you are using.
 
 [source,ddl]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/faq.adoc b/docs/modules/ROOT/pages/servlet/appendix/faq.adoc
similarity index 91%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/appendix/faq.adoc
rename to docs/modules/ROOT/pages/servlet/appendix/faq.adoc
index 911f173982..87dcff4564 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/faq.adoc
+++ b/docs/modules/ROOT/pages/servlet/appendix/faq.adoc
@@ -1,5 +1,5 @@
 [[appendix-faq]]
-== Spring Security FAQ
+= Spring Security FAQ
 
 * <<appendix-faq-general-questions>>
 * <<appendix-faq-common-problems>>
@@ -7,7 +7,7 @@
 * <<appendix-faq-howto>>
 
 [[appendix-faq-general-questions]]
-=== General Questions
+== General Questions
 
 . <<appendix-faq-other-concerns>>
 . <<appendix-faq-web-xml>>
@@ -16,7 +16,7 @@
 
 
 [[appendix-faq-other-concerns]]
-==== Will Spring Security take care of all my application security requirements?
+=== Will Spring Security take care of all my application security requirements?
 
 Spring Security provides you with a very flexible framework for your authentication and authorization requirements, but there are many other considerations for building a secure application that are outside its scope.
 Web applications are vulnerable to all kinds of attacks which you should be familiar with, preferably before you start development so you can design and code with them in mind from the beginning.
@@ -24,7 +24,7 @@ Check out the https://www.owasp.org/[OWASP web site] for information on the majo
 
 
 [[appendix-faq-web-xml]]
-==== Why not just use web.xml security?
+=== Why not just use web.xml security?
 
 Let's assume you're developing an enterprise application based on Spring.
 There are four security concerns you typically need to address: authentication, web request security, service layer security (i.e. your methods that implement business logic), and domain object instance security (i.e. different domain objects have different permissions). With these typical requirements in mind:
@@ -64,7 +64,7 @@ Although when considered within the context of web container portability, config
 
 
 [[appendix-faq-requirements]]
-==== What Java and Spring Framework versions are required?
+=== What Java and Spring Framework versions are required?
 
 Spring Security 3.0 and 3.1 require at least JDK 1.5 and also require Spring 3.0.3 as a minimum.
 Ideally you should be using the latest release versions to avoid problems.
@@ -74,7 +74,7 @@ It should also be compatible with applications using Spring 2.5.x.
 
 
 [[appendix-faq-start-simple]]
-==== I'm new to Spring Security and I need to build an application that supports CAS single sign-on over HTTPS, while allowing Basic authentication locally for certain URLs, authenticating against multiple back end user information sources (LDAP and JDBC). I've copied some configuration files I found but it doesn't work.
+=== I'm new to Spring Security and I need to build an application that supports CAS single sign-on over HTTPS, while allowing Basic authentication locally for certain URLs, authenticating against multiple back end user information sources (LDAP and JDBC). I've copied some configuration files I found but it doesn't work.
 What could be wrong?
 
 Or substitute an alternative complex scenario...
@@ -92,7 +92,7 @@ This will take you through a series of steps to get up and running and get some
 If you are using other technologies which you aren't familiar with then you should do some research and try to make sure you can use them in isolation before combining them in a complex system.
 
 [[appendix-faq-common-problems]]
-=== Common Problems
+== Common Problems
 
 . Authentication
 .. <<appendix-faq-bad-credentials>>
@@ -115,7 +115,7 @@ If you are using other technologies which you aren't familiar with then you shou
 .. <<appendix-faq-method-security-with-taglib>>
 
 [[appendix-faq-bad-credentials]]
-==== When I try to log in, I get an error message that says "Bad Credentials". What's wrong?
+=== When I try to log in, I get an error message that says "Bad Credentials". What's wrong?
 
 This means that authentication has failed.
 It doesn't say why, as it is good practice to avoid giving details which might help an attacker guess account names or passwords.
@@ -129,7 +129,7 @@ If you are using hashed passwords, make sure the value stored in your database i
 
 
 [[appendix-faq-login-loop]]
-==== My application goes into an "endless loop" when I try to login, what's going on?
+=== My application goes into an "endless loop" when I try to login, what's going on?
 
 A common user problem with infinite loop and redirecting to the login page is caused by accidentally configuring the login page as a "secured" resource.
 Make sure your configuration allows anonymous access to the login page, either by excluding it from the security filter chain or marking it as requiring ROLE_ANONYMOUS.
@@ -140,7 +140,7 @@ From Spring Security 2.0.1 onwards, when you are using namespace-based configura
 
 
 [[appendix-faq-anon-access-denied]]
-==== I get an exception with the message "Access is denied (user is anonymous);". What's wrong?
+=== I get an exception with the message "Access is denied (user is anonymous);". What's wrong?
 
 This is a debug level message which occurs the first time an anonymous user attempts to access a protected resource.
 
@@ -158,7 +158,7 @@ It is normal and shouldn't be anything to worry about.
 
 
 [[appendix-faq-cached-secure-page]]
-==== Why can I still see a secured page even after I've logged out of my application?
+=== Why can I still see a secured page even after I've logged out of my application?
 
 The most common reason for this is that your browser has cached the page and you are seeing a copy which is being retrieved from the browsers cache.
 Verify this by checking whether the browser is actually sending the request (check your server access logs, the debug log or use a suitable browser debugging plugin such as "Tamper Data" for Firefox). This has nothing to do with Spring Security and you should configure your application or server to set the appropriate `Cache-Control` response headers.
@@ -166,7 +166,7 @@ Note that SSL requests are never cached.
 
 
 [[auth-exception-credentials-not-found]]
-==== I get an exception with the message "An Authentication object was not found in the SecurityContext". What's wrong?
+=== I get an exception with the message "An Authentication object was not found in the SecurityContext". What's wrong?
 
 This is a another debug level message which occurs the first time an anonymous user attempts to access a protected resource, but when you do not have an `AnonymousAuthenticationFilter` in your filter chain configuration.
 
@@ -184,7 +184,7 @@ It is normal and shouldn't be anything to worry about.
 
 
 [[appendix-faq-ldap-authentication]]
-==== I can't get LDAP authentication to work.
+=== I can't get LDAP authentication to work.
 What's wrong with my configuration?
 
 Note that the permissions for an LDAP directory often do not allow you to read the password for a user.
@@ -232,7 +232,7 @@ fun ldapAuthenticationIsSuccessful() {
 ----
 ====
 
-==== Session Management
+=== Session Management
 
 Session management issues are a common source of forum questions.
 If you are developing Java web applications, you should understand how the session is maintained between the servlet container and the user's browser.
@@ -242,7 +242,7 @@ This is entirely handled by the servlet container.
 
 
 [[appendix-faq-concurrent-session-same-browser]]
-==== I'm using Spring Security's concurrent session control to prevent users from logging in more than once at a time.
+=== I'm using Spring Security's concurrent session control to prevent users from logging in more than once at a time.
 When I open another browser window after logging in, it doesn't stop me from logging in again.
 Why can I log in more than once?
 
@@ -256,7 +256,7 @@ If they are already authenticated with the same session, then re-authenticating
 
 
 [[appendix-faq-new-session-on-authentication]]
-==== Why does the session Id change when I authenticate through Spring Security?
+=== Why does the session Id change when I authenticate through Spring Security?
 
 With the default configuration, Spring Security changes the session ID when the user authenticates.
 If you're using a Servlet 3.1 or newer container, the session ID is simply changed.
@@ -266,7 +266,7 @@ You can find more about this online and in the reference manual.
 
 
 [[appendix-faq-tomcat-https-session]]
-==== I'm using Tomcat (or some other servlet container) and have enabled HTTPS for my login page, switching back to HTTP afterwards.
+=== I'm using Tomcat (or some other servlet container) and have enabled HTTPS for my login page, switching back to HTTP afterwards.
 It doesn't work - I just end up back at the login page after authenticating.
 
 This happens because sessions created under HTTPS, for which the session cookie is marked as "secure", cannot subsequently be used under HTTP. The browser will not send the cookie back to the server and any session state will be lost (including the security context information). Starting a session in HTTP first should work as the session cookie won't be marked as secure.
@@ -278,13 +278,13 @@ Even clicking on an HTTPS link from a page accessed over HTTP is potentially ris
 If you need more convincing, check out a tool like https://github.com/moxie0/sslstrip/[sslstrip].
 
 
-==== I'm not switching between HTTP and HTTPS but my session is still getting lost
+=== I'm not switching between HTTP and HTTPS but my session is still getting lost
 
 Sessions are maintained either by exchanging a session cookie or by adding a `jsessionid` parameter to URLs (this happens automatically if you are using JSTL to output URLs, or if you call `HttpServletResponse.encodeUrl` on URLs (before a redirect, for example). If clients have cookies disabled, and you are not rewriting URLs to include the `jsessionid`, then the session will be lost.
 Note that the use of cookies is preferred for security reasons, as it does not expose the session information in the URL.
 
 [[appendix-faq-session-listener-missing]]
-==== I'm trying to use the concurrent session-control support but it won't let me log back in, even if I'm sure I've logged out and haven't exceeded the allowed sessions.
+=== I'm trying to use the concurrent session-control support but it won't let me log back in, even if I'm sure I've logged out and haven't exceeded the allowed sessions.
 
 Make sure you have added the listener to your web.xml file.
 It is essential to make sure that the Spring Security session registry is notified when a session is destroyed.
@@ -299,7 +299,7 @@ Without it, the session information will not be removed from the registry.
 ----
 
 [[appendix-faq-unwanted-session-creation]]
-==== Spring Security is creating a session somewhere, even though I've configured it not to, by setting the create-session attribute to never.
+=== Spring Security is creating a session somewhere, even though I've configured it not to, by setting the create-session attribute to never.
 
 This usually means that the user's application is creating a session somewhere, but that they aren't aware of it.
 The most common culprit is a JSP. Many people aren't aware that JSPs create sessions by default.
@@ -308,19 +308,19 @@ To prevent a JSP from creating a session, add the directive `<%@ page session="f
 If you are having trouble working out where a session is being created, you can add some debugging code to track down the location(s). One way to do this would be to add a `javax.servlet.http.HttpSessionListener` to your application, which calls `Thread.dumpStack()` in the `sessionCreated` method.
 
 [[appendix-faq-forbidden-csrf]]
-==== I get a 403 Forbidden when performing a POST
+=== I get a 403 Forbidden when performing a POST
 
 If an HTTP 403 Forbidden is returned for HTTP POST, but works for HTTP GET then the issue is most likely related to https://docs.spring.io/spring-security/site/docs/3.2.x/reference/htmlsingle/#csrf[CSRF]. Either provide the CSRF Token or disable CSRF protection (not recommended).
 
 [[appendix-faq-no-security-on-forward]]
-==== I'm forwarding a request to another URL using the RequestDispatcher, but my security constraints aren't being applied.
+=== I'm forwarding a request to another URL using the RequestDispatcher, but my security constraints aren't being applied.
 
 Filters are not applied by default to forwards or includes.
 If you really want the security filters to be applied to forwards and/or includes, then you have to configure these explicitly in your web.xml using the <dispatcher> element, a child element of <filter-mapping>.
 
 
 [[appendix-faq-method-security-in-web-context]]
-==== I have added Spring Security's <global-method-security> element to my application context but if I add security annotations to my Spring MVC controller beans (Struts actions etc.) then they don't seem to have an effect.
+=== I have added Spring Security's <global-method-security> element to my application context but if I add security annotations to my Spring MVC controller beans (Struts actions etc.) then they don't seem to have an effect.
 
 In a Spring web application, the application context which holds the Spring MVC beans for the dispatcher servlet is often separate from the main application context.
 It is often defined in a file called `myapp-servlet.xml`, where "myapp" is the name assigned to the Spring `DispatcherServlet` in `web.xml`. An application can have multiple ``DispatcherServlet``s, each with its own isolated application context.
@@ -333,7 +333,7 @@ Generally we would recommend applying method security at the service layer rathe
 
 
 [[appendix-faq-no-filters-no-context]]
-==== I have a user who has definitely been authenticated, but when I try to access the SecurityContextHolder during some requests, the Authentication is null.
+=== I have a user who has definitely been authenticated, but when I try to access the SecurityContextHolder during some requests, the Authentication is null.
 Why can't I see the user information?
 
 If you have excluded the request from the security filter chain using the attribute `filters='none'` in the `<intercept-url>` element that matches the URL pattern, then the `SecurityContextHolder` will not be populated for that request.
@@ -341,12 +341,12 @@ Check the debug log to see whether the request is passing through the filter cha
 (You are reading the debug log, right?).
 
 [[appendix-faq-method-security-with-taglib]]
-==== The authorize JSP Tag doesn't respect my method security annotations when using the URL attribute.
+=== The authorize JSP Tag doesn't respect my method security annotations when using the URL attribute.
 
 Method security will not hide links when using the `url` attribute in `<sec:authorize>` because we cannot readily reverse engineer what URL is mapped to what controller endpoint as controllers can rely on headers, current user, etc to determine what method to invoke.
 
 [[appendix-faq-architecture]]
-=== Spring Security Architecture Questions
+== Spring Security Architecture Questions
 
 . <<appendix-faq-where-is-class-x>>
 . <<appendix-faq-namespace-to-bean-mapping>>
@@ -357,14 +357,14 @@ Method security will not hide links when using the `url` attribute in `<sec:auth
 
 
 [[appendix-faq-where-is-class-x]]
-==== How do I know which package class X is in?
+=== How do I know which package class X is in?
 
 The best way of locating classes is by installing the Spring Security source in your IDE. The distribution includes source jars for each of the modules the project is divided up into.
 Add these to your project source path and you can navigate directly to Spring Security classes (`Ctrl-Shift-T` in Eclipse). This also makes debugging easier and allows you to troubleshoot exceptions by looking directly at the code where they occur to see what's going on there.
 
 
 [[appendix-faq-namespace-to-bean-mapping]]
-==== How do the namespace elements map to conventional bean configurations?
+=== How do the namespace elements map to conventional bean configurations?
 
 There is a general overview of what beans are created by the namespace in the namespace appendix of the reference guide.
 There is also a detailed blog article called "Behind the Spring Security Namespace" on https://spring.io/blog/2010/03/06/behind-the-spring-security-namespace/[blog.springsource.com]. If want to know the full details then the code is in the `spring-security-config` module within the Spring Security 3.0 distribution.
@@ -372,7 +372,7 @@ You should probably read the chapters on namespace parsing in the standard Sprin
 
 
 [[appendix-faq-role-prefix]]
-==== What does "ROLE_" mean and why do I need it on my role names?
+=== What does "ROLE_" mean and why do I need it on my role names?
 
 Spring Security has a voter-based architecture which means that an access decision is made by a series of ``AccessDecisionVoter``s.
 The voters act on the "configuration attributes" which are specified for a secured resource (such as a method invocation). With this approach, not all attributes may be relevant to all voters and a voter needs to know when it should ignore an attribute (abstain) and when it should vote to grant or deny access based on the attribute value.
@@ -384,7 +384,7 @@ The prefix can be changed by setting the `rolePrefix` property of `RoleVoter`. I
 
 
 [[appendix-faq-what-dependencies]]
-==== How do I know which dependencies to add to my application to work with Spring Security?
+=== How do I know which dependencies to add to my application to work with Spring Security?
 
 It will depend on what features you are using and what type of application you are developing.
 With Spring Security 3.0, the project jars are divided into clearly distinct areas of functionality, so it is straightforward to work out which Spring Security jars you need from your application requirements.
@@ -403,7 +403,7 @@ Any which are marked as "optional" in the Spring Security POM files will have to
 
 
 [[appendix-faq-apacheds-deps]]
-==== What dependencies are needed to run an embedded ApacheDS LDAP server?
+=== What dependencies are needed to run an embedded ApacheDS LDAP server?
 
 If you are using Maven, you need to add the following to your pom dependencies:
 
@@ -428,7 +428,7 @@ If you are using Maven, you need to add the following to your pom dependencies:
 The other required jars should be pulled in transitively.
 
 [[appendix-faq-what-is-userdetailservice]]
-==== What is a UserDetailsService and do I need one?
+=== What is a UserDetailsService and do I need one?
 
 `UserDetailsService` is a DAO interface for loading data that is specific to a user account.
 It has no other function other to load that data for use by other components within the framework.
@@ -440,7 +440,7 @@ If you want to customize the authentication process then you should implement `A
 See this https://spring.io/blog/2010/08/02/spring-security-in-google-app-engine/[ blog article] for an example integrating Spring Security authentication with Google App Engine.
 
 [[appendix-faq-howto]]
-=== Common "Howto" Requests
+== Common "Howto" Requests
 
 . <<appendix-faq-extra-login-fields>>
 . <<appendix-faq-matching-url-fragments>>
@@ -453,7 +453,7 @@ See this https://spring.io/blog/2010/08/02/spring-security-in-google-app-engine/
 
 
 [[appendix-faq-extra-login-fields]]
-==== I need to login in with more information than just the username.
+=== I need to login in with more information than just the username.
 How do I add support for extra login fields (e.g.
 a company name)?
 
@@ -465,14 +465,14 @@ You will also need to customize the actual authentication process.
 If you are using a custom authentication token class, for example, you will have to write an `AuthenticationProvider` to handle it (or extend the standard `DaoAuthenticationProvider`). If you have concatenated the fields, you can implement your own `UserDetailsService` which splits them up and loads the appropriate user data for authentication.
 
 [[appendix-faq-matching-url-fragments]]
-==== How do I apply different intercept-url constraints where only the fragment value of the requested URLs differs (e.g./foo#bar and /foo#blah?
+=== How do I apply different intercept-url constraints where only the fragment value of the requested URLs differs (e.g./foo#bar and /foo#blah?
 
 You can't do this, since the fragment is not transmitted from the browser to the server.
 The URLs above are identical from the server's perspective.
 This is a common question from GWT users.
 
 [[appendix-faq-request-details-in-user-service]]
-==== How do I access the user's IP Address (or other web-request data) in a UserDetailsService?
+=== How do I access the user's IP Address (or other web-request data) in a UserDetailsService?
 
 Obviously you can't (without resorting to something like thread-local variables) since the only information supplied to the interface is the username.
 Instead of implementing `UserDetailsService`, you should implement `AuthenticationProvider` directly and extract the information from the supplied `Authentication` token.
@@ -482,7 +482,7 @@ If you are using the namespace, for example with the `<form-login>` element, the
 
 
 [[appendix-faq-access-session-from-user-service]]
-==== How do I access the HttpSession from a UserDetailsService?
+=== How do I access the HttpSession from a UserDetailsService?
 
 You can't, since the `UserDetailsService` has no awareness of the servlet API. If you want to store custom user data, then you should customize the `UserDetails` object which is returned.
 This can then be accessed at any point, via the thread-local `SecurityContextHolder`. A call to `SecurityContextHolder.getContext().getAuthentication().getPrincipal()` will return this custom object.
@@ -491,14 +491,14 @@ If you really need to access the session, then it must be done by customizing th
 
 
 [[appendix-faq-password-in-user-service]]
-==== How do I access the user's password in a UserDetailsService?
+=== How do I access the user's password in a UserDetailsService?
 
 You can't (and shouldn't). You are probably misunderstanding its purpose.
 See "<<appendix-faq-what-is-userdetailservice,What is a UserDetailsService?>>" above.
 
 
 [[appendix-faq-dynamic-url-metadata]]
-==== How do I define the secured URLs within an application dynamically?
+=== How do I define the secured URLs within an application dynamically?
 
 People often ask about how to store the mapping between secured URLs and security metadata attributes in a database, rather than in the application context.
 
@@ -575,7 +575,7 @@ For more information, look at the code for `DefaultFilterInvocationSecurityMetad
 
 
 [[appendix-faq-ldap-authorities]]
-==== How do I authenticate against LDAP but load user roles from a database?
+=== How do I authenticate against LDAP but load user roles from a database?
 
 The `LdapAuthenticationProvider` bean (which handles normal LDAP authentication in Spring Security) is configured with two separate strategy interfaces, one which performs the authentication and one which loads the user authorities, called `LdapAuthenticator` and `LdapAuthoritiesPopulator` respectively.
 The `DefaultLdapAuthoritiesPopulator` loads the user authorities from the LDAP directory and has various configuration parameters to allow you to specify how these should be retrieved.
@@ -637,7 +637,7 @@ You should also consult the Javadoc for the relevant classes and interfaces.
 
 
 [[appendix-faq-namespace-post-processor]]
-==== I want to modify the property of a bean that is created by the namespace, but there is nothing in the schema to support it.
+=== I want to modify the property of a bean that is created by the namespace, but there is nothing in the schema to support it.
 What can I do short of abandoning namespace use?
 
 The namespace functionality is intentionally limited, so it doesn't cover everything that you can do with plain beans.
diff --git a/docs/modules/ROOT/pages/servlet/appendix/index.adoc b/docs/modules/ROOT/pages/servlet/appendix/index.adoc
new file mode 100644
index 0000000000..3fecd174b4
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/appendix/index.adoc
@@ -0,0 +1,8 @@
+= Appendix
+
+This is an appendix for Servlet based Spring Security.
+It has the following sections:
+
+* xref:servlet/appendix/database-schema.adoc[Database Schemas]
+* xref:servlet/appendix/namespace.adoc[XML Namespace]
+* xref:servlet/appendix/faq.adoc[FAQ]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc
similarity index 90%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc
rename to docs/modules/ROOT/pages/servlet/appendix/namespace.adoc
index f33d01b906..a6518b4ed1 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc
+++ b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc
@@ -1,40 +1,40 @@
 [[appendix-namespace]]
-== The Security Namespace
+= The Security Namespace
 This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document).
-If you haven't used the namespace before, please read the <<ns-config,introductory chapter>> on namespace configuration, as this is intended as a supplement to the information there.
+If you haven't used the namespace before, please read the xref:servlet/configuration/xml-namespace.adoc#ns-config[introductory chapter] on namespace configuration, as this is intended as a supplement to the information there.
 Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose.
 The namespace is written in https://relaxng.org/[RELAX NG] Compact format and later converted into an XSD schema.
 If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/main/config/src/main/resources/org/springframework/security/config/spring-security-4.1.rnc[schema file] directly.
 
 [[nsa-web]]
-=== Web Application Security
+== Web Application Security
 
 [[nsa-debug]]
-==== <debug>
+=== <debug>
 Enables Spring Security debugging infrastructure.
 This will provide human-readable (multi-line) debugging information to monitor requests coming into the security filters.
 This may include sensitive information, such as request parameters or headers, and should only be used in a development environment.
 
 [[nsa-http]]
-==== <http>
+=== <http>
 If you use an `<http>` element within your application, a `FilterChainProxy` bean named "springSecurityFilterChain" is created and the configuration within the element is used to build a filter chain within
 `FilterChainProxy`.
-As of Spring Security 3.1, additional `http` elements can be used to add extra filter chains footnote:[See the pass:specialcharacters,macros[<<ns-web-xml,introductory chapter>>] for how to set up the mapping from your `web.xml` ].
+As of Spring Security 3.1, additional `http` elements can be used to add extra filter chains footnote:[See the pass:specialcharacters,macros[xref:servlet/configuration/xml-namespace.adoc#ns-web-xml[introductory chapter]] for how to set up the mapping from your `web.xml` ].
 Some core filters are always created in a filter chain and others will be added to the stack depending on the attributes and child elements which are present.
 The positions of the standard filters are fixed (see
-<<filter-stack,the filter order table>> in the namespace introduction), removing a common source of errors with previous versions of the framework when users had to configure the filter chain explicitly in the
+xref:servlet/configuration/xml-namespace.adoc#filter-stack[the filter order table] in the namespace introduction), removing a common source of errors with previous versions of the framework when users had to configure the filter chain explicitly in the
 `FilterChainProxy` bean.
 You can, of course, still do this if you need full control of the configuration.
 
 
-All filters which require a reference to the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> will be automatically injected with the internal instance created by the namespace configuration.
+All filters which require a reference to the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] will be automatically injected with the internal instance created by the namespace configuration.
 
 Each `<http>` namespace block always creates an `SecurityContextPersistenceFilter`, an `ExceptionTranslationFilter` and a `FilterSecurityInterceptor`.
 These are fixed and cannot be replaced with alternatives.
 
 
 [[nsa-http-attributes]]
-===== <http> Attributes
+==== <http> Attributes
 The attributes on the `<http>` element control some of the properties on the core filters.
 
 
@@ -146,12 +146,12 @@ Defaults to `true`.
 
 [[nsa-http-use-expressions]]
 * **use-expressions**
-Enables EL-expressions in the `access` attribute, as described in the chapter on <<el-access-web,expression-based access-control>>.
+Enables EL-expressions in the `access` attribute, as described in the chapter on xref:servlet/authorization/expression-based.adoc#el-access-web[expression-based access-control].
 The default value is true.
 
 
 [[nsa-http-children]]
-===== Child Elements of <http>
+==== Child Elements of <http>
 * <<nsa-access-denied-handler,access-denied-handler>>
 * <<nsa-anonymous,anonymous>>
 * <<nsa-cors,cors>>
@@ -177,18 +177,18 @@ The default value is true.
 
 
 [[nsa-access-denied-handler]]
-==== <access-denied-handler>
+=== <access-denied-handler>
 This element allows you to set the `errorPage` property for the default `AccessDeniedHandler` used by the `ExceptionTranslationFilter`, using the <<nsa-access-denied-handler-error-page,error-page>> attribute, or to supply your own implementation using the<<nsa-access-denied-handler-ref,ref>> attribute.
-This is discussed in more detail in the section on the <<servlet-exceptiontranslationfilter,ExceptionTranslationFilter>>.
+This is discussed in more detail in the section on the xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[ExceptionTranslationFilter].
 
 
 [[nsa-access-denied-handler-parents]]
-===== Parent Elements of <access-denied-handler>
+==== Parent Elements of <access-denied-handler>
 
 * <<nsa-http,http>>
 
 [[nsa-access-denied-handler-attributes]]
-===== <access-denied-handler> Attributes
+==== <access-denied-handler> Attributes
 
 
 [[nsa-access-denied-handler-error-page]]
@@ -202,12 +202,12 @@ Defines a reference to a Spring bean of type `AccessDeniedHandler`.
 
 
 [[nsa-cors]]
-==== <cors>
+=== <cors>
 This element allows for configuring a `CorsFilter`.
 If no `CorsFilter` or `CorsConfigurationSource` is specified and Spring MVC is on the classpath, a `HandlerMappingIntrospector` is used as the `CorsConfigurationSource`.
 
 [[nsa-cors-attributes]]
-===== <cors> Attributes
+==== <cors> Attributes
 The attributes on the `<cors>` element control the headers element.
 
 [[nsa-cors-ref]]
@@ -219,15 +219,15 @@ Optional attribute that specifies the bean name of a `CorsFilter`.
 Optional attribute that specifies the bean name of a `CorsConfigurationSource` to be injected into a `CorsFilter` created by the XML namespace.
 
 [[nsa-cors-parents]]
-===== Parent Elements of <cors>
+==== Parent Elements of <cors>
 
 * <<nsa-http,http>>
 
 [[nsa-headers]]
-==== <headers>
+=== <headers>
 This element allows for configuring additional (security) headers to be send with the response.
 It enables easy configuration for several headers and also allows for setting custom headers through the <<nsa-header,header>> element.
-Additional information, can be found in the <<headers,Security Headers>> section of the reference.
+Additional information, can be found in the xref:features/exploits/headers.adoc#headers[Security Headers] section of the reference.
 
 ** `Cache-Control`, `Pragma`, and `Expires` - Can be set using the <<nsa-cache-control,cache-control>> element.
 This ensures that the browser does not cache your secured pages.
@@ -248,7 +248,7 @@ https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] is a mechanism that w
 ** `Feature-Policy` - Can be set using the <<nsa-feature-policy,feature-policy>> element, https://wicg.github.io/feature-policy/[Feature-Policy] is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
 
 [[nsa-headers-attributes]]
-===== <headers> Attributes
+==== <headers> Attributes
 The attributes on the `<headers>` element control the headers element.
 
 
@@ -264,14 +264,14 @@ The default is false (the headers are enabled).
 
 
 [[nsa-headers-parents]]
-===== Parent Elements of <headers>
+==== Parent Elements of <headers>
 
 * <<nsa-http,http>>
 
 
 
 [[nsa-headers-children]]
-===== Child Elements of <headers>
+==== Child Elements of <headers>
 
 
 * <<nsa-cache-control,cache-control>>
@@ -289,12 +289,12 @@ The default is false (the headers are enabled).
 
 
 [[nsa-cache-control]]
-==== <cache-control>
+=== <cache-control>
 Adds `Cache-Control`, `Pragma`, and `Expires` headers to ensure that the browser does not cache your secured pages.
 
 
 [[nsa-cache-control-attributes]]
-===== <cache-control> Attributes
+==== <cache-control> Attributes
 
 [[nsa-cache-control-disabled]]
 * **disabled**
@@ -303,7 +303,7 @@ Default false.
 
 
 [[nsa-cache-control-parents]]
-===== Parent Elements of <cache-control>
+==== Parent Elements of <cache-control>
 
 
 * <<nsa-headers,headers>>
@@ -311,13 +311,13 @@ Default false.
 
 
 [[nsa-hsts]]
-==== <hsts>
+=== <hsts>
 When enabled adds the https://tools.ietf.org/html/rfc6797[Strict-Transport-Security] header to the response for any secure request.
 This allows the server to instruct browsers to automatically use HTTPS for future requests.
 
 
 [[nsa-hsts-attributes]]
-===== <hsts> Attributes
+==== <hsts> Attributes
 
 [[nsa-hsts-disabled]]
 * **disabled**
@@ -347,20 +347,20 @@ Specifies if preload should be included.
 Default false.
 
 [[nsa-hsts-parents]]
-===== Parent Elements of <hsts>
+==== Parent Elements of <hsts>
 
 * <<nsa-headers,headers>>
 
 
 
 [[nsa-hpkp]]
-==== <hpkp>
+=== <hpkp>
 When enabled adds the https://tools.ietf.org/html/rfc7469[Public Key Pinning Extension for HTTP] header to the response for any secure request.
 This allows HTTPS websites to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates.
 
 
 [[nsa-hpkp-attributes]]
-===== <hpkp> Attributes
+==== <hpkp> Attributes
 
 [[nsa-hpkp-disabled]]
 * **disabled**
@@ -391,28 +391,28 @@ Specifies the URI to which the browser should report pin validation failures.
 
 
 [[nsa-hpkp-parents]]
-===== Parent Elements of <hpkp>
+==== Parent Elements of <hpkp>
 
 * <<nsa-headers,headers>>
 
 
 [[nsa-pins]]
-==== <pins>
+=== <pins>
 The list of pins
 
 
 [[nsa-pins-children]]
-===== Child Elements of <pins>
+==== Child Elements of <pins>
 
 * <<nsa-pin,pin>>
 
 
 [[nsa-pin]]
-==== <pin>
+=== <pin>
 A pin is specified using the base64-encoded SPKI fingerprint as value and the cryptographic hash algorithm as attribute
 
 [[nsa-pin-attributes]]
-===== <pin> Attributes
+==== <pin> Attributes
 
 [[nsa-pin-algorithm]]
 * **algorithm**
@@ -421,19 +421,19 @@ Default is SHA256.
 
 
 [[nsa-pin-parents]]
-===== Parent Elements of <pin>
+==== Parent Elements of <pin>
 
 * <<nsa-pins,pins>>
 
 
 
 [[nsa-content-security-policy]]
-==== <content-security-policy>
+=== <content-security-policy>
 When enabled adds the https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] header to the response.
 CSP is a mechanism that web applications can leverage to mitigate content injection vulnerabilities, such as cross-site scripting (XSS).
 
 [[nsa-content-security-policy-attributes]]
-===== <content-security-policy> Attributes
+==== <content-security-policy> Attributes
 
 [[nsa-content-security-policy-policy-directives]]
 * **policy-directives**
@@ -445,18 +445,18 @@ Set to true, to enable the Content-Security-Policy-Report-Only header for report
 Defaults to false.
 
 [[nsa-content-security-policy-parents]]
-===== Parent Elements of <content-security-policy>
+==== Parent Elements of <content-security-policy>
 
 * <<nsa-headers,headers>>
 
 
 
 [[nsa-referrer-policy]]
-==== <referrer-policy>
+=== <referrer-policy>
 When enabled adds the https://www.w3.org/TR/referrer-policy/[Referrer Policy] header to the response.
 
 [[nsa-referrer-policy-attributes]]
-===== <referrer-policy> Attributes
+==== <referrer-policy> Attributes
 
 [[nsa-referrer-policy-policy]]
 * **policy**
@@ -464,37 +464,37 @@ The policy for the Referrer-Policy header.
 Default "no-referrer".
 
 [[nsa-referrer-policy-parents]]
-===== Parent Elements of <referrer-policy>
+==== Parent Elements of <referrer-policy>
 
 * <<nsa-headers,headers>>
 
 
 
 [[nsa-feature-policy]]
-==== <feature-policy>
+=== <feature-policy>
 When enabled adds the https://wicg.github.io/feature-policy/[Feature Policy] header to the response.
 
 [[nsa-feature-policy-attributes]]
-===== <feature-policy> Attributes
+==== <feature-policy> Attributes
 
 [[nsa-feature-policy-policy-directives]]
 * **policy-directives**
 The security policy directive(s) for the Feature-Policy header.
 
 [[nsa-feature-policy-parents]]
-===== Parent Elements of <feature-policy>
+==== Parent Elements of <feature-policy>
 
 * <<nsa-headers,headers>>
 
 
 
 [[nsa-frame-options]]
-==== <frame-options>
+=== <frame-options>
 When enabled adds the https://tools.ietf.org/html/draft-ietf-websec-x-frame-options[X-Frame-Options header] to the response, this allows newer browsers to do some security checks and prevent https://en.wikipedia.org/wiki/Clickjacking[clickjacking] attacks.
 
 
 [[nsa-frame-options-attributes]]
-===== <frame-options> Attributes
+==== <frame-options> Attributes
 
 [[nsa-frame-options-disabled]]
 * **disabled**
@@ -515,34 +515,34 @@ On the other hand, if you specify SAMEORIGIN, you can still use the page in a fr
 
 
 [[nsa-frame-options-parents]]
-===== Parent Elements of <frame-options>
+==== Parent Elements of <frame-options>
 
 * <<nsa-headers,headers>>
 
 [[nsa-permissions-policy]]
-==== <permissions-policy>
+=== <permissions-policy>
 Adds the https://w3c.github.io/webappsec-permissions-policy/[Permissions-Policy header] to the response.
 
 [[nsa-permissions-policy-attributes]]
-===== <permissions-policy> Attributes
+==== <permissions-policy> Attributes
 
 [[nsa-permissions-policy-policy]]
 * **policy**
 The policy value to write for the `Permissions-Policy` header
 
 [[nsa-permissions-policy-parents]]
-===== Parent Elements of <permissions-policy>
+==== Parent Elements of <permissions-policy>
 
 * <<nsa-headers,headers>>
 
 [[nsa-xss-protection]]
-==== <xss-protection>
+=== <xss-protection>
 Adds the https://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx[X-XSS-Protection header] to the response to assist in protecting against https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] attacks.
 This is in no-way a full protection to XSS attacks!
 
 
 [[nsa-xss-protection-attributes]]
-===== <xss-protection> Attributes
+==== <xss-protection> Attributes
 
 
 [[nsa-xss-protection-disabled]]
@@ -564,20 +564,20 @@ Note that there are sometimes ways of bypassing this mode which can often times
 
 
 [[nsa-xss-protection-parents]]
-===== Parent Elements of <xss-protection>
+==== Parent Elements of <xss-protection>
 
 * <<nsa-headers,headers>>
 
 
 
 [[nsa-content-type-options]]
-==== <content-type-options>
+=== <content-type-options>
 Add the X-Content-Type-Options header with the value of nosniff to the response.
 This https://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx[disables MIME-sniffing] for IE8+ and Chrome extensions.
 
 
 [[nsa-content-type-options-attributes]]
-===== <content-type-options> Attributes
+==== <content-type-options> Attributes
 
 [[nsa-content-type-options-disabled]]
 * **disabled**
@@ -585,7 +585,7 @@ Specifies if Content Type Options should be disabled.
 Default false.
 
 [[nsa-content-type-options-parents]]
-===== Parent Elements of <content-type-options>
+==== Parent Elements of <content-type-options>
 
 
 * <<nsa-headers,headers>>
@@ -593,12 +593,12 @@ Default false.
 
 
 [[nsa-header]]
-==== <header>
+=== <header>
 Add additional headers to the response, both the name and value need to be specified.
 
 
 [[nsa-header-attributes]]
-===== <header-attributes> Attributes
+==== <header-attributes> Attributes
 
 
 [[nsa-header-name]]
@@ -617,7 +617,7 @@ Reference to a custom implementation of the `HeaderWriter` interface.
 
 
 [[nsa-header-parents]]
-===== Parent Elements of <header>
+==== Parent Elements of <header>
 
 
 * <<nsa-headers,headers>>
@@ -625,13 +625,13 @@ Reference to a custom implementation of the `HeaderWriter` interface.
 
 
 [[nsa-anonymous]]
-==== <anonymous>
+=== <anonymous>
 Adds an `AnonymousAuthenticationFilter` to the stack and an `AnonymousAuthenticationProvider`.
 Required if you are using the `IS_AUTHENTICATED_ANONYMOUSLY` attribute.
 
 
 [[nsa-anonymous-parents]]
-===== Parent Elements of <anonymous>
+==== Parent Elements of <anonymous>
 
 
 * <<nsa-http,http>>
@@ -639,7 +639,7 @@ Required if you are using the `IS_AUTHENTICATED_ANONYMOUSLY` attribute.
 
 
 [[nsa-anonymous-attributes]]
-===== <anonymous> Attributes
+==== <anonymous> Attributes
 
 
 [[nsa-anonymous-enabled]]
@@ -671,14 +671,14 @@ if unset, defaults to `anonymousUser`.
 
 
 [[nsa-csrf]]
-==== <csrf>
+=== <csrf>
 This element will add https://en.wikipedia.org/wiki/Cross-site_request_forgery[Cross Site Request Forger (CSRF)] protection to the application.
 It also updates the default RequestCache to only replay "GET" requests upon successful authentication.
-Additional information can be found in the <<csrf,Cross Site Request Forgery (CSRF)>> section of the reference.
+Additional information can be found in the xref:features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] section of the reference.
 
 
 [[nsa-csrf-parents]]
-===== Parent Elements of <csrf>
+==== Parent Elements of <csrf>
 
 
 * <<nsa-http,http>>
@@ -686,7 +686,7 @@ Additional information can be found in the <<csrf,Cross Site Request Forgery (CS
 
 
 [[nsa-csrf-attributes]]
-===== <csrf> Attributes
+==== <csrf> Attributes
 
 [[nsa-csrf-disabled]]
 * **disabled**
@@ -707,14 +707,14 @@ Default is any HTTP method except "GET", "TRACE", "HEAD", "OPTIONS".
 
 
 [[nsa-custom-filter]]
-==== <custom-filter>
+=== <custom-filter>
 This element is used to add a filter to the filter chain.
 It doesn't create any additional beans but is used to select a bean of type `javax.servlet.Filter` which is already defined in the application context and add that at a particular position in the filter chain maintained by Spring Security.
-Full details can be found in the <<ns-custom-filters, namespace chapter>>.
+Full details can be found in the xref:servlet/configuration/xml-namespace.adoc#ns-custom-filters[ namespace chapter].
 
 
 [[nsa-custom-filter-parents]]
-===== Parent Elements of <custom-filter>
+==== Parent Elements of <custom-filter>
 
 
 * <<nsa-http,http>>
@@ -722,7 +722,7 @@ Full details can be found in the <<ns-custom-filters, namespace chapter>>.
 
 
 [[nsa-custom-filter-attributes]]
-===== <custom-filter> Attributes
+==== <custom-filter> Attributes
 
 
 [[nsa-custom-filter-after]]
@@ -749,13 +749,13 @@ Defines a reference to a Spring bean that implements `Filter`.
 
 
 [[nsa-expression-handler]]
-==== <expression-handler>
+=== <expression-handler>
 Defines the `SecurityExpressionHandler` instance which will be used if expression-based access-control is enabled.
 A default implementation (with no ACL support) will be used if not supplied.
 
 
 [[nsa-expression-handler-parents]]
-===== Parent Elements of <expression-handler>
+==== Parent Elements of <expression-handler>
 
 
 * <<nsa-global-method-security,global-method-security>>
@@ -766,7 +766,7 @@ A default implementation (with no ACL support) will be used if not supplied.
 
 
 [[nsa-expression-handler-attributes]]
-===== <expression-handler> Attributes
+==== <expression-handler> Attributes
 
 
 [[nsa-expression-handler-ref]]
@@ -775,7 +775,7 @@ Defines a reference to a Spring bean that implements `SecurityExpressionHandler`
 
 
 [[nsa-form-login]]
-==== <form-login>
+=== <form-login>
 Used to add an `UsernamePasswordAuthenticationFilter` to the filter stack and an `LoginUrlAuthenticationEntryPoint` to the application context to provide authentication on demand.
 This will always take precedence over other namespace-created entry points.
 If no attributes are supplied, a login page will be generated automatically at the URL "/login" footnote:[
@@ -785,7 +785,7 @@ The class `DefaultLoginPageGeneratingFilter` is responsible for rendering the lo
 
 
 [[nsa-form-login-parents]]
-===== Parent Elements of <form-login>
+==== Parent Elements of <form-login>
 
 
 * <<nsa-http,http>>
@@ -793,7 +793,7 @@ The class `DefaultLoginPageGeneratingFilter` is responsible for rendering the lo
 
 
 [[nsa-form-login-attributes]]
-===== <form-login> Attributes
+==== <form-login> Attributes
 
 
 [[nsa-form-login-always-use-default-target]]
@@ -870,17 +870,17 @@ Maps a `ForwardAuthenticationFailureHandler` to `authenticationFailureHandler` p
 
 
 [[nsa-oauth2-login]]
-==== <oauth2-login>
-The <<oauth2login,OAuth 2.0 Login>> feature configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider.
+=== <oauth2-login>
+The xref:servlet/oauth2/oauth2-login.adoc#oauth2login[OAuth 2.0 Login] feature configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider.
 
 
 [[nsa-oauth2-login-parents]]
-===== Parent Elements of <oauth2-login>
+==== Parent Elements of <oauth2-login>
 
 * <<nsa-http,http>>
 
 [[nsa-oauth2-login-attributes]]
-===== <oauth2-login> Attributes
+==== <oauth2-login> Attributes
 
 
 [[nsa-oauth2-login-client-registration-repository-ref]]
@@ -954,17 +954,17 @@ Reference to the `JwtDecoderFactory` used by `OidcAuthorizationCodeAuthenticatio
 
 
 [[nsa-oauth2-client]]
-==== <oauth2-client>
-Configures <<oauth2client,OAuth 2.0 Client>> support.
+=== <oauth2-client>
+Configures xref:servlet/oauth2/oauth2-client.adoc#oauth2client[OAuth 2.0 Client] support.
 
 
 [[nsa-oauth2-client-parents]]
-===== Parent Elements of <oauth2-client>
+==== Parent Elements of <oauth2-client>
 
 * <<nsa-http,http>>
 
 [[nsa-oauth2-client-attributes]]
-===== <oauth2-client> Attributes
+==== <oauth2-client> Attributes
 
 
 [[nsa-oauth2-client-client-registration-repository-ref]]
@@ -983,24 +983,24 @@ Reference to the `OAuth2AuthorizedClientService`.
 
 
 [[nsa-oauth2-client-children]]
-===== Child Elements of <oauth2-client>
+==== Child Elements of <oauth2-client>
 
 * <<nsa-authorization-code-grant,authorization-code-grant>>
 
 
 [[nsa-authorization-code-grant]]
-==== <authorization-code-grant>
-Configures <<oauth2Client-auth-grant-support,OAuth 2.0 Authorization Code Grant>>.
+=== <authorization-code-grant>
+Configures xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-grant-support[OAuth 2.0 Authorization Code Grant].
 
 
 [[nsa-authorization-code-grant-parents]]
-===== Parent Elements of <authorization-code-grant>
+==== Parent Elements of <authorization-code-grant>
 
 * <<nsa-oauth2-client,oauth2-client>>
 
 
 [[nsa-authorization-code-grant-attributes]]
-===== <authorization-code-grant> Attributes
+==== <authorization-code-grant> Attributes
 
 
 [[nsa-authorization-code-grant-authorization-request-repository-ref]]
@@ -1019,30 +1019,30 @@ Reference to the `OAuth2AccessTokenResponseClient`.
 
 
 [[nsa-client-registrations]]
-==== <client-registrations>
-A container element for client(s) registered (<<oauth2Client-client-registration,ClientRegistration>>) with an OAuth 2.0 or OpenID Connect 1.0 Provider.
+=== <client-registrations>
+A container element for client(s) registered (xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration]) with an OAuth 2.0 or OpenID Connect 1.0 Provider.
 
 
 [[nsa-client-registrations-children]]
-===== Child Elements of <client-registrations>
+==== Child Elements of <client-registrations>
 
 * <<nsa-client-registration,client-registration>>
 * <<nsa-provider,provider>>
 
 
 [[nsa-client-registration]]
-==== <client-registration>
+=== <client-registration>
 Represents a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider.
 
 
 [[nsa-client-registration-parents]]
-===== Parent Elements of <client-registration>
+==== Parent Elements of <client-registration>
 
 * <<nsa-client-registrations,client-registrations>>
 
 
 [[nsa-client-registration-attributes]]
-===== <client-registration> Attributes
+==== <client-registration> Attributes
 
 
 [[nsa-client-registration-registration-id]]
@@ -1093,18 +1093,18 @@ A reference to the associated provider. May reference a `<provider>` element or
 
 
 [[nsa-provider]]
-==== <provider>
+=== <provider>
 The configuration information for an OAuth 2.0 or OpenID Connect 1.0 Provider.
 
 
 [[nsa-provider-parents]]
-===== Parent Elements of <provider>
+==== Parent Elements of <provider>
 
 * <<nsa-client-registrations,client-registrations>>
 
 
 [[nsa-provider-attributes]]
-===== <provider> Attributes
+==== <provider> Attributes
 
 
 [[nsa-provider-provider-id]]
@@ -1148,23 +1148,23 @@ The URI used to retrieve the https://tools.ietf.org/html/rfc7517[JSON Web Key (J
 The URI used to initially configure a `ClientRegistration` using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint].
 
 [[nsa-oauth2-resource-server]]
-==== <oauth2-resource-server>
+=== <oauth2-resource-server>
 Adds a `BearerTokenAuthenticationFilter`, `BearerTokenAuthenticationEntryPoint`, and `BearerTokenAccessDeniedHandler` to the configuration.
 In addition, either `<jwt>` or `<opaque-token>` must be specified.
 
 [[nsa-oauth2-resource-server-parents]]
-===== Parents Elements of <oauth2-resource-server>
+==== Parents Elements of <oauth2-resource-server>
 
 * <<nsa-http,http>>
 
 [[nsa-oauth2-resource-server-children]]
-===== Child Elements of <oauth2-resource-server>
+==== Child Elements of <oauth2-resource-server>
 
 * <<nsa-jwt,jwt>>
 * <<nsa-opaque-token,opaque-token>>
 
 [[nsa-oauth2-resource-server-attributes]]
-===== <oauth2-resource-server> Attributes
+==== <oauth2-resource-server> Attributes
 
 [[nsa-oauth2-resource-server-authentication-manager-resolver-ref]]
 * **authentication-manager-resolver-ref**
@@ -1179,18 +1179,18 @@ Reference to a `BearerTokenResolver` which will retrieve the bearer token from t
 Reference to a `AuthenticationEntryPoint` which will handle unauthorized requests
 
 [[nsa-jwt]]
-==== <jwt>
+=== <jwt>
 Represents an OAuth 2.0 Resource Server that will authorize JWTs
 
 
 [[nsa-jwt-parents]]
-===== Parent Elements of <jwt>
+==== Parent Elements of <jwt>
 
 * <<nsa-oauth2-resource-server,oauth2-resource-server>>
 
 
 [[nsa-jwt-attributes]]
-===== <jwt> Attributes
+==== <jwt> Attributes
 
 [[nsa-jwt-jwt-authentication-converter-ref]]
 * **jwt-authentication-converter-ref**
@@ -1205,16 +1205,16 @@ Reference to a `JwtDecoder`. This is a larger component that overrides `jwk-set-
 The JWK Set Uri used to load signing verification keys from an OAuth 2.0 Authorization Server
 
 [[nsa-opaque-token]]
-==== <opaque-token>
+=== <opaque-token>
 Represents an OAuth 2.0 Resource Server that will authorize opaque tokens
 
 [[nsa-opaque-token-parents]]
-===== Parent Elements of <opaque-token>
+==== Parent Elements of <opaque-token>
 
 * <<nsa-oauth2-resource-server,oauth2-resource-server>>
 
 [[nsa-opaque-token-attributes]]
-===== <opaque-token> Attributes
+==== <opaque-token> Attributes
 
 [[nsa-opaque-token-introspector-ref]]
 * **introspector-ref**
@@ -1233,13 +1233,13 @@ The Client Id to use for client authentication against the provided `introspecti
 The Client Secret to use for client authentication against the provided `introspection-uri`.
 
 [[nsa-http-basic]]
-==== <http-basic>
+=== <http-basic>
 Adds a `BasicAuthenticationFilter` and `BasicAuthenticationEntryPoint` to the configuration.
 The latter will only be used as the configuration entry point if form-based login is not enabled.
 
 
 [[nsa-http-basic-parents]]
-===== Parent Elements of <http-basic>
+==== Parent Elements of <http-basic>
 
 
 * <<nsa-http,http>>
@@ -1247,7 +1247,7 @@ The latter will only be used as the configuration entry point if form-based logi
 
 
 [[nsa-http-basic-attributes]]
-===== <http-basic> Attributes
+==== <http-basic> Attributes
 
 
 [[nsa-http-basic-authentication-details-source-ref]]
@@ -1261,13 +1261,13 @@ Sets the `AuthenticationEntryPoint` which is used by the `BasicAuthenticationFil
 
 
 [[nsa-http-firewall]]
-==== <http-firewall> Element
+=== <http-firewall> Element
 This is a top-level element which can be used to inject a custom implementation of `HttpFirewall` into the `FilterChainProxy` created by the namespace.
 The default implementation should be suitable for most applications.
 
 
 [[nsa-http-firewall-attributes]]
-===== <http-firewall> Attributes
+==== <http-firewall> Attributes
 
 
 [[nsa-http-firewall-ref]]
@@ -1276,7 +1276,7 @@ Defines a reference to a Spring bean that implements `HttpFirewall`.
 
 
 [[nsa-intercept-url]]
-==== <intercept-url>
+=== <intercept-url>
 This element is used to define the set of URL patterns that the application is interested in and to configure how they should be handled.
 It is used to construct the `FilterInvocationSecurityMetadataSource` used by the `FilterSecurityInterceptor`.
 It is also responsible for configuring a `ChannelProcessingFilter` if particular URLs need to be accessed by HTTPS, for example.
@@ -1285,7 +1285,7 @@ So the most specific patterns should come first and the most general should come
 
 
 [[nsa-intercept-url-parents]]
-===== Parent Elements of <intercept-url>
+==== Parent Elements of <intercept-url>
 
 
 * <<nsa-filter-security-metadata-source,filter-security-metadata-source>>
@@ -1294,7 +1294,7 @@ So the most specific patterns should come first and the most general should come
 
 
 [[nsa-intercept-url-attributes]]
-===== <intercept-url> Attributes
+==== <intercept-url> Attributes
 
 
 [[nsa-intercept-url-access]]
@@ -1341,12 +1341,12 @@ NOTE: This property is invalid for <<nsa-filter-security-metadata-source,filter-
 
 
 [[nsa-jee]]
-==== <jee>
+=== <jee>
 Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integration with container authentication.
 
 
 [[nsa-jee-parents]]
-===== Parent Elements of <jee>
+==== Parent Elements of <jee>
 
 
 * <<nsa-http,http>>
@@ -1354,7 +1354,7 @@ Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integ
 
 
 [[nsa-jee-attributes]]
-===== <jee> Attributes
+==== <jee> Attributes
 
 
 [[nsa-jee-mappable-roles]]
@@ -1368,13 +1368,13 @@ A reference to a user-service (or UserDetailsService bean) Id
 
 
 [[nsa-logout]]
-==== <logout>
+=== <logout>
 Adds a `LogoutFilter` to the filter stack.
 This is configured with a `SecurityContextLogoutHandler`.
 
 
 [[nsa-logout-parents]]
-===== Parent Elements of <logout>
+==== Parent Elements of <logout>
 
 
 * <<nsa-http,http>>
@@ -1382,7 +1382,7 @@ This is configured with a `SecurityContextLogoutHandler`.
 
 
 [[nsa-logout-attributes]]
-===== <logout> Attributes
+==== <logout> Attributes
 
 
 [[nsa-logout-delete-cookies]]
@@ -1419,7 +1419,7 @@ May be used to supply an instance of `LogoutSuccessHandler` which will be invoke
 
 
 [[nsa-openid-login]]
-==== <openid-login>
+=== <openid-login>
 Similar to `<form-login>` and has the same attributes.
 The default value for `login-processing-url` is "/login/openid".
 An `OpenIDAuthenticationFilter` and `OpenIDAuthenticationProvider` will be registered.
@@ -1428,7 +1428,7 @@ Again, this can be specified by `id`, using the `user-service-ref` attribute, or
 
 
 [[nsa-openid-login-parents]]
-===== Parent Elements of <openid-login>
+==== Parent Elements of <openid-login>
 
 
 * <<nsa-http,http>>
@@ -1436,7 +1436,7 @@ Again, this can be specified by `id`, using the `user-service-ref` attribute, or
 
 
 [[nsa-openid-login-attributes]]
-===== <openid-login> Attributes
+==== <openid-login> Attributes
 
 
 [[nsa-openid-login-always-use-default-target]]
@@ -1514,21 +1514,21 @@ Defaults to "username".
 
 
 [[nsa-openid-login-children]]
-===== Child Elements of <openid-login>
+==== Child Elements of <openid-login>
 * <<nsa-attribute-exchange,attribute-exchange>>
 
 
 
 [[nsa-attribute-exchange]]
-==== <attribute-exchange>
+=== <attribute-exchange>
 The `attribute-exchange` element defines the list of attributes which should be requested from the identity provider.
-An example can be found in the <<servlet-openid,OpenID Support>> section of the namespace configuration chapter.
+An example can be found in the xref:servlet/authentication/openid.adoc#servlet-openid[OpenID Support] section of the namespace configuration chapter.
 More than one can be used, in which case each must have an `identifier-match` attribute, containing a regular expression which is matched against the supplied OpenID identifier.
 This allows different attribute lists to be fetched from different providers (Google, Yahoo etc).
 
 
 [[nsa-attribute-exchange-parents]]
-===== Parent Elements of <attribute-exchange>
+==== Parent Elements of <attribute-exchange>
 
 
 * <<nsa-openid-login,openid-login>>
@@ -1536,7 +1536,7 @@ This allows different attribute lists to be fetched from different providers (Go
 
 
 [[nsa-attribute-exchange-attributes]]
-===== <attribute-exchange> Attributes
+==== <attribute-exchange> Attributes
 
 
 [[nsa-attribute-exchange-identifier-match]]
@@ -1545,7 +1545,7 @@ A regular expression which will be compared against the claimed identity, when d
 
 
 [[nsa-attribute-exchange-children]]
-===== Child Elements of <attribute-exchange>
+==== Child Elements of <attribute-exchange>
 
 
 * <<nsa-openid-attribute,openid-attribute>>
@@ -1553,12 +1553,12 @@ A regular expression which will be compared against the claimed identity, when d
 
 
 [[nsa-openid-attribute]]
-==== <openid-attribute>
+=== <openid-attribute>
 Attributes used when making an OpenID AX https://openid.net/specs/openid-attribute-exchange-1_0.html#fetch_request[ Fetch Request]
 
 
 [[nsa-openid-attribute-parents]]
-===== Parent Elements of <openid-attribute>
+==== Parent Elements of <openid-attribute>
 
 
 * <<nsa-attribute-exchange,attribute-exchange>>
@@ -1566,7 +1566,7 @@ Attributes used when making an OpenID AX https://openid.net/specs/openid-attribu
 
 
 [[nsa-openid-attribute-attributes]]
-===== <openid-attribute> Attributes
+==== <openid-attribute> Attributes
 
 
 [[nsa-openid-attribute-count]]
@@ -1595,32 +1595,32 @@ For example, https://axschema.org/contact/email.
 See your OP's documentation for valid attribute types.
 
 [[nsa-password-management]]
-==== <password-management>
+=== <password-management>
 This element configures password management.
 
 [[nsa-password-management-parents]]
-===== Parent Elements of <password-management>
+==== Parent Elements of <password-management>
 
 * <<nsa-http,http>>
 
 [[nsa-password-management-attributes]]
-===== <password-management> Attributes
+==== <password-management> Attributes
 
 [[nsa-password-management-change-password-page]]
 * **change-password-page**
 The change password page. Defaults to "/change-password".
 
 [[nsa-port-mappings]]
-==== <port-mappings>
+=== <port-mappings>
 By default, an instance of `PortMapperImpl` will be added to the configuration for use in redirecting to secure and insecure URLs.
 This element can optionally be used to override the default mappings which that class defines.
 Each child `<port-mapping>` element defines a pair of HTTP:HTTPS ports.
 The default mappings are 80:443 and 8080:8443.
-An example of overriding these can be found in <<servlet-http-redirect>>.
+An example of overriding these can be found in xref:servlet/exploits/http.adoc#servlet-http-redirect[Redirect to HTTPS].
 
 
 [[nsa-port-mappings-parents]]
-===== Parent Elements of <port-mappings>
+==== Parent Elements of <port-mappings>
 
 
 * <<nsa-http,http>>
@@ -1628,7 +1628,7 @@ An example of overriding these can be found in <<servlet-http-redirect>>.
 
 
 [[nsa-port-mappings-children]]
-===== Child Elements of <port-mappings>
+==== Child Elements of <port-mappings>
 
 
 * <<nsa-port-mapping,port-mapping>>
@@ -1636,12 +1636,12 @@ An example of overriding these can be found in <<servlet-http-redirect>>.
 
 
 [[nsa-port-mapping]]
-==== <port-mapping>
+=== <port-mapping>
 Provides a method to map http ports to https ports when forcing a redirect.
 
 
 [[nsa-port-mapping-parents]]
-===== Parent Elements of <port-mapping>
+==== Parent Elements of <port-mapping>
 
 
 * <<nsa-port-mappings,port-mappings>>
@@ -1649,7 +1649,7 @@ Provides a method to map http ports to https ports when forcing a redirect.
 
 
 [[nsa-port-mapping-attributes]]
-===== <port-mapping> Attributes
+==== <port-mapping> Attributes
 
 
 [[nsa-port-mapping-http]]
@@ -1663,13 +1663,13 @@ The https port to use.
 
 
 [[nsa-remember-me]]
-==== <remember-me>
+=== <remember-me>
 Adds the `RememberMeAuthenticationFilter` to the stack.
 This in turn will be configured with either a `TokenBasedRememberMeServices`, a `PersistentTokenBasedRememberMeServices` or a user-specified bean implementing `RememberMeServices` depending on the attribute settings.
 
 
 [[nsa-remember-me-parents]]
-===== Parent Elements of <remember-me>
+==== Parent Elements of <remember-me>
 
 
 * <<nsa-http,http>>
@@ -1677,7 +1677,7 @@ This in turn will be configured with either a `TokenBasedRememberMeServices`, a
 
 
 [[nsa-remember-me-attributes]]
-===== <remember-me> Attributes
+==== <remember-me> Attributes
 
 
 [[nsa-remember-me-authentication-success-handler-ref]]
@@ -1757,17 +1757,17 @@ If there are multiple instances, you can specify a bean `id` explicitly using th
 
 
 [[nsa-request-cache]]
-==== <request-cache> Element
+=== <request-cache> Element
 Sets the `RequestCache` instance which will be used by the `ExceptionTranslationFilter` to store request information before invoking an `AuthenticationEntryPoint`.
 
 
 [[nsa-request-cache-parents]]
-===== Parent Elements of <request-cache>
+==== Parent Elements of <request-cache>
 
 * <<nsa-http,http>>
 
 [[nsa-request-cache-attributes]]
-===== <request-cache> Attributes
+==== <request-cache> Attributes
 
 
 [[nsa-request-cache-ref]]
@@ -1776,12 +1776,12 @@ Defines a reference to a Spring bean that is a `RequestCache`.
 
 
 [[nsa-session-management]]
-==== <session-management>
+=== <session-management>
 Session-management related functionality is implemented by the addition of a `SessionManagementFilter` to the filter stack.
 
 
 [[nsa-session-management-parents]]
-===== Parent Elements of <session-management>
+==== Parent Elements of <session-management>
 
 
 * <<nsa-http,http>>
@@ -1789,7 +1789,7 @@ Session-management related functionality is implemented by the addition of a `Se
 
 
 [[nsa-session-management-attributes]]
-===== <session-management> Attributes
+==== <session-management> Attributes
 
 
 [[nsa-session-management-invalid-session-url]]
@@ -1831,7 +1831,7 @@ See the Javadoc for this class for more details.
 
 
 [[nsa-session-management-children]]
-===== Child Elements of <session-management>
+==== Child Elements of <session-management>
 
 
 * <<nsa-concurrency-control,concurrency-control>>
@@ -1839,7 +1839,7 @@ See the Javadoc for this class for more details.
 
 
 [[nsa-concurrency-control]]
-==== <concurrency-control>
+=== <concurrency-control>
 Adds support for concurrent session control, allowing limits to be placed on the number of active sessions a user can have.
 A `ConcurrentSessionFilter` will be created, and a `ConcurrentSessionControlAuthenticationStrategy` will be used with the `SessionManagementFilter`.
 If a `form-login` element has been declared, the strategy object will also be injected into the created authentication filter.
@@ -1847,7 +1847,7 @@ An instance of `SessionRegistry` (a `SessionRegistryImpl` instance unless the us
 
 
 [[nsa-concurrency-control-parents]]
-===== Parent Elements of <concurrency-control>
+==== Parent Elements of <concurrency-control>
 
 
 * <<nsa-session-management,session-management>>
@@ -1855,7 +1855,7 @@ An instance of `SessionRegistry` (a `SessionRegistryImpl` instance unless the us
 
 
 [[nsa-concurrency-control-attributes]]
-===== <concurrency-control> Attributes
+==== <concurrency-control> Attributes
 
 
 [[nsa-concurrency-control-error-if-maximum-exceeded]]
@@ -1893,7 +1893,7 @@ The other concurrent session control beans will be wired up to use it.
 
 
 [[nsa-x509]]
-==== <x509>
+=== <x509>
 Adds support for X.509 authentication.
 An `X509AuthenticationFilter` will be added to the stack and an `Http403ForbiddenEntryPoint` bean will be created.
 The latter will only be used if no other authentication mechanisms are in use (its only functionality is to return an HTTP 403 error code).
@@ -1901,7 +1901,7 @@ A `PreAuthenticatedAuthenticationProvider` will also be created which delegates
 
 
 [[nsa-x509-parents]]
-===== Parent Elements of <x509>
+==== Parent Elements of <x509>
 
 
 * <<nsa-http,http>>
@@ -1909,7 +1909,7 @@ A `PreAuthenticatedAuthenticationProvider` will also be created which delegates
 
 
 [[nsa-x509-attributes]]
-===== <x509> Attributes
+==== <x509> Attributes
 
 
 [[nsa-x509-authentication-details-source-ref]]
@@ -1929,12 +1929,12 @@ If not set, an attempt will be made to locate a suitable instance automatically
 
 
 [[nsa-filter-chain-map]]
-==== <filter-chain-map>
+=== <filter-chain-map>
 Used to explicitly configure a FilterChainProxy instance with a FilterChainMap
 
 
 [[nsa-filter-chain-map-attributes]]
-===== <filter-chain-map> Attributes
+==== <filter-chain-map> Attributes
 
 
 [[nsa-filter-chain-map-request-matcher]]
@@ -1944,7 +1944,7 @@ Currently the options are 'ant' (for ant path patterns), 'regex' for regular exp
 
 
 [[nsa-filter-chain-map-children]]
-===== Child Elements of <filter-chain-map>
+==== Child Elements of <filter-chain-map>
 
 
 * <<nsa-filter-chain,filter-chain>>
@@ -1952,13 +1952,13 @@ Currently the options are 'ant' (for ant path patterns), 'regex' for regular exp
 
 
 [[nsa-filter-chain]]
-==== <filter-chain>
+=== <filter-chain>
 Used within to define a specific URL pattern and the list of filters which apply to the URLs matching that pattern.
 When multiple filter-chain elements are assembled in a list in order to configure a FilterChainProxy, the most specific patterns must be placed at the top of the list, with most general ones at the bottom.
 
 
 [[nsa-filter-chain-parents]]
-===== Parent Elements of <filter-chain>
+==== Parent Elements of <filter-chain>
 
 
 * <<nsa-filter-chain-map,filter-chain-map>>
@@ -1966,7 +1966,7 @@ When multiple filter-chain elements are assembled in a list in order to configur
 
 
 [[nsa-filter-chain-attributes]]
-===== <filter-chain> Attributes
+==== <filter-chain> Attributes
 
 
 [[nsa-filter-chain-filters]]
@@ -1986,7 +1986,7 @@ A reference to a `RequestMatcher` that will be used to determine if any `Filter`
 
 
 [[nsa-filter-security-metadata-source]]
-==== <filter-security-metadata-source>
+=== <filter-security-metadata-source>
 Used to explicitly configure a FilterSecurityMetadataSource bean for use with a FilterSecurityInterceptor.
 Usually only needed if you are configuring a FilterChainProxy explicitly, rather than using the<http> element.
 The intercept-url elements used should only contain pattern, method and access attributes.
@@ -1994,7 +1994,7 @@ Any others will result in a configuration error.
 
 
 [[nsa-filter-security-metadata-source-attributes]]
-===== <filter-security-metadata-source> Attributes
+==== <filter-security-metadata-source> Attributes
 
 
 [[nsa-filter-security-metadata-source-id]]
@@ -2017,19 +2017,19 @@ If the expression evaluates to 'true', access will be granted.
 
 
 [[nsa-filter-security-metadata-source-children]]
-===== Child Elements of <filter-security-metadata-source>
+==== Child Elements of <filter-security-metadata-source>
 
 
 * <<nsa-intercept-url,intercept-url>>
 
 [[nsa-websocket-security]]
-=== WebSocket Security
+== WebSocket Security
 
 Spring Security 4.0+ provides support for authorizing messages.
 One concrete example of where this is useful is to provide authorization in WebSocket based applications.
 
 [[nsa-websocket-message-broker]]
-==== <websocket-message-broker>
+=== <websocket-message-broker>
 
 The websocket-message-broker element has two different modes.
 If the <<nsa-websocket-message-broker-id,websocket-message-broker@id>> is not specified, then it will do the following things:
@@ -2051,7 +2051,7 @@ This is more cumbersome, but provides greater control over the configuration.
 
 
 [[nsa-websocket-message-broker-attributes]]
-===== <websocket-message-broker> Attributes
+==== <websocket-message-broker> Attributes
 
 [[nsa-websocket-message-broker-id]]
 * **id** A bean identifier, used for referring to the ChannelSecurityInterceptor bean elsewhere in the context.
@@ -2063,27 +2063,27 @@ If not specified, Spring Security will automatically integrate with the messagin
 Changing the default is useful if it is necessary to allow other origins to make SockJS connections.
 
 [[nsa-websocket-message-broker-children]]
-===== Child Elements of <websocket-message-broker>
+==== Child Elements of <websocket-message-broker>
 
 
 * <<nsa-expression-handler,expression-handler>>
 * <<nsa-intercept-message,intercept-message>>
 
 [[nsa-intercept-message]]
-==== <intercept-message>
+=== <intercept-message>
 
 Defines an authorization rule for a message.
 
 
 [[nsa-intercept-message-parents]]
-===== Parent Elements of <intercept-message>
+==== Parent Elements of <intercept-message>
 
 
 * <<nsa-websocket-message-broker,websocket-message-broker>>
 
 
 [[nsa-intercept-message-attributes]]
-===== <intercept-message> Attributes
+==== <intercept-message> Attributes
 
 [[nsa-intercept-message-pattern]]
 * **pattern** An ant based pattern that matches on the Message destination.
@@ -2098,7 +2098,7 @@ Valid values are defined in SimpMessageType (i.e. CONNECT, CONNECT_ACK, HEARTBEA
 For example, "denyAll" will deny access to all of the matching Messages; "permitAll" will grant access to all of the matching Messages; "hasRole('ADMIN') requires the current user to have the role 'ROLE_ADMIN' for the matching Messages.
 
 [[nsa-authentication]]
-=== Authentication Services
+== Authentication Services
 Before Spring Security 3.0, an `AuthenticationManager` was automatically registered internally.
 Now you must register one explicitly using the `<authentication-manager>` element.
 This creates an instance of Spring Security's `ProviderManager` class, which needs to be configured with a list of one or more `AuthenticationProvider` instances.
@@ -2106,14 +2106,14 @@ These can either be created using syntax elements provided by the namespace, or
 
 
 [[nsa-authentication-manager]]
-==== <authentication-manager>
+=== <authentication-manager>
 Every Spring Security application which uses the namespace must have include this element somewhere.
 It is responsible for registering the `AuthenticationManager` which provides authentication services to the application.
 All elements which create `AuthenticationProvider` instances should be children of this element.
 
 
 [[nsa-authentication-manager-attributes]]
-===== <authentication-manager> Attributes
+==== <authentication-manager> Attributes
 
 
 [[nsa-authentication-manager-alias]]
@@ -2124,7 +2124,7 @@ This attribute allows you to define an alias name for the internal instance for
 [[nsa-authentication-manager-erase-credentials]]
 * **erase-credentials**
 If set to true, the AuthenticationManager will attempt to clear any credentials data in the returned Authentication object, once the user has been authenticated.
-Literally it maps to the `eraseCredentialsAfterAuthentication` property of the <<servlet-authentication-providermanager,`ProviderManager`>>.
+Literally it maps to the `eraseCredentialsAfterAuthentication` property of the xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
 
 
 [[nsa-authentication-manager-id]]
@@ -2134,7 +2134,7 @@ It is the same as the alias element, but provides a more consistent experience w
 
 
 [[nsa-authentication-manager-children]]
-===== Child Elements of <authentication-manager>
+==== Child Elements of <authentication-manager>
 
 
 * <<nsa-authentication-provider,authentication-provider>>
@@ -2143,7 +2143,7 @@ It is the same as the alias element, but provides a more consistent experience w
 
 
 [[nsa-authentication-provider]]
-==== <authentication-provider>
+=== <authentication-provider>
 Unless used with a `ref` attribute, this element is shorthand for configuring a `DaoAuthenticationProvider`.
 `DaoAuthenticationProvider` loads user information from a `UserDetailsService` and compares the username/password combination with the values supplied at login.
 The `UserDetailsService` instance can be defined either by using an available namespace element (`jdbc-user-service` or by using the `user-service-ref` attribute to point to a bean defined elsewhere in the application context).
@@ -2151,7 +2151,7 @@ The `UserDetailsService` instance can be defined either by using an available na
 
 
 [[nsa-authentication-provider-parents]]
-===== Parent Elements of <authentication-provider>
+==== Parent Elements of <authentication-provider>
 
 
 * <<nsa-authentication-manager,authentication-manager>>
@@ -2159,7 +2159,7 @@ The `UserDetailsService` instance can be defined either by using an available na
 
 
 [[nsa-authentication-provider-attributes]]
-===== <authentication-provider> Attributes
+==== <authentication-provider> Attributes
 
 
 [[nsa-authentication-provider-ref]]
@@ -2187,7 +2187,7 @@ A reference to a bean that implements UserDetailsService that may be created usi
 
 
 [[nsa-authentication-provider-children]]
-===== Child Elements of <authentication-provider>
+==== Child Elements of <authentication-provider>
 
 
 * <<nsa-jdbc-user-service,jdbc-user-service>>
@@ -2198,12 +2198,12 @@ A reference to a bean that implements UserDetailsService that may be created usi
 
 
 [[nsa-jdbc-user-service]]
-==== <jdbc-user-service>
+=== <jdbc-user-service>
 Causes creation of a JDBC-based UserDetailsService.
 
 
 [[nsa-jdbc-user-service-attributes]]
-===== <jdbc-user-service> Attributes
+==== <jdbc-user-service> Attributes
 
 
 [[nsa-jdbc-user-service-authorities-by-username-query]]
@@ -2277,13 +2277,13 @@ select username, password, enabled from users where username = ?
 
 
 [[nsa-password-encoder]]
-==== <password-encoder>
-Authentication providers can optionally be configured to use a password encoder as described in the <<authentication-password-storage>>.
+=== <password-encoder>
+Authentication providers can optionally be configured to use a password encoder as described in the xref:features/authentication/password-storage.adoc#authentication-password-storage[Password Storage].
 This will result in the bean being injected with the appropriate `PasswordEncoder` instance.
 
 
 [[nsa-password-encoder-parents]]
-===== Parent Elements of <password-encoder>
+==== Parent Elements of <password-encoder>
 
 
 * <<nsa-authentication-provider,authentication-provider>>
@@ -2292,7 +2292,7 @@ This will result in the bean being injected with the appropriate `PasswordEncode
 
 
 [[nsa-password-encoder-attributes]]
-===== <password-encoder> Attributes
+==== <password-encoder> Attributes
 
 
 [[nsa-password-encoder-hash]]
@@ -2307,13 +2307,13 @@ Defines a reference to a Spring bean that implements `PasswordEncoder`.
 
 
 [[nsa-user-service]]
-==== <user-service>
+=== <user-service>
 Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements.
 Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should not be used if case-sensitivity is required.
 
 
 [[nsa-user-service-attributes]]
-===== <user-service> Attributes
+==== <user-service> Attributes
 
 
 [[nsa-user-service-id]]
@@ -2336,7 +2336,7 @@ username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]
 
 
 [[nsa-user-service-children]]
-===== Child Elements of <user-service>
+==== Child Elements of <user-service>
 
 
 * <<nsa-user,user>>
@@ -2344,12 +2344,12 @@ username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]
 
 
 [[nsa-user]]
-==== <user>
+=== <user>
 Represents a user in the application.
 
 
 [[nsa-user-parents]]
-===== Parent Elements of <user>
+==== Parent Elements of <user>
 
 
 * <<nsa-user-service,user-service>>
@@ -2357,7 +2357,7 @@ Represents a user in the application.
 
 
 [[nsa-user-attributes]]
-===== <user> Attributes
+==== <user> Attributes
 
 
 [[nsa-user-authorities]]
@@ -2392,15 +2392,15 @@ Cannot be empty.
 
 
 
-=== Method Security
+== Method Security
 
 [[nsa-method-security]]
-==== <method-security>
+=== <method-security>
 This element is the primary means of adding support for securing methods on Spring Security beans.
 Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts.
 
 [[nsa-method-security-attributes]]
-===== <method-security> attributes
+==== <method-security> attributes
 
 [[nsa-method-security-pre-post-enabled]]
 * **pre-post-enabled**
@@ -2423,18 +2423,18 @@ If true, class based proxying will be used instead of interface based proxying.
 Defaults to "false".
 
 [[nsa-method-security-children]]
-===== Child Elements of <method-security>
+==== Child Elements of <method-security>
 
 * <<nsa-expression-handler,expression-handler>>
 
 [[nsa-global-method-security]]
-==== <global-method-security>
+=== <global-method-security>
 This element is the primary means of adding support for securing methods on Spring Security beans.
 Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax.
 
 
 [[nsa-global-method-security-attributes]]
-===== <global-method-security> Attributes
+==== <global-method-security> Attributes
 
 
 [[nsa-global-method-security-access-decision-manager-ref]]
@@ -2498,7 +2498,7 @@ Defaults to "disabled".
 
 
 [[nsa-global-method-security-children]]
-===== Child Elements of <global-method-security>
+==== Child Elements of <global-method-security>
 
 
 * <<nsa-after-invocation-provider,after-invocation-provider>>
@@ -2509,13 +2509,13 @@ Defaults to "disabled".
 
 
 [[nsa-after-invocation-provider]]
-==== <after-invocation-provider>
+=== <after-invocation-provider>
 This element can be used to decorate an `AfterInvocationProvider` for use by the security interceptor maintained by the `<global-method-security>` namespace.
 You can define zero or more of these within the `global-method-security` element, each with a `ref` attribute pointing to an `AfterInvocationProvider` bean instance within your application context.
 
 
 [[nsa-after-invocation-provider-parents]]
-===== Parent Elements of <after-invocation-provider>
+==== Parent Elements of <after-invocation-provider>
 
 
 * <<nsa-global-method-security,global-method-security>>
@@ -2523,7 +2523,7 @@ You can define zero or more of these within the `global-method-security` element
 
 
 [[nsa-after-invocation-provider-attributes]]
-===== <after-invocation-provider> Attributes
+==== <after-invocation-provider> Attributes
 
 
 [[nsa-after-invocation-provider-ref]]
@@ -2532,13 +2532,13 @@ Defines a reference to a Spring bean that implements `AfterInvocationProvider`.
 
 
 [[nsa-pre-post-annotation-handling]]
-==== <pre-post-annotation-handling>
+=== <pre-post-annotation-handling>
 Allows the default expression-based mechanism for handling Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) to be replaced entirely.
 Only applies if these annotations are enabled.
 
 
 [[nsa-pre-post-annotation-handling-parents]]
-===== Parent Elements of <pre-post-annotation-handling>
+==== Parent Elements of <pre-post-annotation-handling>
 
 
 * <<nsa-global-method-security,global-method-security>>
@@ -2546,7 +2546,7 @@ Only applies if these annotations are enabled.
 
 
 [[nsa-pre-post-annotation-handling-children]]
-===== Child Elements of <pre-post-annotation-handling>
+==== Child Elements of <pre-post-annotation-handling>
 
 
 * <<nsa-invocation-attribute-factory,invocation-attribute-factory>>
@@ -2556,12 +2556,12 @@ Only applies if these annotations are enabled.
 
 
 [[nsa-invocation-attribute-factory]]
-==== <invocation-attribute-factory>
+=== <invocation-attribute-factory>
 Defines the PrePostInvocationAttributeFactory instance which is used to generate pre and post invocation metadata from the annotated methods.
 
 
 [[nsa-invocation-attribute-factory-parents]]
-===== Parent Elements of <invocation-attribute-factory>
+==== Parent Elements of <invocation-attribute-factory>
 
 
 * <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
@@ -2569,7 +2569,7 @@ Defines the PrePostInvocationAttributeFactory instance which is used to generate
 
 
 [[nsa-invocation-attribute-factory-attributes]]
-===== <invocation-attribute-factory> Attributes
+==== <invocation-attribute-factory> Attributes
 
 
 [[nsa-invocation-attribute-factory-ref]]
@@ -2578,12 +2578,12 @@ Defines a reference to a Spring bean Id.
 
 
 [[nsa-post-invocation-advice]]
-==== <post-invocation-advice>
+=== <post-invocation-advice>
 Customizes the `PostInvocationAdviceProvider` with the ref as the `PostInvocationAuthorizationAdvice` for the <pre-post-annotation-handling> element.
 
 
 [[nsa-post-invocation-advice-parents]]
-===== Parent Elements of <post-invocation-advice>
+==== Parent Elements of <post-invocation-advice>
 
 
 * <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
@@ -2591,7 +2591,7 @@ Customizes the `PostInvocationAdviceProvider` with the ref as the `PostInvocatio
 
 
 [[nsa-post-invocation-advice-attributes]]
-===== <post-invocation-advice> Attributes
+==== <post-invocation-advice> Attributes
 
 
 [[nsa-post-invocation-advice-ref]]
@@ -2600,12 +2600,12 @@ Defines a reference to a Spring bean Id.
 
 
 [[nsa-pre-invocation-advice]]
-==== <pre-invocation-advice>
+=== <pre-invocation-advice>
 Customizes the `PreInvocationAuthorizationAdviceVoter` with the ref as the `PreInvocationAuthorizationAdviceVoter` for the <pre-post-annotation-handling> element.
 
 
 [[nsa-pre-invocation-advice-parents]]
-===== Parent Elements of <pre-invocation-advice>
+==== Parent Elements of <pre-invocation-advice>
 
 
 * <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
@@ -2613,7 +2613,7 @@ Customizes the `PreInvocationAuthorizationAdviceVoter` with the ref as the `PreI
 
 
 [[nsa-pre-invocation-advice-attributes]]
-===== <pre-invocation-advice> Attributes
+==== <pre-invocation-advice> Attributes
 
 
 [[nsa-pre-invocation-advice-ref]]
@@ -2622,14 +2622,14 @@ Defines a reference to a Spring bean Id.
 
 
 [[nsa-protect-pointcut]]
-==== Securing Methods using
+=== Securing Methods using
 `<protect-pointcut>`
 Rather than defining security attributes on an individual method or class basis using the `@Secured` annotation, you can define cross-cutting security constraints across whole sets of methods and interfaces in your service layer using the `<protect-pointcut>` element.
-You can find an example in the <<ns-protect-pointcut,namespace introduction>>.
+You can find an example in the xref:servlet/authorization/method-security.adoc#ns-protect-pointcut[namespace introduction].
 
 
 [[nsa-protect-pointcut-parents]]
-===== Parent Elements of <protect-pointcut>
+==== Parent Elements of <protect-pointcut>
 
 
 * <<nsa-global-method-security,global-method-security>>
@@ -2637,7 +2637,7 @@ You can find an example in the <<ns-protect-pointcut,namespace introduction>>.
 
 
 [[nsa-protect-pointcut-attributes]]
-===== <protect-pointcut> Attributes
+==== <protect-pointcut> Attributes
 
 
 [[nsa-protect-pointcut-access]]
@@ -2653,12 +2653,12 @@ For example, `execution(int com.foo.TargetObject.countLength(String))`.
 
 
 [[nsa-intercept-methods]]
-==== <intercept-methods>
+=== <intercept-methods>
 Can be used inside a bean definition to add a security interceptor to the bean and set up access configuration attributes for the bean's methods
 
 
 [[nsa-intercept-methods-attributes]]
-===== <intercept-methods> Attributes
+==== <intercept-methods> Attributes
 
 
 [[nsa-intercept-methods-access-decision-manager-ref]]
@@ -2667,7 +2667,7 @@ Optional AccessDecisionManager bean ID to be used by the created method security
 
 
 [[nsa-intercept-methods-children]]
-===== Child Elements of <intercept-methods>
+==== Child Elements of <intercept-methods>
 
 
 * <<nsa-protect,protect>>
@@ -2675,12 +2675,12 @@ Optional AccessDecisionManager bean ID to be used by the created method security
 
 
 [[nsa-method-security-metadata-source]]
-==== <method-security-metadata-source>
+=== <method-security-metadata-source>
 Creates a MethodSecurityMetadataSource instance
 
 
 [[nsa-method-security-metadata-source-attributes]]
-===== <method-security-metadata-source> Attributes
+==== <method-security-metadata-source> Attributes
 
 
 [[nsa-method-security-metadata-source-id]]
@@ -2697,7 +2697,7 @@ If the expression evaluates to 'true', access will be granted.
 
 
 [[nsa-method-security-metadata-source-children]]
-===== Child Elements of <method-security-metadata-source>
+==== Child Elements of <method-security-metadata-source>
 
 
 * <<nsa-protect,protect>>
@@ -2705,13 +2705,13 @@ If the expression evaluates to 'true', access will be granted.
 
 
 [[nsa-protect]]
-==== <protect>
+=== <protect>
 Defines a protected method and the access control configuration attributes that apply to it.
 We strongly advise you NOT to mix "protect" declarations with any services provided "global-method-security".
 
 
 [[nsa-protect-parents]]
-===== Parent Elements of <protect>
+==== Parent Elements of <protect>
 
 
 * <<nsa-intercept-methods,intercept-methods>>
@@ -2720,7 +2720,7 @@ We strongly advise you NOT to mix "protect" declarations with any services provi
 
 
 [[nsa-protect-attributes]]
-===== <protect> Attributes
+==== <protect> Attributes
 
 
 [[nsa-protect-access]]
@@ -2735,18 +2735,18 @@ A method name
 
 
 [[nsa-ldap]]
-=== LDAP Namespace Options
-LDAP is covered in some details in <<servlet-authentication-ldap,its own chapter>>.
+== LDAP Namespace Options
+LDAP is covered in some details in xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[its own chapter].
 We will expand on that here with some explanation of how the namespace options map to Spring beans.
 The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful.
 
 
 [[nsa-ldap-server]]
-==== Defining the LDAP Server using the
+=== Defining the LDAP Server using the
 `<ldap-server>` Element
 This element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it.
 It can also be used to create an embedded server for testing.
-Details of the syntax for both options are covered in the <<servlet-authentication-ldap,LDAP chapter>>.
+Details of the syntax for both options are covered in the xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[LDAP chapter].
 The actual `ContextSource` implementation is `DefaultSpringSecurityContextSource` which extends Spring LDAP's `LdapContextSource` class.
 The `manager-dn` and `manager-password` attributes map to the latter's `userDn` and `password` properties respectively.
 
@@ -2756,7 +2756,7 @@ This is actually the bean `id` of the `ContextSource` instance, if you want to u
 
 
 [[nsa-ldap-server-attributes]]
-===== <ldap-server> Attributes
+==== <ldap-server> Attributes
 
 [[nsa-ldap-server-mode]]
 * **mode**
@@ -2805,14 +2805,14 @@ Specifies the ldap server URL when not using the embedded LDAP server.
 
 
 [[nsa-ldap-authentication-provider]]
-==== <ldap-authentication-provider>
+=== <ldap-authentication-provider>
 This element is shorthand for the creation of an `LdapAuthenticationProvider` instance.
 By default this will be configured with a `BindAuthenticator` instance and a `DefaultAuthoritiesPopulator`.
 As with all namespace authentication providers, it must be included as a child of the `authentication-provider` element.
 
 
 [[nsa-ldap-authentication-provider-parents]]
-===== Parent Elements of <ldap-authentication-provider>
+==== Parent Elements of <ldap-authentication-provider>
 
 
 * <<nsa-authentication-manager,authentication-manager>>
@@ -2820,7 +2820,7 @@ As with all namespace authentication providers, it must be included as a child o
 
 
 [[nsa-ldap-authentication-provider-attributes]]
-===== <ldap-authentication-provider> Attributes
+==== <ldap-authentication-provider> Attributes
 
 
 [[nsa-ldap-authentication-provider-group-role-attribute]]
@@ -2905,7 +2905,7 @@ If these attributes aren't set and no `user-dn-pattern` has been supplied as an
 
 
 [[nsa-ldap-authentication-provider-children]]
-===== Child Elements of <ldap-authentication-provider>
+==== Child Elements of <ldap-authentication-provider>
 
 
 * <<nsa-password-compare,password-compare>>
@@ -2913,12 +2913,12 @@ If these attributes aren't set and no `user-dn-pattern` has been supplied as an
 
 
 [[nsa-password-compare]]
-==== <password-compare>
+=== <password-compare>
 This is used as child element to `<ldap-provider>` and switches the authentication strategy from `BindAuthenticator` to `PasswordComparisonAuthenticator`.
 
 
 [[nsa-password-compare-parents]]
-===== Parent Elements of <password-compare>
+==== Parent Elements of <password-compare>
 
 
 * <<nsa-ldap-authentication-provider,ldap-authentication-provider>>
@@ -2926,7 +2926,7 @@ This is used as child element to `<ldap-provider>` and switches the authenticati
 
 
 [[nsa-password-compare-attributes]]
-===== <password-compare> Attributes
+==== <password-compare> Attributes
 
 
 [[nsa-password-compare-hash]]
@@ -2942,7 +2942,7 @@ Defaults to "userPassword".
 
 
 [[nsa-password-compare-children]]
-===== Child Elements of <password-compare>
+==== Child Elements of <password-compare>
 
 
 * <<nsa-password-encoder,password-encoder>>
@@ -2950,14 +2950,14 @@ Defaults to "userPassword".
 
 
 [[nsa-ldap-user-service]]
-==== <ldap-user-service>
+=== <ldap-user-service>
 This element configures an LDAP `UserDetailsService`.
 The class used is `LdapUserDetailsService` which is a combination of a `FilterBasedLdapUserSearch` and a `DefaultLdapAuthoritiesPopulator`.
 The attributes it supports have the same usage as in `<ldap-provider>`.
 
 
 [[nsa-ldap-user-service-attributes]]
-===== <ldap-user-service> Attributes
+==== <ldap-user-service> Attributes
 
 
 [[nsa-ldap-user-service-cache-ref]]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/proxy-server.adoc b/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/appendix/proxy-server.adoc
rename to docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc
index 18d650bf45..ac3f182a16 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/proxy-server.adoc
+++ b/docs/modules/ROOT/pages/servlet/appendix/proxy-server.adoc
@@ -1,5 +1,5 @@
 [[appendix-proxy-server]]
-== Proxy Server Configuration
+= Proxy Server Configuration
 
 When using a proxy server it is important to ensure that you have configured your application properly.
 For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080
diff --git a/docs/modules/ROOT/pages/servlet/architecture.adoc b/docs/modules/ROOT/pages/servlet/architecture.adoc
new file mode 100644
index 0000000000..40b62a1a3c
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/architecture.adoc
@@ -0,0 +1,248 @@
+[[servlet-architecture]]
+= Architecture
+:figures: servlet/architecture
+
+This section discusses Spring Security's high level architecture within Servlet based applications.
+We build on this high level understanding within xref:servlet/authentication/index.adoc#servlet-authentication[Authentication], xref:servlet/authorization/index.adoc#servlet-authorization[Authorization], xref:servlet/exploits/index.adoc#servlet-exploits[Protection Against Exploits] sections of the reference.
+// FIXME: Add links to other sections of architecture
+
+[[servlet-filters-review]]
+== A Review of ``Filter``s
+
+Spring Security's Servlet support is based on Servlet ``Filter``s, so it is helpful to look at the role of ``Filter``s generally first.
+The picture below shows the typical layering of the handlers for a single HTTP request.
+
+.FilterChain
+[[servlet-filterchain-figure]]
+image::{figures}/filterchain.png[]
+
+The client sends a request to the application, and the container creates a `FilterChain` which contains the ``Filter``s and `Servlet` that should process the `HttpServletRequest` based on the path of the request URI.
+In a Spring MVC application the `Servlet` is an instance of {spring-framework-reference-url}web.html#mvc-servlet[`DispatcherServlet`].
+At most one `Servlet` can handle a single `HttpServletRequest` and `HttpServletResponse`.
+However, more than one `Filter` can be used to:
+
+* Prevent downstream ``Filter``s or the `Servlet` from being invoked.
+In this instance the `Filter` will typically write the `HttpServletResponse`.
+* Modify the `HttpServletRequest` or `HttpServletResponse` used by the downstream ``Filter``s and `Servlet`
+
+The power of the `Filter` comes from the `FilterChain` that is passed into it.
+
+.`FilterChain` Usage Example
+====
+.Java
+[source,java,role="primary"]
+----
+public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
+	// do something before the rest of the application
+    chain.doFilter(request, response); // invoke the rest of the application
+    // do something after the rest of the application
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
+    // do something before the rest of the application
+    chain.doFilter(request, response) // invoke the rest of the application
+    // do something after the rest of the application
+}
+----
+====
+
+Since a `Filter` only impacts downstream ``Filter``s and the `Servlet`, the order each `Filter` is invoked is extremely important.
+
+
+[[servlet-delegatingfilterproxy]]
+== DelegatingFilterProxy
+
+Spring provides a `Filter` implementation named {spring-framework-api-url}org/springframework/web/filter/DelegatingFilterProxy.html[`DelegatingFilterProxy`] that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
+The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
+`DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.
+
+Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filters-review,``Filter``s and the `FilterChain`>>.
+
+.DelegatingFilterProxy
+[[servlet-delegatingfilterproxy-figure]]
+image::{figures}/delegatingfilterproxy.png[]
+
+`DelegatingFilterProxy` looks up __Bean Filter~0~__ from the `ApplicationContext` and then invokes __Bean Filter~0~__.
+The pseudo code of `DelegatingFilterProxy` can be seen below.
+
+.`DelegatingFilterProxy` Pseudo Code
+====
+.Java
+[source,java,role="primary",subs="+quotes,+macros"]
+----
+public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
+	// Lazily get Filter that was registered as a Spring Bean
+	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
+	Filter delegate = getFilterBean(someBeanName);
+	// delegate work to the Spring Bean
+	delegate.doFilter(request, response);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary",subs="+quotes,+macros"]
+----
+fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
+	// Lazily get Filter that was registered as a Spring Bean
+	// For the example in <<servlet-delegatingfilterproxy-figure>> `delegate` is an instance of __Bean Filter~0~__
+	val delegate: Filter = getFilterBean(someBeanName)
+	// delegate work to the Spring Bean
+	delegate.doFilter(request, response)
+}
+----
+====
+
+Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances.
+This is important because the container needs to register the `Filter` instances before the container can startup.
+However, Spring typically uses a `ContextLoaderListener` to load the Spring Beans which will not be done until after the `Filter` instances need to be registered.
+
+[[servlet-filterchainproxy]]
+== FilterChainProxy
+
+Spring Security's Servlet support is contained within `FilterChainProxy`.
+`FilterChainProxy` is a special `Filter` provided by Spring Security that allows delegating to many `Filter` instances through <<servlet-securityfilterchain,`SecurityFilterChain`>>.
+Since `FilterChainProxy` is a Bean, it is typically wrapped in a <<servlet-delegatingfilterproxy>>.
+
+.FilterChainProxy
+[[servlet-filterchainproxy-figure]]
+image::{figures}/filterchainproxy.png[]
+
+[[servlet-securityfilterchain]]
+== SecurityFilterChain
+
+{security-api-url}org/springframework/security/web/SecurityFilterChain.html[`SecurityFilterChain`] is used by <<servlet-filterchainproxy>> to determine which Spring Security ``Filter``s should be invoked for this request.
+
+.SecurityFilterChain
+[[servlet-securityfilterchain-figure]]
+image::{figures}/securityfilterchain.png[]
+
+The <<servlet-security-filters,Security Filters>> in `SecurityFilterChain` are typically Beans, but they are registered with `FilterChainProxy` instead of <<servlet-delegatingfilterproxy>>.
+`FilterChainProxy` provides a number of advantages to registering directly with the Servlet container or <<servlet-delegatingfilterproxy>>.
+First, it provides a starting point for all of Spring Security's Servlet support.
+For that reason, if you are attempting to troubleshoot Spring Security's Servlet support, adding a debug point in `FilterChainProxy` is a great place to start.
+
+Second, since `FilterChainProxy` is central to Spring Security usage it can perform tasks that are not viewed as optional.
+// FIXME: Add a link to SecurityContext
+For example, it clears out the `SecurityContext` to avoid memory leaks.
+It also applies Spring Security's xref:servlet/exploits/firewall.adoc#servlet-httpfirewall[`HttpFirewall`] to protect applications against certain types of attacks.
+
+In addition, it provides more flexibility in determining when a `SecurityFilterChain` should be invoked.
+In a Servlet container, ``Filter``s are invoked based upon the URL alone.
+// FIXME: Link to RequestMatcher
+However, `FilterChainProxy` can determine invocation based upon anything in the `HttpServletRequest` by leveraging the `RequestMatcher` interface.
+
+In fact, `FilterChainProxy` can be used to determine which `SecurityFilterChain` should be used.
+This allows providing a totally separate configuration for different _slices_ of your application.
+
+.Multiple SecurityFilterChain
+[[servlet-multi-securityfilterchain-figure]]
+image::{figures}/multi-securityfilterchain.png[]
+
+In the <<servlet-multi-securityfilterchain-figure>> Figure `FilterChainProxy` decides which `SecurityFilterChain` should be used.
+Only the first `SecurityFilterChain` that matches will be invoked.
+If a URL of `/api/messages/` is requested, it will first match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so only `SecurityFilterChain~0~` will be invoked even though it also matches on ``SecurityFilterChain~n~``.
+If a URL of `/messages/` is requested, it will not match on ``SecurityFilterChain~0~``'s pattern of `+/api/**+`, so `FilterChainProxy` will continue trying each `SecurityFilterChain`.
+Assuming that no other, `SecurityFilterChain` instances match `SecurityFilterChain~n~` will be invoked.
+// FIXME add link to pattern matching
+
+Notice that `SecurityFilterChain~0~` has only three security ``Filter``s instances configured.
+However, `SecurityFilterChain~n~` has four security ``Filter``s configured.
+It is important to note that each `SecurityFilterChain` can be unique and configured in isolation.
+In fact, a `SecurityFilterChain` might have zero security ``Filter``s if the application wants Spring Security to ignore certain requests.
+// FIXME: add link to configuring multiple `SecurityFilterChain` instances
+
+[[servlet-security-filters]]
+== Security Filters
+
+The Security Filters are inserted into the <<servlet-filterchainproxy>> with the <<servlet-securityfilterchain>> API.
+The <<servlet-filters-review,order of ``Filter``>>s matters.
+It is typically not necessary to know the ordering of Spring Security's ``Filter``s.
+However, there are times that it is beneficial to know the ordering
+
+Below is a comprehensive list of Spring Security Filter ordering:
+
+* ChannelProcessingFilter
+* WebAsyncManagerIntegrationFilter
+* SecurityContextPersistenceFilter
+* HeaderWriterFilter
+* CorsFilter
+* CsrfFilter
+* LogoutFilter
+* OAuth2AuthorizationRequestRedirectFilter
+* Saml2WebSsoAuthenticationRequestFilter
+* X509AuthenticationFilter
+* AbstractPreAuthenticatedProcessingFilter
+* CasAuthenticationFilter
+* OAuth2LoginAuthenticationFilter
+* Saml2WebSsoAuthenticationFilter
+* xref:servlet/authentication/passwords/form.adoc#servlet-authentication-usernamepasswordauthenticationfilter[`UsernamePasswordAuthenticationFilter`]
+* OpenIDAuthenticationFilter
+* DefaultLoginPageGeneratingFilter
+* DefaultLogoutPageGeneratingFilter
+* ConcurrentSessionFilter
+* xref:servlet/authentication/passwords/digest.adoc#servlet-authentication-digest[`DigestAuthenticationFilter`]
+* BearerTokenAuthenticationFilter
+* xref:servlet/authentication/passwords/basic.adoc#servlet-authentication-basic[`BasicAuthenticationFilter`]
+* RequestCacheAwareFilter
+* SecurityContextHolderAwareRequestFilter
+* JaasApiIntegrationFilter
+* RememberMeAuthenticationFilter
+* AnonymousAuthenticationFilter
+* OAuth2AuthorizationCodeGrantFilter
+* SessionManagementFilter
+* <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>>
+* xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`]
+* SwitchUserFilter
+
+[[servlet-exceptiontranslationfilter]]
+== Handling Security Exceptions
+
+
+The {security-api-url}org/springframework/security/web/access/ExceptionTranslationFilter.html[`ExceptionTranslationFilter`] allows translation of {security-api-url}org/springframework/security/access/AccessDeniedException.html[`AccessDeniedException`] and {security-api-url}/org/springframework/security/core/AuthenticationException.html[`AuthenticationException`] into HTTP responses.
+
+`ExceptionTranslationFilter` is inserted into the <<servlet-filterchainproxy>> as one of the <<servlet-security-filters>>.
+
+image::{figures}/exceptiontranslationfilter.png[]
+
+
+* image:{icondir}/number_1.png[] First, the `ExceptionTranslationFilter` invokes `FilterChain.doFilter(request, response)` to invoke the rest of the application.
+* image:{icondir}/number_2.png[] If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__.
+** The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder] is cleared out
+** The `HttpServletRequest` is saved in the {security-api-url}org/springframework/security/web/savedrequest/RequestCache.html[`RequestCache`].
+When the user successfully authenticates, the `RequestCache` is used to replay the original request.
+// FIXME: add link to authentication success
+** The `AuthenticationEntryPoint` is used to request credentials from the client.
+For example, it might redirect to a log in page or send a `WWW-Authenticate` header.
+// FIXME: link to AuthenticationEntryPoint
+* image:{icondir}/number_3.png[] Otherwise if it is an `AccessDeniedException`, then __Access Denied__.
+The `AccessDeniedHandler` is invoked to handle access denied.
+// FIXME: link to AccessDeniedHandler
+
+[NOTE]
+====
+If the application does not throw an `AccessDeniedException` or an `AuthenticationException`, then `ExceptionTranslationFilter` does not do anything.
+====
+
+The pseudocode for `ExceptionTranslationFilter` looks something like this:
+
+.ExceptionTranslationFilter pseudocode
+[source,java]
+----
+try {
+	filterChain.doFilter(request, response); // <1>
+} catch (AccessDeniedException | AuthenticationException ex) {
+	if (!authenticated || ex instanceof AuthenticationException) {
+		startAuthentication(); // <2>
+	} else {
+		accessDenied(); // <3>
+	}
+}
+----
+<1> You will recall from <<servlet-filters-review>> that invoking `FilterChain.doFilter(request, response)` is the equivalent of invoking the rest of the application.
+This means that if another part of the application, (i.e. xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] or method security) throws an `AuthenticationException` or `AccessDeniedException` it will be caught and handled here.
+<2> If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__.
+<3> Otherwise, __Access Denied__
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc
index eee0f8e6f4..d30fd584bf 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc
@@ -1,9 +1,9 @@
 [[anonymous]]
-== Anonymous Authentication
+= Anonymous Authentication
 
 
 [[anonymous-overview]]
-=== Overview
+== Overview
 It's generally considered good security practice to adopt a "deny-by-default" where you explicitly specify what is allowed and disallow everything else.
 Defining what is accessible to unauthenticated users is a similar situation, particularly for web applications.
 Many sites require that users must be authenticated for anything other than a few URLs (for example the home and login pages).
@@ -21,7 +21,7 @@ Classes can be authored more robustly if they know the `SecurityContextHolder` a
 
 
 [[anonymous-config]]
-=== Configuration
+== Configuration
 Anonymous authentication support is provided automatically when using the HTTP configuration Spring Security 3.0 and can be customized (or disabled) using the `<anonymous>` element.
 You don't need to configure the beans described here unless you are using traditional bean configuration.
 
@@ -88,7 +88,7 @@ For example:
 
 
 [[anonymous-auth-trust-resolver]]
-=== AuthenticationTrustResolver
+== AuthenticationTrustResolver
 Rounding out the anonymous authentication discussion is the `AuthenticationTrustResolver` interface, with its corresponding `AuthenticationTrustResolverImpl` implementation.
 This interface provides an `isAnonymous(Authentication)` method, which allows interested classes to take into account this special type of authentication status.
 The `ExceptionTranslationFilter` uses this interface in processing ``AccessDeniedException``s.
@@ -96,13 +96,13 @@ If an `AccessDeniedException` is thrown, and the authentication is of an anonymo
 This is a necessary distinction, otherwise principals would always be deemed "authenticated" and never be given an opportunity to login via form, basic, digest or some other normal authentication mechanism.
 
 You will often see the `ROLE_ANONYMOUS` attribute in the above interceptor configuration replaced with `IS_AUTHENTICATED_ANONYMOUSLY`, which is effectively the same thing when defining access controls.
-This is an example of the use of the `AuthenticatedVoter` which we will see in the <<authz-authenticated-voter,authorization chapter>>.
+This is an example of the use of the `AuthenticatedVoter` which we will see in the xref:servlet/authorization/architecture.adoc#authz-authenticated-voter[authorization chapter].
 It uses an `AuthenticationTrustResolver` to process this particular configuration attribute and grant access to anonymous users.
 The `AuthenticatedVoter` approach is more powerful, since it allows you to differentiate between anonymous, remember-me and fully-authenticated users.
 If you don't need this functionality though, then you can stick with `ROLE_ANONYMOUS`, which will be processed by Spring Security's standard `RoleVoter`.
 
 [[anonymous-auth-mvc-controller]]
-=== Getting Anonymous Authentications with Spring MVC
+== Getting Anonymous Authentications with Spring MVC
 
 https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-ann-arguments[Spring MVC resolves parameters of type `Principal`] using its own argument resolver.
 
diff --git a/docs/modules/ROOT/pages/servlet/authentication/architecture.adoc b/docs/modules/ROOT/pages/servlet/authentication/architecture.adoc
new file mode 100644
index 0000000000..ea61488c57
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/architecture.adoc
@@ -0,0 +1,261 @@
+[[servlet-authentication-architecture]]
+= Servlet Authentication Architecture
+:figures: servlet/authentication/architecture
+
+This discussion expands on xref:servlet/architecture.adoc#servlet-architecture[Servlet Security: The Big Picture] to describe the main architectural components of Spring Security's used in Servlet authentication.
+If you need concrete flows that explain how these pieces fit together, look at the xref:servlet/authentication/index.adoc#servlet-authentication-mechanisms[Authentication Mechanism] specific sections.
+
+* <<servlet-authentication-securitycontextholder>> - The `SecurityContextHolder` is where Spring Security stores the details of who is xref:features/authentication/index.adoc#authentication[authenticated].
+* <<servlet-authentication-securitycontext>> - is obtained from the `SecurityContextHolder` and contains the `Authentication` of the currently authenticated user.
+* <<servlet-authentication-authentication>> - Can be the input to `AuthenticationManager` to provide the credentials a user has provided to authenticate or the current user from the `SecurityContext`.
+* <<servlet-authentication-granted-authority>> - An authority that is granted to the principal on the `Authentication` (i.e. roles, scopes, etc.)
+* <<servlet-authentication-authenticationmanager>> -  the API that defines how Spring Security's Filters perform  xref:features/authentication/index.adoc#authentication[authentication].
+* <<servlet-authentication-providermanager>> -  the most common implementation of `AuthenticationManager`.
+* <<servlet-authentication-authenticationprovider>> - used by `ProviderManager` to perform a specific type of authentication.
+* <<servlet-authentication-authenticationentrypoint>> - used for requesting credentials from a client (i.e. redirecting to a log in page, sending a `WWW-Authenticate` response, etc.)
+* <<servlet-authentication-abstractprocessingfilter>> - a base `Filter` used for authentication.
+This also gives a good idea of the high level flow of authentication and how pieces work together.
+
+[[servlet-authentication-securitycontextholder]]
+== SecurityContextHolder
+
+Hi {figures} there
+
+At the heart of Spring Security's authentication model is the `SecurityContextHolder`.
+It contains the <<servlet-authentication-securitycontext>>.
+
+image::{figures}/securitycontextholder.png[]
+
+The `SecurityContextHolder` is where Spring Security stores the details of who is xref:features/authentication/index.adoc#authentication[authenticated].
+Spring Security does not care how the `SecurityContextHolder` is populated.
+If it contains a value, then it is used as the currently authenticated user.
+
+The simplest way to indicate a user is authenticated is to set the `SecurityContextHolder` directly.
+
+.Setting `SecurityContextHolder`
+====
+.Java
+[source,java,role="primary"]
+----
+SecurityContext context = SecurityContextHolder.createEmptyContext(); // <1>
+Authentication authentication =
+    new TestingAuthenticationToken("username", "password", "ROLE_USER"); // <2>
+context.setAuthentication(authentication);
+
+SecurityContextHolder.setContext(context); // <3>
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val context: SecurityContext = SecurityContextHolder.createEmptyContext() // <1>
+val authentication: Authentication = TestingAuthenticationToken("username", "password", "ROLE_USER") // <2>
+context.authentication = authentication
+
+SecurityContextHolder.setContext(context) // <3>
+----
+====
+
+<1> We start by creating an empty `SecurityContext`.
+It is important to create a new `SecurityContext` instance instead of using `SecurityContextHolder.getContext().setAuthentication(authentication)` to avoid race conditions across multiple threads.
+<2> Next we create a new <<servlet-authentication-authentication,`Authentication`>> object.
+Spring Security does not care what type of `Authentication` implementation is set on the `SecurityContext`.
+Here we use `TestingAuthenticationToken` because it is very simple.
+A more common production scenario is `UsernamePasswordAuthenticationToken(userDetails, password, authorities)`.
+<3> Finally, we set the `SecurityContext` on the `SecurityContextHolder`.
+Spring Security will use this information for xref:servlet/authorization/index.adoc#servlet-authorization[authorization].
+
+If you wish to obtain information about the authenticated principal, you can do so by accessing the `SecurityContextHolder`.
+
+.Access Currently Authenticated User
+====
+.Java
+[source,java,role="primary"]
+----
+SecurityContext context = SecurityContextHolder.getContext();
+Authentication authentication = context.getAuthentication();
+String username = authentication.getName();
+Object principal = authentication.getPrincipal();
+Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val context = SecurityContextHolder.getContext()
+val authentication = context.authentication
+val username = authentication.name
+val principal = authentication.principal
+val authorities = authentication.authorities
+----
+====
+
+// FIXME: add links to HttpServletRequest.getRemoteUser() and @CurrentSecurityContext @AuthenticationPrincipal
+
+By default the `SecurityContextHolder` uses a `ThreadLocal` to store these details, which means that the `SecurityContext` is always available to methods in the same thread, even if the `SecurityContext` is not explicitly passed around as an argument to those methods.
+Using a `ThreadLocal` in this way is quite safe if care is taken to clear the thread after the present principal's request is processed.
+Spring Security's xref:servlet/architecture.adoc#servlet-filterchainproxy[FilterChainProxy] ensures that the `SecurityContext` is always cleared.
+
+Some applications aren't entirely suitable for using a `ThreadLocal`, because of the specific way they work with threads.
+For example, a Swing client might want all threads in a Java Virtual Machine to use the same security context.
+`SecurityContextHolder` can be configured with a strategy on startup to specify how you would like the context to be stored.
+For a standalone application you would use the `SecurityContextHolder.MODE_GLOBAL` strategy.
+Other applications might want to have threads spawned by the secure thread also assume the same security identity.
+This is achieved by using `SecurityContextHolder.MODE_INHERITABLETHREADLOCAL`.
+You can change the mode from the default `SecurityContextHolder.MODE_THREADLOCAL` in two ways.
+The first is to set a system property, the second is to call a static method on `SecurityContextHolder`.
+Most applications won't need to change from the default, but if you do, take a look at the Javadoc for `SecurityContextHolder` to learn more.
+
+[[servlet-authentication-securitycontext]]
+== SecurityContext
+
+The {security-api-url}org/springframework/security/core/context/SecurityContext.html[`SecurityContext`] is obtained from the <<servlet-authentication-securitycontextholder>>.
+The `SecurityContext` contains an <<servlet-authentication-authentication>> object.
+
+[[servlet-authentication-authentication]]
+== Authentication
+
+The {security-api-url}org/springframework/security/core/Authentication.html[`Authentication`] serves two main purposes within Spring Security:
+
+* An input to <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to provide the credentials a user has provided to authenticate.
+When used in this scenario, `isAuthenticated()` returns `false`.
+* Represents the currently authenticated user.
+The current `Authentication` can be obtained from the <<servlet-authentication-securitycontext>>.
+
+The `Authentication` contains:
+
+* `principal` - identifies the user.
+When authenticating with a username/password this is often an instance of xref:servlet/authentication/passwords/user-details.adoc#servlet-authentication-userdetails[`UserDetails`].
+* `credentials` - often a password.
+In many cases this will be cleared after the user is authenticated to ensure it is not leaked.
+* `authorities` - the <<servlet-authentication-granted-authority,``GrantedAuthority``s>> are high level permissions the user is granted.
+A few examples are roles or scopes.
+
+[[servlet-authentication-granted-authority]]
+== GrantedAuthority
+{security-api-url}org/springframework/security/core/GrantedAuthority.html[``GrantedAuthority``s] are high level permissions the user is granted. A few examples are roles or scopes.
+
+``GrantedAuthority``s can be obtained from the <<servlet-authentication-authentication,`Authentication.getAuthorities()`>> method.
+This method provides a `Collection` of `GrantedAuthority` objects.
+A `GrantedAuthority` is, not surprisingly, an authority that is granted to the principal.
+Such authorities are usually "roles", such as `ROLE_ADMINISTRATOR` or `ROLE_HR_SUPERVISOR`.
+These roles are later on configured for web authorization, method authorization and domain object authorization.
+Other parts of Spring Security are capable of interpreting these authorities, and expect them to be present.
+When using username/password based authentication ``GrantedAuthority``s are usually loaded by the xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`].
+
+Usually the `GrantedAuthority` objects are application-wide permissions.
+They are not specific to a given domain object.
+Thus, you wouldn't likely have a `GrantedAuthority` to represent a permission to `Employee` object number 54, because if there are thousands of such authorities you would quickly run out of memory (or, at the very least, cause the application to take a long time to authenticate a user).
+Of course, Spring Security is expressly designed to handle this common requirement, but you'd instead use the project's domain object security capabilities for this purpose.
+
+[[servlet-authentication-authenticationmanager]]
+== AuthenticationManager
+
+{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform  xref:features/authentication/index.adoc#authentication[authentication].
+The <<servlet-authentication-authentication,`Authentication`>> that is returned is then set on the <<servlet-authentication-securitycontextholder>> by the controller (i.e. xref:servlet/architecture.adoc#servlet-security-filters[Spring Security's ``Filters``s]) that invoked the `AuthenticationManager`.
+If you are not integrating with __Spring Security's ``Filters``s__ you can set the `SecurityContextHolder` directly and are not required to use an `AuthenticationManager`.
+
+While the implementation of `AuthenticationManager` could be anything, the most common implementation is <<servlet-authentication-providermanager,`ProviderManager`>>.
+// FIXME: add configuration
+
+[[servlet-authentication-providermanager]]
+== ProviderManager
+
+{security-api-url}org/springframework/security/authentication/ProviderManager.html[`ProviderManager`] is the most commonly used implementation of <<servlet-authentication-authenticationmanager,`AuthenticationManager`>>.
+`ProviderManager` delegates to a `List` of <<servlet-authentication-authenticationprovider,``AuthenticationProvider``s>>.
+// FIXME: link to AuthenticationProvider
+Each `AuthenticationProvider` has an opportunity to indicate that authentication should be successful, fail, or indicate it cannot make a decision and allow a downstream `AuthenticationProvider` to decide.
+If none of the configured ``AuthenticationProvider``s can authenticate, then authentication will fail with a `ProviderNotFoundException` which is a special `AuthenticationException` that indicates the `ProviderManager` was not configured to support the type of `Authentication` that was passed into it.
+
+image::{figures}/providermanager.png[]
+
+In practice each `AuthenticationProvider` knows how to perform a specific type of authentication.
+For example, one `AuthenticationProvider` might be able to validate a username/password, while another might be able to authenticate a SAML assertion.
+This allows each `AuthenticationProvider` to do a very specific type of authentication, while supporting multiple types of authentication and only exposing a single `AuthenticationManager` bean.
+
+`ProviderManager` also allows configuring an optional parent `AuthenticationManager` which is consulted in the event that no `AuthenticationProvider` can perform authentication.
+The parent can be any type of `AuthenticationManager`, but it is often an instance of `ProviderManager`.
+
+image::{figures}/providermanager-parent.png[]
+
+In fact, multiple `ProviderManager` instances might share the same parent `AuthenticationManager`.
+This is somewhat common in scenarios where there are multiple xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] instances that have some authentication in common (the shared parent `AuthenticationManager`), but also different authentication mechanisms (the different `ProviderManager` instances).
+
+image::{figures}/providermanagers-parent.png[]
+
+[[servlet-authentication-providermanager-erasing-credentials]]
+By default `ProviderManager` will attempt to clear any sensitive credentials information from the `Authentication` object which is returned by a successful authentication request.
+This prevents information like passwords being retained longer than necessary in the `HttpSession`.
+
+This may cause issues when you are using a cache of user objects, for example, to improve performance in a stateless application.
+If the `Authentication` contains a reference to an object in the cache (such as a `UserDetails` instance) and this has its credentials removed, then it will no longer be possible to authenticate against the cached value.
+You need to take this into account if you are using a cache.
+An obvious solution is to make a copy of the object first, either in the cache implementation or in the `AuthenticationProvider` which creates the returned `Authentication` object.
+Alternatively, you can disable the `eraseCredentialsAfterAuthentication` property on `ProviderManager`.
+See the {security-api-url}org/springframework/security/authentication/ProviderManager.html[Javadoc] for more information.
+
+[[servlet-authentication-authenticationprovider]]
+== AuthenticationProvider
+
+Multiple {security-api-url}org/springframework/security/authentication/AuthenticationProvider.html[``AuthenticationProvider``s] can be injected into <<servlet-authentication-providermanager,`ProviderManager`>>.
+Each `AuthenticationProvider` performs a specific type of authentication.
+For example, xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token.
+
+[[servlet-authentication-authenticationentrypoint]]
+== Request Credentials with `AuthenticationEntryPoint`
+
+{security-api-url}org/springframework/security/web/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`] is used to send an HTTP response that requests credentials from a client.
+
+Sometimes a client will proactively include credentials such as a username/password to request a resource.
+In these cases, Spring Security does not need to provide an HTTP response that requests credentials from the client since they are already included.
+
+In other cases, a client will make an unauthenticated request to a resource that they are not authorized to access.
+In this case, an implementation of `AuthenticationEntryPoint` is used to request credentials from the client.
+The `AuthenticationEntryPoint` implementation might perform a xref:servlet/authentication/passwords/form.adoc#servlet-authentication-form[redirect to a log in page], respond with an xref:servlet/authentication/passwords/basic.adoc#servlet-authentication-basic[WWW-Authenticate] header, etc.
+
+
+
+// FIXME: authenticationsuccesshandler
+// FIXME: authenticationfailurehandler
+
+[[servlet-authentication-abstractprocessingfilter]]
+== AbstractAuthenticationProcessingFilter
+
+{security-api-url}org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.html[`AbstractAuthenticationProcessingFilter`] is used as a base `Filter` for authenticating a user's credentials.
+Before the credentials can be authenticated, Spring Security typically requests the credentials using <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
+
+Next, the `AbstractAuthenticationProcessingFilter` can authenticate any authentication requests that are submitted to it.
+
+image::{figures}/abstractauthenticationprocessingfilter.png[]
+
+image:{icondir}/number_1.png[] When the user submits their credentials, the `AbstractAuthenticationProcessingFilter` creates an <<servlet-authentication-authentication,`Authentication`>> from the `HttpServletRequest` to be authenticated.
+The type of `Authentication` created depends on the subclass of `AbstractAuthenticationProcessingFilter`.
+For example, xref:servlet/authentication/passwords/form.adoc#servlet-authentication-usernamepasswordauthenticationfilter[`UsernamePasswordAuthenticationFilter`] creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`.
+
+image:{icondir}/number_2.png[] Next, the <<servlet-authentication-authentication,`Authentication`>> is passed into the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to be authenticated.
+
+image:{icondir}/number_3.png[] If authentication fails, then __Failure__
+
+* The <<servlet-authentication-securitycontextholder>> is cleared out.
+* `RememberMeServices.loginFail` is invoked.
+If remember me is not configured, this is a no-op.
+// FIXME: link to rememberme
+* `AuthenticationFailureHandler` is invoked.
+// FIXME: link to AuthenticationFailureHandler
+
+image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
+
+* `SessionAuthenticationStrategy` is notified of a new log in.
+// FIXME: Add link to SessionAuthenticationStrategy
+* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
+Later the `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession`.
+// FIXME: link securitycontextpersistencefilter
+* `RememberMeServices.loginSuccess` is invoked.
+If remember me is not configured, this is a no-op.
+// FIXME: link to rememberme
+* `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`.
+* `AuthenticationSuccessHandler` is invoked.
+// FIXME: link to AuthenticationSuccessHandler
+
+
+// daoauthenticationprovider (goes in username/password)
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/cas.adoc b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/cas.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/cas.adoc
index 29c245eb95..5b6dd7617e 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/cas.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc
@@ -1,8 +1,8 @@
 [[servlet-cas]]
-== CAS Authentication
+= CAS Authentication
 
 [[cas-overview]]
-=== Overview
+== Overview
 JA-SIG produces an enterprise-wide single sign on system known as CAS.
 Unlike other initiatives, JA-SIG's Central Authentication Service is open source, widely used, simple to understand, platform independent, and supports proxy capabilities.
 Spring Security fully supports CAS, and provides an easy migration path from single-application deployments of Spring Security through to multiple-application deployments secured by an enterprise-wide CAS server.
@@ -11,7 +11,7 @@ You can learn more about CAS at https://www.apereo.org.
 You will also need to visit this site to download the CAS Server files.
 
 [[cas-how-it-works]]
-=== How CAS Works
+== How CAS Works
 Whilst the CAS web site contains documents that detail the architecture of CAS, we present the general overview again here within the context of Spring Security.
 Spring Security 3.x supports CAS 3.
 At the time of writing, the CAS server was at version 3.4.
@@ -34,7 +34,7 @@ Authenticating a proxy ticket differs because the list of proxies must be valida
 
 
 [[cas-sequence]]
-==== Spring Security and CAS Interaction Sequence
+=== Spring Security and CAS Interaction Sequence
 The basic interaction between a web browser, CAS server and a Spring Security-secured service is as follows:
 
 * The web user is browsing the service's public pages.
@@ -87,16 +87,16 @@ It's good that you're still here!
 Let's now look at how this is configured
 
 [[cas-client]]
-=== Configuration of CAS Client
+== Configuration of CAS Client
 The web application side of CAS is made easy due to Spring Security.
 It is assumed you already know the basics of using Spring Security, so these are not covered again below.
 We'll assume a namespace based configuration is being used and add in the CAS beans as required.
 Each section builds upon the previous section.
-A full CAS sample application can be found in the Spring Security <<samples,Samples>>.
+A full CAS sample application can be found in the Spring Security xref:samples.adoc#samples[Samples].
 
 
 [[cas-st]]
-==== Service Ticket Authentication
+=== Service Ticket Authentication
 This section describes how to setup Spring Security to authenticate Service Tickets.
 Often times this is all a web application requires.
 You will need to add a `ServiceProperties` bean to your application context.
@@ -139,7 +139,7 @@ The following beans should be configured to commence the CAS authentication proc
 ----
 
 For CAS to operate, the `ExceptionTranslationFilter` must have its `authenticationEntryPoint` property set to the `CasAuthenticationEntryPoint` bean.
-This can easily be done using <<nsa-http-entry-point-ref,entry-point-ref>> as is done in the example above.
+This can easily be done using xref:servlet/appendix/namespace.adoc#nsa-http-entry-point-ref[entry-point-ref] as is done in the example above.
 The `CasAuthenticationEntryPoint` must refer to the `ServiceProperties` bean (discussed above), which provides the URL to the enterprise's CAS login server.
 This is where the user's browser will be redirected.
 
@@ -194,7 +194,7 @@ In the following sections we will discuss some (optional) more advanced configur
 
 
 [[cas-singlelogout]]
-==== Single Logout
+=== Single Logout
 The CAS protocol supports Single Logout and can be easily added to your Spring Security configuration.
 Below are updates to the Spring Security configuration that handle Single Logout
 
@@ -271,14 +271,14 @@ The `SingleSignOutHttpSessionListener` ensures that when an `HttpSession` expire
 
 
 [[cas-pt-client]]
-==== Authenticating to a Stateless Service with CAS
+=== Authenticating to a Stateless Service with CAS
 This section describes how to authenticate to a service using CAS.
 In other words, this section discusses how to setup a client that uses a service that authenticates with CAS.
 The next section describes how to setup a stateless service to Authenticate using CAS.
 
 
 [[cas-pt-client-config]]
-===== Configuring CAS to Obtain Proxy Granting Tickets
+==== Configuring CAS to Obtain Proxy Granting Tickets
 In order to authenticate to a stateless service, the application needs to obtain a proxy granting ticket (PGT).
 This section describes how to configure Spring Security to obtain a PGT building upon thencas-st[Service Ticket Authentication] configuration.
 
@@ -335,9 +335,9 @@ An example configuration is shown below.
 ----
 
 [[cas-pt-client-sample]]
-===== Calling a Stateless Service Using a Proxy Ticket
+==== Calling a Stateless Service Using a Proxy Ticket
 Now that Spring Security obtains PGTs, you can use them to create proxy tickets which can be used to authenticate to a stateless service.
-The CAS <<samples,sample application>> contains a working example in the `ProxyTicketSampleServlet`.
+The CAS xref:samples.adoc#samples[sample application] contains a working example in the `ProxyTicketSampleServlet`.
 Example code can be found below:
 
 ====
@@ -379,7 +379,7 @@ protected fun doGet(request: HttpServletRequest, response: HttpServletResponse?)
 ====
 
 [[cas-pt]]
-==== Proxy Ticket Authentication
+=== Proxy Ticket Authentication
 The `CasAuthenticationProvider` distinguishes between stateful and stateless clients.
 A stateful client is considered any that submits to the `filterProcessUrl` of the `CasAuthenticationFilter`.
 A stateless client is any that presents an authentication request to `CasAuthenticationFilter` on a URL other than the `filterProcessUrl`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/events.adoc b/docs/modules/ROOT/pages/servlet/authentication/events.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/events.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/events.adoc
index 6bb9896718..c016d37574 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/events.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/events.adoc
@@ -1,5 +1,5 @@
 [[servlet-events]]
-== Authentication Events
+= Authentication Events
 
 For each authentication that succeeds or fails, a `AuthenticationSuccessEvent` or `AbstractAuthenticationFailureEvent` is fired, respectively.
 
@@ -68,7 +68,7 @@ class AuthenticationEvents {
 
 While similar to `AuthenticationSuccessHandler` and `AuthenticationFailureHandler`, these are nice in that they can be used independently from the servlet API.
 
-=== Adding Exception Mappings
+== Adding Exception Mappings
 
 `DefaultAuthenticationEventPublisher` by default will publish an `AbstractAuthenticationFailureEvent` for the following events:
 
@@ -121,7 +121,7 @@ fun authenticationEventPublisher
 ----
 ====
 
-=== Default Event
+== Default Event
 
 And, you can supply a catch-all event to fire in the case of any `AuthenticationException`:
 
diff --git a/docs/modules/ROOT/pages/servlet/authentication/index.adoc b/docs/modules/ROOT/pages/servlet/authentication/index.adoc
new file mode 100644
index 0000000000..ceb08df6cb
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/index.adoc
@@ -0,0 +1,24 @@
+[[servlet-authentication]]
+= Authentication
+
+Spring Security provides comprehensive support for xref:features/authentication/index.adoc#authentication[Authentication].
+We start by discussing the overall xref:servlet/architecture.adoc#servlet-architecture[Servlet Authentication Architecture].
+As you might expect, this section is more abstract describing the architecture without much discussion on how it applies to concrete flows.
+
+If you prefer, you can refer to <<servlet-authentication-mechanisms,Authentication Mechanisms>> for concrete ways in which users can authenticate.
+These sections focus on specific ways you may want to authenticate and point back at the architecture sections to describe how the specific flows work.
+
+[[servlet-authentication-mechanisms]]
+== Authentication Mechanisms
+
+// FIXME: brief description
+
+* xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd[Username and Password] - how to authenticate with a username/password
+* xref:servlet/oauth2/oauth2-login.adoc#oauth2login[OAuth 2.0 Login] - OAuth 2.0 Log In with OpenID Connect and non-standard OAuth 2.0 Login (i.e. GitHub)
+* xref:servlet/saml2/index.adoc#servlet-saml2[SAML 2.0 Login] - SAML 2.0 Log In
+* xref:servlet/authentication/cas.adoc#servlet-cas[Central Authentication Server (CAS)] - Central Authentication Server (CAS) Support
+* xref:servlet/authentication/rememberme.adoc#servlet-rememberme[Remember Me] - how to remember a user past session expiration
+* xref:servlet/authentication/jaas.adoc#servlet-jaas[JAAS Authentication] - authenticate with JAAS
+* xref:servlet/authentication/openid.adoc#servlet-openid[OpenID] - OpenID Authentication (not to be confused with OpenID Connect)
+* xref:servlet/authentication/preauth.adoc#servlet-preauth[Pre-Authentication Scenarios] - authenticate with an external mechanism such as https://www.siteminder.com/[SiteMinder] or Java EE security but still use Spring Security for authorization and protection against common exploits.
+* xref:servlet/authentication/x509.adoc#servlet-x509[X509 Authentication] - X509 Authentication
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/jaas.adoc b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc
similarity index 94%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/jaas.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/jaas.adoc
index 216435bf43..9e241932be 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/jaas.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc
@@ -1,21 +1,21 @@
 [[servlet-jaas]]
-== Java Authentication and Authorization Service (JAAS) Provider
+= Java Authentication and Authorization Service (JAAS) Provider
 
 
-=== Overview
+== Overview
 Spring Security provides a package able to delegate authentication requests to the Java Authentication and Authorization Service (JAAS).
 This package is discussed in detail below.
 
 
 [[jaas-abstractjaasauthenticationprovider]]
-=== AbstractJaasAuthenticationProvider
+== AbstractJaasAuthenticationProvider
 The `AbstractJaasAuthenticationProvider` is the basis for the provided JAAS `AuthenticationProvider` implementations.
 Subclasses must implement a method that creates the `LoginContext`.
 The `AbstractJaasAuthenticationProvider` has a number of dependencies that can be injected into it that are discussed below.
 
 
 [[jaas-callbackhandler]]
-==== JAAS CallbackHandler
+=== JAAS CallbackHandler
 Most JAAS ``LoginModule``s require a callback of some sort.
 These callbacks are usually used to obtain the username and password from the user.
 
@@ -33,7 +33,7 @@ If the `LoginModule` requests a callback against the ``InternalCallbackHandler``
 
 
 [[jaas-authoritygranter]]
-==== JAAS AuthorityGranter
+=== JAAS AuthorityGranter
 JAAS works with principals.
 Even "roles" are represented as principals in JAAS.
 Spring Security, on the other hand, works with `Authentication` objects.
@@ -50,14 +50,14 @@ However, there is a `TestAuthorityGranter` in the unit tests that demonstrates a
 
 
 [[jaas-defaultjaasauthenticationprovider]]
-=== DefaultJaasAuthenticationProvider
+== DefaultJaasAuthenticationProvider
 The `DefaultJaasAuthenticationProvider` allows a JAAS `Configuration` object to be injected into it as a dependency.
 It then creates a `LoginContext` using the injected JAAS `Configuration`.
 This means that `DefaultJaasAuthenticationProvider` is not bound any particular implementation of `Configuration` as `JaasAuthenticationProvider` is.
 
 
 [[jaas-inmemoryconfiguration]]
-==== InMemoryConfiguration
+=== InMemoryConfiguration
 In order to make it easy to inject a `Configuration` into `DefaultJaasAuthenticationProvider`, a default in-memory implementation named `InMemoryConfiguration` is provided.
 The implementation constructor accepts a `Map` where each key represents a login configuration name and the value represents an `Array` of ``AppConfigurationEntry``s.
 `InMemoryConfiguration` also supports a default `Array` of `AppConfigurationEntry` objects that will be used if no mapping is found within the provided `Map`.
@@ -65,7 +65,7 @@ For details, refer to the class level javadoc of `InMemoryConfiguration`.
 
 
 [[jaas-djap-config]]
-==== DefaultJaasAuthenticationProvider Example Configuration
+=== DefaultJaasAuthenticationProvider Example Configuration
 While the Spring configuration for `InMemoryConfiguration` can be more verbose than the standard JAAS configuration files, using it in conjunction with `DefaultJaasAuthenticationProvider` is more flexible than `JaasAuthenticationProvider` since it not dependant on the default `Configuration` implementation.
 
 An example configuration of `DefaultJaasAuthenticationProvider` using `InMemoryConfiguration` is provided below.
@@ -116,7 +116,7 @@ class="org.springframework.security.authentication.jaas.DefaultJaasAuthenticatio
 
 
 [[jaas-jaasauthenticationprovider]]
-=== JaasAuthenticationProvider
+== JaasAuthenticationProvider
 The `JaasAuthenticationProvider` assumes the default `Configuration` is an instance of https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/login/ConfigFile.html[ ConfigFile].
 This assumption is made in order to attempt to update the `Configuration`.
 The `JaasAuthenticationProvider` then uses the default `Configuration` to create the `LoginContext`.
@@ -157,7 +157,7 @@ class="org.springframework.security.authentication.jaas.JaasAuthenticationProvid
 ----
 
 [[jaas-apiprovision]]
-=== Running as a Subject
+== Running as a Subject
 If configured, the `JaasApiIntegrationFilter` will attempt to run as the `Subject` on the `JaasAuthenticationToken`.
 This means that the `Subject` can be accessed using:
 
@@ -166,5 +166,5 @@ This means that the `Subject` can be accessed using:
 Subject subject = Subject.getSubject(AccessController.getContext());
 ----
 
-This integration can easily be configured using the <<nsa-http-jaas-api-provision,jaas-api-provision>> attribute.
+This integration can easily be configured using the xref:servlet/appendix/namespace.adoc#nsa-http-jaas-api-provision[jaas-api-provision] attribute.
 This feature is useful when integrating with legacy or external API's that rely on the JAAS Subject being populated.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc
similarity index 87%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/logout.adoc
index 7ebb287ac2..db4276e6df 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc
@@ -1,8 +1,8 @@
 [[jc-logout]]
-== Handling Logouts
+= Handling Logouts
 
 [[logout-java-configuration]]
-=== Logout Java/Kotlin Configuration
+== Logout Java/Kotlin Configuration
 
 When using the `{security-api-url}org/springframework/security/config/annotation/web/configuration/WebSecurityConfigurerAdapter.html[WebSecurityConfigurerAdapter]`, logout capabilities are automatically applied.
 The default is that accessing the URL `/logout` will log the user out by:
@@ -74,7 +74,7 @@ This is a shortcut for adding a `CookieClearingLogoutHandler` explicitly.
 [NOTE]
 ====
 Logouts can of course also be configured using the XML Namespace notation.
-Please see the documentation for the <<nsa-logout, logout element>> in the Spring Security XML Namespace section for further details.
+Please see the documentation for the xref:servlet/appendix/namespace.adoc#nsa-logout[ logout element] in the Spring Security XML Namespace section for further details.
 ====
 
 Generally, in order to customize logout functionality, you can add
@@ -86,13 +86,13 @@ For many common scenarios, these handlers are applied under the
 covers when using the fluent API.
 
 [[ns-logout]]
-=== Logout XML Configuration
+== Logout XML Configuration
 The `logout` element adds support for logging out by navigating to a particular URL.
 The default logout URL is `/logout`, but you can set it to something else using the `logout-url` attribute.
 More information on other available attributes may be found in the namespace appendix.
 
 [[jc-logout-handler]]
-=== LogoutHandler
+== LogoutHandler
 
 Generally, `{security-api-url}org/springframework/security/web/authentication/logout/LogoutHandler.html[LogoutHandler]`
 implementations indicate classes that are able to participate in logout handling.
@@ -108,14 +108,14 @@ Various implementations are provided:
 - {security-api-url}org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html[SecurityContextLogoutHandler]
 - {security-api-url}org/springframework/security/web/authentication/logout/HeaderWriterLogoutHandler.html[HeaderWriterLogoutHandler]
 
-Please see <<remember-me-impls>> for details.
+Please see xref:servlet/authentication/rememberme.adoc#remember-me-impls[Remember-Me Interfaces and Implementations] for details.
 
 Instead of providing `LogoutHandler` implementations directly, the fluent API also provides shortcuts that provide the respective `LogoutHandler` implementations under the covers.
 E.g. `deleteCookies()` allows specifying the names of one or more cookies to be removed on logout success.
 This is a shortcut compared to adding a `CookieClearingLogoutHandler`.
 
 [[jc-logout-success-handler]]
-=== LogoutSuccessHandler
+== LogoutSuccessHandler
 
 The `LogoutSuccessHandler` is called after a successful logout by the `LogoutFilter`, to handle e.g.
 redirection or forwarding to the appropriate destination.
@@ -137,12 +137,12 @@ Instead of redirecting to a URL upon the successful logout, this `LogoutSuccessH
 If not configured a status code 200 will be returned by default.
 
 [[jc-logout-references]]
-=== Further Logout-Related References
+== Further Logout-Related References
 
 - <<ns-logout, Logout Handling>>
-- <<test-logout, Testing Logout>>
-- <<servletapi-logout, HttpServletRequest.logout()>>
-- <<remember-me-impls>>
-- <<servlet-considerations-csrf-logout, Logging Out>> in section CSRF Caveats
-- Section <<cas-singlelogout, Single Logout>> (CAS protocol)
-- Documentation for the <<nsa-logout, logout element>> in the Spring Security XML Namespace section
+- xref:servlet/test/mockmvc.adoc#test-logout[ Testing Logout]
+- xref:servlet/integrations/servlet-api.adoc#servletapi-logout[ HttpServletRequest.logout()]
+- xref:servlet/authentication/rememberme.adoc#remember-me-impls[Remember-Me Interfaces and Implementations]
+- xref:servlet/exploits/csrf.adoc#servlet-considerations-csrf-logout[ Logging Out] in section CSRF Caveats
+- Section xref:servlet/authentication/cas.adoc#cas-singlelogout[ Single Logout] (CAS protocol)
+- Documentation for the xref:servlet/appendix/namespace.adoc#nsa-logout[ logout element] in the Spring Security XML Namespace section
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/openid.adoc b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc
similarity index 93%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/openid.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/openid.adoc
index 01362127ff..8451b82d4d 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/openid.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc
@@ -1,5 +1,5 @@
 [[servlet-openid]]
-== OpenID Support
+= OpenID Support
 
 [NOTE]
 The OpenID 1.0 and 2.0 protocols have been deprecated and users are encouraged to migrate to OpenID Connect, which is supported by spring-security-oauth2.
@@ -27,7 +27,7 @@ Note that we have omitted the password attribute from the above user configurati
 A random password will be generated internally, preventing you from accidentally using this user data as an authentication source elsewhere in your configuration.
 
 
-=== Attribute Exchange
+== Attribute Exchange
 Support for OpenID https://openid.net/specs/openid-attribute-exchange-1_0.html[attribute exchange].
 As an example, the following configuration would attempt to retrieve the email and full name from the OpenID provider, for use by the application:
 
@@ -53,7 +53,7 @@ OpenIDAuthenticationToken token =
 List<OpenIDAttribute> attributes = token.getAttributes();
 ----
 
-We can obtain the `OpenIDAuthenticationToken` from the <<servlet-authentication-securitycontextholder>>.
+We can obtain the `OpenIDAuthenticationToken` from the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
 The `OpenIDAttribute` contains the attribute type and the retrieved value (or values in the case of multi-valued attributes).
 You can supply multiple `attribute-exchange` elements, using an `identifier-matcher` attribute on each.
 This contains a regular expression which will be matched against the OpenID identifier supplied by the user.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/basic.adoc
similarity index 62%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/basic.adoc
index 411fefcb13..f83ead53ac 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/basic.adoc
@@ -1,5 +1,6 @@
 [[servlet-authentication-basic]]
 = Basic Authentication
+:figures: servlet/authentication/unpwd
 
 This section provides details on how Spring Security provides support for https://tools.ietf.org/html/rfc7617[Basic HTTP Authentication] for servlet based applications.
 // FIXME: describe authenticationentrypoint, authenticationfailurehandler, authenticationsuccesshandler
@@ -10,14 +11,14 @@ First, we see the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authentica
 .Sending WWW-Authenticate Header
 image::{figures}/basicauthenticationentrypoint.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
 image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
 
-image:{icondir}/number_2.png[] Spring Security's <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
+image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
 
-image:{icondir}/number_3.png[] Since the user is not authenticated, <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__.
-The configured <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>> is an instance of {security-api-url}org/springframework/security/web/authentication/www/BasicAuthenticationEntryPoint.html[`BasicAuthenticationEntryPoint`] which sends a WWW-Authenticate header.
+image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/web/authentication/www/BasicAuthenticationEntryPoint.html[`BasicAuthenticationEntryPoint`] which sends a WWW-Authenticate header.
 The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested.
 
 When a client receives the WWW-Authenticate header it knows it should retry with a username and password.
@@ -27,17 +28,17 @@ Below is the flow for the username and password being processed.
 .Authenticating Username and Password
 image::{figures}/basicauthenticationfilter.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
 
-image:{icondir}/number_1.png[] When the user submits their username and password, the `BasicAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <<servlet-authentication-authentication,`Authentication`>> by extracting the username and password from the `HttpServletRequest`.
+image:{icondir}/number_1.png[] When the user submits their username and password, the `BasicAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] by extracting the username and password from the `HttpServletRequest`.
 
 image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated.
-The details of what `AuthenticationManager` looks like depend on how the <<servlet-authentication-unpwd-storage,user information is stored>>.
+The details of what `AuthenticationManager` looks like depend on how the xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-storage[user information is stored].
 
 image:{icondir}/number_3.png[] If authentication fails, then __Failure__
 
-* The <<servlet-authentication-securitycontextholder>> is cleared out.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder] is cleared out.
 * `RememberMeServices.loginFail` is invoked.
 If remember me is not configured, this is a no-op.
 // FIXME: link to rememberme
@@ -45,7 +46,7 @@ If remember me is not configured, this is a no-op.
 
 image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
 
-* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[Authentication] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
 * `RememberMeServices.loginSuccess` is invoked.
 If remember me is not configured, this is a no-op.
 // FIXME: link to rememberme
diff --git a/docs/modules/ROOT/pages/servlet/authentication/passwords/dao-authentication-provider.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/dao-authentication-provider.adoc
new file mode 100644
index 0000000000..18631cb9c4
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/dao-authentication-provider.adoc
@@ -0,0 +1,22 @@
+[[servlet-authentication-daoauthenticationprovider]]
+= DaoAuthenticationProvider
+:figures: servlet/authentication/unpwd
+
+{security-api-url}org/springframework/security/authentication/dao/DaoAuthenticationProvider.html[`DaoAuthenticationProvider`] is an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`] and xref:servlet/authentication/passwords/password-encoder.adoc#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 xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-input[Reading the Username & Password] works.
+
+.`DaoAuthenticationProvider` Usage
+image::{figures}/daoauthenticationprovider.png[]
+
+image:{icondir}/number_1.png[] The authentication `Filter` from xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-input[Reading the Username & Password] passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
+
+image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[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 xref:servlet/authentication/passwords/password-encoder.adoc#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 xref:servlet/authentication/architecture.adoc#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 xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/digest.adoc
similarity index 86%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/digest.adoc
index 3503f3f21c..913f175e36 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/digest.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/digest.adoc
@@ -11,14 +11,14 @@ All of these storage formats are considered insecure.
 Instead, you should store credentials using a one way adaptive password hash (i.e. bCrypt, PBKDF2, SCrypt, etc) which is not supported by Digest Authentication.
 ====
 
-Digest Authentication attempts to solve many of the weaknesses of <<servlet-authentication-basic,Basic authentication>>, specifically by ensuring credentials are never sent in clear text across the wire.
+Digest Authentication attempts to solve many of the weaknesses of xref:servlet/authentication/passwords/basic.adoc#servlet-authentication-basic[Basic authentication], specifically by ensuring credentials are never sent in clear text across the wire.
 Many https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest#Browser_compatibility[browsers support Digest Authentication].
 
 The standard governing HTTP Digest Authentication is defined by https://tools.ietf.org/html/rfc2617[RFC 2617], which updates an earlier version of the Digest Authentication standard prescribed by https://tools.ietf.org/html/rfc2069[RFC 2069].
 Most user agents implement RFC 2617.
 Spring Security's Digest Authentication support is compatible with the "`auth`" quality of protection (`qop`) prescribed by RFC 2617, which also provides backward compatibility with RFC 2069.
 Digest Authentication was seen as a more attractive option if you need to use unencrypted HTTP (i.e. no TLS/HTTPS) and wish to maximise security of the authentication process.
-However, everyone should use <<http,HTTPS>>.
+However, everyone should use xref:features/exploits/http.adoc#http[HTTPS].
 
 Central to Digest Authentication is a "nonce".
 This is a value the server generates.
@@ -34,7 +34,7 @@ key:              A private key to prevent modification of the nonce token
 ----
 ====
 
-You will need to ensure you <<authentication-password-storage-configuration,configure>> insecure plain text <<authentication-password-storage,Password Storage>> using `NoOpPasswordEncoder`.
+You will need to ensure you xref:features/authentication/password-storage.adoc#authentication-password-storage-configuration[configure] insecure plain text xref:features/authentication/password-storage.adoc#authentication-password-storage[Password Storage] using `NoOpPasswordEncoder`.
 The following provides an example of configuring Digest Authentication with Java Configuration:
 
 .Digest Authentication
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/form.adoc
similarity index 75%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/form.adoc
index f8745f89ab..941cbb037f 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/form.adoc
@@ -1,5 +1,6 @@
 [[servlet-authentication-form]]
 = Form Login
+:figures: servlet/authentication/unpwd
 
 Spring Security provides support for username and password being provided through an html form.
 This section provides details on how form based authentication works within Spring Security.
@@ -11,13 +12,13 @@ First, we see how the user is redirected to the log in form.
 .Redirecting to the Log In Page
 image::{figures}/loginurlauthenticationentrypoint.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
 image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
 
-image:{icondir}/number_2.png[] Spring Security's <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
+image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
 
-image:{icondir}/number_3.png[] Since the user is not authenticated, <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__ and sends a redirect to the log in page with the configured <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
+image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__ and sends a redirect to the log in page with the configured xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`].
 In most cases the `AuthenticationEntryPoint` is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`].
 
 image:{icondir}/number_4.png[] The browser will then request the log in page that it was redirected to.
@@ -26,22 +27,22 @@ image:{icondir}/number_5.png[] Something within the application, must <<servlet-
 
 [[servlet-authentication-usernamepasswordauthenticationfilter]]
 When the username and password are submitted, the `UsernamePasswordAuthenticationFilter` authenticates the username and password.
-The `UsernamePasswordAuthenticationFilter` extends <<servlet-authentication-abstractprocessingfilter>>, so this diagram should look pretty similar.
+The `UsernamePasswordAuthenticationFilter` extends xref:servlet/authentication/architecture.adoc#servlet-authentication-abstractprocessingfilter[AbstractAuthenticationProcessingFilter], so this diagram should look pretty similar.
 
 .Authenticating Username and Password
 image::{figures}/usernamepasswordauthenticationfilter.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
 
-image:{icondir}/number_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <<servlet-authentication-authentication,`Authentication`>> by extracting the username and password from the `HttpServletRequest`.
+image:{icondir}/number_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] by extracting the username and password from the `HttpServletRequest`.
 
 image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated.
-The details of what `AuthenticationManager` looks like depend on how the <<servlet-authentication-unpwd-storage,user information is stored>>.
+The details of what `AuthenticationManager` looks like depend on how the xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-storage[user information is stored].
 
 image:{icondir}/number_3.png[] If authentication fails, then __Failure__
 
-* The <<servlet-authentication-securitycontextholder>> is cleared out.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder] is cleared out.
 * `RememberMeServices.loginFail` is invoked.
 If remember me is not configured, this is a no-op.
 // FIXME: link to rememberme
@@ -52,13 +53,13 @@ image:{icondir}/number_4.png[] If authentication is successful, then __Success__
 
 * `SessionAuthenticationStrategy` is notified of a new log in.
 // FIXME: Add link to SessionAuthenticationStrategy
-* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[Authentication] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
 // FIXME: link securitycontextpersistencefilter
 * `RememberMeServices.loginSuccess` is invoked.
 If remember me is not configured, this is a no-op.
 // FIXME: link to rememberme
 * `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`.
-* The `AuthenticationSuccessHandler` is invoked. Typically this is a `SimpleUrlAuthenticationSuccessHandler` which will redirect to a request saved by <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> when we redirect to the log in page.
+* The `AuthenticationSuccessHandler` is invoked. Typically this is a `SimpleUrlAuthenticationSuccessHandler` which will redirect to a request saved by xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] when we redirect to the log in page.
 
 [[servlet-authentication-form-min]]
 Spring Security form log in is enabled by default.
@@ -182,7 +183,7 @@ Below is a https://www.thymeleaf.org/[Thymeleaf] template that produces an HTML
 There are a few key points about the default HTML form:
 
 * The form should perform a `post` to `/login`
-* The form will need to include a <<servlet-csrf,CSRF Token>> which is <<servlet-csrf-include-form-auto,automatically included>> by Thymeleaf.
+* The form will need to include a xref:servlet/exploits/csrf.adoc#servlet-csrf[CSRF Token] which is xref:servlet/exploits/csrf.adoc#servlet-csrf-include-form-auto[automatically included] by Thymeleaf.
 * The form should specify the username in a parameter named `username`
 * The form should specify the password in a parameter named `password`
 * If the HTTP parameter error is found, it indicates the user failed to provide a valid username / password
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/in-memory.adoc
similarity index 76%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/in-memory.adoc
index d5b178516b..62fb993c0d 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/in-memory.adoc
@@ -1,11 +1,11 @@
 [[servlet-authentication-inmemory]]
 = In-Memory Authentication
 
-Spring Security's `InMemoryUserDetailsManager` implements <<servlet-authentication-userdetailsservice,UserDetailsService>> to provide support for username/password based authentication that is stored in memory.
+Spring Security's `InMemoryUserDetailsManager` implements xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] to provide support for username/password based authentication that is stored in memory.
 `InMemoryUserDetailsManager` provides management of `UserDetails` by implementing the `UserDetailsManager` interface.
-`UserDetails` based authentication is used by Spring Security when it is configured to <<servlet-authentication-unpwd-input,accept a username/password>> for authentication.
+`UserDetails` based authentication is used by Spring Security when it is configured to xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication.
 
-In this sample we use <<authentication-password-storage-boot-cli,Spring Boot CLI>> to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`.
+In this sample we use xref:features/authentication/password-storage.adoc#authentication-password-storage-boot-cli[Spring Boot CLI] to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`.
 
 .InMemoryUserDetailsManager Java Configuration
 ====
@@ -64,7 +64,7 @@ fun users(): UserDetailsService {
 The samples above store the passwords in a secure format, but leave a lot to be desired in terms of getting started experience.
 
 
-In the sample below we leverage <<authentication-password-storage-dep-getting-started,User.withDefaultPasswordEncoder>> to ensure that the password stored in memory is protected.
+In the sample below we leverage xref:features/authentication/password-storage.adoc#authentication-password-storage-dep-getting-started[User.withDefaultPasswordEncoder] to ensure that the password stored in memory is protected.
 However, it does not protect against obtaining the password by decompiling the source code.
 For this reason, `User.withDefaultPasswordEncoder` should only be used for "getting started" and is not intended for production.
 
@@ -114,7 +114,7 @@ fun users(): UserDetailsService {
 ====
 
 There is no simple way to use `User.withDefaultPasswordEncoder` with XML based configuration.
-For demos or just getting started, you can choose to prefix the password with `+{noop}+` to indicate <<authentication-password-storage-dpe-format,no encoding should be used>>.
+For demos or just getting started, you can choose to prefix the password with `+{noop}+` to indicate xref:features/authentication/password-storage.adoc#authentication-password-storage-dpe-format[no encoding should be used].
 
 .<user-service> `+{noop}+` XML Configuration
 ====
diff --git a/docs/modules/ROOT/pages/servlet/authentication/passwords/index.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/index.adoc
new file mode 100644
index 0000000000..49efe3d2da
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/index.adoc
@@ -0,0 +1,27 @@
+[[servlet-authentication-unpwd]]
+= Username/Password Authentication
+:figures: images/servlet/authentication/unpwd
+:icondir: images/icons
+
+One of the most common ways to authenticate a user is by validating a username and password.
+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`:
+
+* xref:servlet/authentication/passwords/form.adoc#servlet-authentication-form[Form Login]
+* xref:servlet/authentication/passwords/basic.adoc#servlet-authentication-basic[Basic Authentication]
+* xref:servlet/authentication/passwords/digest.adoc#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 xref:servlet/authentication/passwords/in-memory.adoc#servlet-authentication-inmemory[In-Memory Authentication]
+* Relational Databases with xref:servlet/authentication/passwords/jdbc.adoc#servlet-authentication-jdbc[JDBC Authentication]
+* Custom data stores with xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService]
+* LDAP storage with xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[LDAP Authentication]
+
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/jdbc.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/jdbc.adoc
similarity index 87%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/jdbc.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/jdbc.adoc
index 009e551512..d4462eaaf8 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/jdbc.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/jdbc.adoc
@@ -1,9 +1,9 @@
 [[servlet-authentication-jdbc]]
 = JDBC Authentication
 
-Spring Security's `JdbcDaoImpl` implements <<servlet-authentication-userdetailsservice,UserDetailsService>> to provide support for username/password based authentication that is retrieved using JDBC.
+Spring Security's `JdbcDaoImpl` implements xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] to provide support for username/password based authentication that is retrieved using JDBC.
 `JdbcUserDetailsManager` extends `JdbcDaoImpl` to provide management of `UserDetails` through the `UserDetailsManager` interface.
-`UserDetails` based authentication is used by Spring Security when it is configured to <<servlet-authentication-unpwd-input,accept a username/password>> for authentication.
+`UserDetails` based authentication is used by Spring Security when it is configured to xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication.
 
 In the following sections we will discuss:
 
@@ -147,8 +147,8 @@ In a production environment, you will want to ensure you setup a connection to a
 [[servlet-authentication-jdbc-bean]]
 == JdbcUserDetailsManager Bean
 
-In this sample we use <<authentication-password-storage-boot-cli,Spring Boot CLI>> to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`.
-See the <<authentication-password-storage,PasswordEncoder>> section for more details about how to store passwords.
+In this sample we use xref:features/authentication/password-storage.adoc#authentication-password-storage-boot-cli[Spring Boot CLI] to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`.
+See the xref:features/authentication/password-storage.adoc#authentication-password-storage[PasswordEncoder] section for more details about how to store passwords.
 
 .JdbcUserDetailsManager
 ====
@@ -171,7 +171,7 @@ UserDetailsManager users(DataSource dataSource) {
 	JdbcUserDetailsManager users = new JdbcUserDetailsManager(dataSource);
 	users.createUser(user);
 	users.createUser(admin);
-	return users; 
+	return users;
 }
 ----
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/ldap.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/ldap.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/ldap.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/ldap.adoc
index 57f456deb8..aa4ad900ff 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/ldap.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/ldap.adoc
@@ -4,7 +4,7 @@
 LDAP is often used by organizations as a central repository for user information and as an authentication service.
 It can also be used to store the role information for application users.
 
-Spring Security's LDAP based authentication is used by Spring Security when it is configured to <<servlet-authentication-unpwd-input,accept a username/password>> for authentication.
+Spring Security's LDAP based authentication is used by Spring Security when it is configured to xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication.
 However, despite leveraging a username/password for authentication it does not integrate using `UserDetailsService` because in <<servlet-authentication-ldap-bind,bind authentication>> the LDAP server does not return the password so the application cannot perform validation of the password.
 
 There are many different scenarios for how an LDAP server may be configured so Spring Security's LDAP provider is fully configurable.
@@ -258,7 +258,7 @@ fun contextSource(container: UnboundIdContainer): ContextSource {
 [[servlet-authentication-ldap-authentication]]
 == Authentication
 
-Spring Security's LDAP support does not use the <<servlet-authentication-userdetailsservice>> because LDAP bind authentication does not allow clients to read the password or even a hashed version of the password.
+Spring Security's LDAP support does not use the xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] because LDAP bind authentication does not allow clients to read the password or even a hashed version of the password.
 This means there is no way a password to be read and then authenticated by Spring Security.
 
 For this reason, LDAP support is implemented using the `LdapAuthenticator` interface.
diff --git a/docs/modules/ROOT/pages/servlet/authentication/passwords/password-encoder.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/password-encoder.adoc
new file mode 100644
index 0000000000..de20d29004
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/password-encoder.adoc
@@ -0,0 +1,5 @@
+[[servlet-authentication-password-storage]]
+= PasswordEncoder
+
+Spring Security's servlet support storing passwords securely by integrating with xref:features/authentication/password-storage.adoc#authentication-password-storage[`PasswordEncoder`].
+Customizing the `PasswordEncoder` implementation used by Spring Security can be done by xref:features/authentication/password-storage.adoc#authentication-password-storage-configuration[exposing a `PasswordEncoder` Bean].
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/user-details-service.adoc
similarity index 63%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/passwords/user-details-service.adoc
index 9147cedbd2..d557c04041 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/user-details-service.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/user-details-service.adoc
@@ -1,8 +1,8 @@
 [[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`.
+{security-api-url}org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] is used by xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] for retrieving a username, password, and other attributes for authenticating with a username and password.
+Spring Security provides xref:servlet/authentication/passwords/in-memory.adoc#servlet-authentication-inmemory[in-memory] and xref:servlet/authentication/passwords/jdbc.adoc#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 `CustomUserDetailsService` implements `UserDetailsService`:
diff --git a/docs/modules/ROOT/pages/servlet/authentication/passwords/user-details.adoc b/docs/modules/ROOT/pages/servlet/authentication/passwords/user-details.adoc
new file mode 100644
index 0000000000..34918cb455
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/authentication/passwords/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 xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`].
+The xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] validates the `UserDetails` and then returns an xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/preauth.adoc b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc
similarity index 88%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/preauth.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/preauth.adoc
index f23b57a203..406c3f871f 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/preauth.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc
@@ -1,5 +1,5 @@
 [[servlet-preauth]]
-== Pre-Authentication Scenarios
+= Pre-Authentication Scenarios
 There are situations where you want to use Spring Security for authorization, but the user has already been reliably authenticated by some external system prior to accessing the application.
 We refer to these situations as "pre-authenticated" scenarios.
 Examples include X.509, Siteminder and authentication by the Java EE container in which the application is running.
@@ -16,16 +16,16 @@ If relying on container authentication, the user will be identified by calling t
 In some cases, the external mechanism may supply role/authority information for the user but in others the authorities must be obtained from a separate source, such as a `UserDetailsService`.
 
 
-=== Pre-Authentication Framework Classes
+== Pre-Authentication Framework Classes
 Because most pre-authentication mechanisms follow the same pattern, Spring Security has a set of classes which provide an internal framework for implementing pre-authenticated authentication providers.
 This removes duplication and allows new implementations to be added in a structured fashion, without having to write everything from scratch.
-You don't need to know about these classes if you want to use something like <<servlet-x509,X.509 authentication>>, as it already has a namespace configuration option which is simpler to use and get started with.
+You don't need to know about these classes if you want to use something like xref:servlet/authentication/x509.adoc#servlet-x509[X.509 authentication], as it already has a namespace configuration option which is simpler to use and get started with.
 If you need to use explicit bean configuration or are planning on writing your own implementation then an understanding of how the provided implementations work will be useful.
 You will find classes under the `org.springframework.security.web.authentication.preauth`.
 We just provide an outline here so you should consult the Javadoc and source where appropriate.
 
 
-==== AbstractPreAuthenticatedProcessingFilter
+=== AbstractPreAuthenticatedProcessingFilter
 This class will check the current contents of the security context and, if empty, it will attempt to extract user information from the HTTP request and submit it to the `AuthenticationManager`.
 Subclasses override the following methods to obtain this information:
 
@@ -59,7 +59,7 @@ We'll look at a concrete example next.
 
 
 [[j2ee-preauth-details]]
-===== J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource
+==== J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource
 If the filter is configured with an `authenticationDetailsSource` which is an instance of this class, the authority information is obtained by calling the `isUserInRole(String role)` method for each of a pre-determined set of "mappable roles".
 The class gets these from a configured `MappableAttributesRetriever`.
 Possible implementations include hard-coding a list in the application context and reading the role information from the `<security-role>` information in a `web.xml` file.
@@ -69,7 +69,7 @@ There is an additional stage where the roles (or attributes) are mapped to Sprin
 The default will just add the usual `ROLE_` prefix to the names, but it gives you full control over the behaviour.
 
 
-==== PreAuthenticatedAuthenticationProvider
+=== PreAuthenticatedAuthenticationProvider
 The pre-authenticated provider has little more to do than load the `UserDetails` object for the user.
 It does this by delegating to an `AuthenticationUserDetailsService`.
 The latter is similar to the standard `UserDetailsService` but takes an `Authentication` object rather than just user name:
@@ -85,19 +85,19 @@ This interface may have also other uses but with pre-authentication it allows ac
 The `PreAuthenticatedGrantedAuthoritiesUserDetailsService` class does this.
 Alternatively, it may delegate to a standard `UserDetailsService` via the `UserDetailsByNameServiceWrapper` implementation.
 
-==== Http403ForbiddenEntryPoint
-The <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>> is responsible for kick-starting the authentication process for an unauthenticated user (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply.
+=== Http403ForbiddenEntryPoint
+The xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is responsible for kick-starting the authentication process for an unauthenticated user (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply.
 You would only configure the `ExceptionTranslationFilter` with an instance of this class if you aren't using pre-authentication in combination with other authentication mechanisms.
 It will be called if the user is rejected by the `AbstractPreAuthenticatedProcessingFilter` resulting in a null authentication.
 It always returns a `403`-forbidden response code if called.
 
 
-=== Concrete Implementations
-X.509 authentication is covered in its <<servlet-x509,own chapter>>.
+== Concrete Implementations
+X.509 authentication is covered in its xref:servlet/authentication/x509.adoc#servlet-x509[own chapter].
 Here we'll look at some classes which provide support for other pre-authenticated scenarios.
 
 
-==== Request-Header Authentication (Siteminder)
+=== Request-Header Authentication (Siteminder)
 An external authentication system may supply information to the application by setting specific headers on the HTTP request.
 A well-known example of this is Siteminder, which passes the username in a header called `SM_USER`.
 This mechanism is supported by the class `RequestHeaderAuthenticationFilter` which simply extracts the username from the header.
@@ -110,7 +110,7 @@ Note that when using a system like this, the framework performs no authenticatio
 If an attacker is able to forge the headers in their original request without this being detected then they could potentially choose any username they wished.
 ====
 
-===== Siteminder Example Configuration
+==== Siteminder Example Configuration
 A typical configuration using this filter would look like this:
 
 [source,xml]
@@ -139,11 +139,11 @@ A typical configuration using this filter would look like this:
 </security:authentication-manager>
 ----
 
-We've assumed here that the <<ns-config,security namespace>> is being used for configuration.
+We've assumed here that the xref:servlet/configuration/xml-namespace.adoc#ns-config[security namespace] is being used for configuration.
 It's also assumed that you have added a `UserDetailsService` (called "userDetailsService") to your configuration to load the user's roles.
 
 
-==== Java EE Container Authentication
+=== Java EE Container Authentication
 The class `J2eePreAuthenticatedProcessingFilter` will extract the username from the `userPrincipal` property of the `HttpServletRequest`.
 Use of this filter would usually be combined with the use of Java EE roles as described above in <<j2ee-preauth-details>>.
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc
similarity index 95%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc
index b2375d62cb..5e75fc219e 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc
@@ -1,9 +1,9 @@
 [[servlet-rememberme]]
-== Remember-Me Authentication
+= Remember-Me Authentication
 
 
 [[remember-me-overview]]
-=== Overview
+== Overview
 Remember-me or persistent-login authentication refers to web sites being able to remember the identity of a principal between sessions.
 This is typically accomplished by sending a cookie to the browser, with the cookie being detected during future sessions and causing automated login to take place.
 Spring Security provides the necessary hooks for these operations to take place, and has two concrete remember-me implementations.
@@ -14,7 +14,7 @@ If you are using an authentication provider which doesn't use a `UserDetailsServ
 
 
 [[remember-me-hash-token]]
-=== Simple Hash-Based Token Approach
+== Simple Hash-Based Token Approach
 This approach uses hashing to achieve a useful remember-me strategy.
 In essence a cookie is sent to the browser upon successful interactive authentication, with the cookie being composed as follows:
 
@@ -36,7 +36,7 @@ If a principal is aware a token has been captured, they can easily change their
 If more significant security is needed you should use the approach described in the next section.
 Alternatively, remember-me services should simply not be used at all.
 
-If you are familiar with the topics discussed in the chapter on <<ns-config,namespace configuration>>, you can enable remember-me authentication just by adding the `<remember-me>` element:
+If you are familiar with the topics discussed in the chapter on xref:servlet/configuration/xml-namespace.adoc#ns-config[namespace configuration], you can enable remember-me authentication just by adding the `<remember-me>` element:
 
 [source,xml]
 ----
@@ -50,7 +50,7 @@ The `UserDetailsService` will normally be selected automatically.
 If you have more than one in your application context, you need to specify which one should be used with the `user-service-ref` attribute, where the value is the name of your `UserDetailsService` bean.
 
 [[remember-me-persistent-token]]
-=== Persistent Token Approach
+== Persistent Token Approach
 This approach is based on the article https://web.archive.org/web/20180819014446/http://jaspan.com/improved_persistent_login_cookie_best_practice[http://jaspan.com/improved_persistent_login_cookie_best_practice] with some minor modifications  footnote:[Essentially, the username is not included in the cookie, to prevent exposing a valid login name unecessarily.
 There is a discussion on this in the comments section of this article.].
 To use the this approach with namespace configuration, you would supply a datasource reference:
@@ -74,7 +74,7 @@ create table persistent_logins (username varchar(64) not null,
 ----
 
 [[remember-me-impls]]
-=== Remember-Me Interfaces and Implementations
+== Remember-Me Interfaces and Implementations
 Remember-me is used with `UsernamePasswordAuthenticationFilter`, and is implemented via hooks in the `AbstractAuthenticationProcessingFilter` superclass.
 It is also used within `BasicAuthenticationFilter`.
 The hooks will invoke a concrete `RememberMeServices` at the appropriate times.
@@ -97,7 +97,7 @@ This design allows any number of remember-me implementation strategies.
 We've seen above that Spring Security provides two implementations.
 We'll look at these in turn.
 
-==== TokenBasedRememberMeServices
+=== TokenBasedRememberMeServices
 This implementation supports the simpler approach described in <<remember-me-hash-token>>.
 `TokenBasedRememberMeServices` generates a `RememberMeAuthenticationToken`, which is processed by `RememberMeAuthenticationProvider`.
 A `key` is shared between this authentication provider and the `TokenBasedRememberMeServices`.
@@ -130,7 +130,7 @@ The beans required in an application context to enable remember-me services are
 Don't forget to add your `RememberMeServices` implementation to your `UsernamePasswordAuthenticationFilter.setRememberMeServices()` property, include the `RememberMeAuthenticationProvider` in your `AuthenticationManager.setProviders()` list, and add `RememberMeAuthenticationFilter` into your `FilterChainProxy` (typically immediately after your `UsernamePasswordAuthenticationFilter`).
 
 
-==== PersistentTokenBasedRememberMeServices
+=== PersistentTokenBasedRememberMeServices
 This class can be used in the same way as `TokenBasedRememberMeServices`, but it additionally needs to be configured with a `PersistentTokenRepository` to store the tokens.
 There are two standard implementations.
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc b/docs/modules/ROOT/pages/servlet/authentication/runas.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/runas.adoc
index 0b439ad369..258e5a033c 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/runas.adoc
@@ -1,8 +1,8 @@
 [[runas]]
-== Run-As Authentication Replacement
+= Run-As Authentication Replacement
 
 [[runas-overview]]
-=== Overview
+== Overview
 The `AbstractSecurityInterceptor` is able to temporarily replace the `Authentication` object in the `SecurityContext` and `SecurityContextHolder` during the secure object callback phase.
 This only occurs if the original `Authentication` object was successfully processed by the `AuthenticationManager` and `AccessDecisionManager`.
 The `RunAsManager` will indicate the replacement `Authentication` object, if any, that should be used during the `SecurityInterceptorCallback`.
@@ -12,7 +12,7 @@ It will also be able to perform any internal security checks for specific `Grant
 Because Spring Security provides a number of helper classes that automatically configure remoting protocols based on the contents of the `SecurityContextHolder`, these run-as replacements are particularly useful when calling remote web services.
 
 [[runas-config]]
-=== Configuration
+== Configuration
 A `RunAsManager` interface is provided by Spring Security:
 
 [source,java]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/session-management.adoc
index bee0394d4b..6024d34a1b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/session-management.adoc
@@ -1,9 +1,9 @@
 [[session-mgmt]]
-== Session Management
+= Session Management
 HTTP session related functionality is handled by a combination of the `SessionManagementFilter` and the `SessionAuthenticationStrategy` interface, which the filter delegates to.
 Typical usage includes session-fixation protection attack prevention, detection of session timeouts and restrictions on how many sessions an authenticated user may have open concurrently.
 
-=== Detecting Timeouts
+== Detecting Timeouts
 You can configure Spring Security to detect the submission of an invalid session ID and redirect the user to an appropriate URL.
 This is achieved through the `session-management` element:
 
@@ -74,7 +74,7 @@ Header always set Set-Cookie "JSESSIONID=;Path=/tutorial;Expires=Thu, 01 Jan 197
 
 
 [[ns-concurrent-sessions]]
-=== Concurrent Session Control
+== Concurrent Session Control
 If you wish to place constraints on a single user's ability to log in to your application, Spring Security supports this out of the box with the following simple additions.
 First, you need to add the following listener to your configuration to keep Spring Security updated about session lifecycle events:
 
@@ -165,7 +165,7 @@ If you are using a customized authentication filter for form-based login, then y
 More details can be found in the <<session-mgmt,Session Management chapter>>.
 
 [[ns-session-fixation]]
-=== Session Fixation Attack Protection
+== Session Fixation Attack Protection
 https://en.wikipedia.org/wiki/Session_fixation[Session fixation] attacks are a potential risk where it is possible for a malicious attacker to create a session by accessing a site, then persuade another user to log in with the same session (by sending them a link containing the session identifier as a parameter, for example).
 Spring Security protects against this automatically by creating a new session or otherwise changing the session ID when a user logs in.
 If you don't require this protection, or it conflicts with some other requirement, you can control the behavior using the `session-fixation-protection` attribute on `<session-management>`, which has four options
@@ -189,7 +189,7 @@ When session fixation protection occurs, it results in a `SessionFixationProtect
 If you use `changeSessionId`, this protection will __also__ result in any  ``javax.servlet.http.HttpSessionIdListener``s being notified, so use caution if your code listens for both events.
 See the <<session-mgmt,Session Management>> chapter for additional information.
 
-=== SessionManagementFilter
+== SessionManagementFilter
 The `SessionManagementFilter` checks the contents of the `SecurityContextRepository` against the current contents of the `SecurityContextHolder` to determine whether a user has been authenticated during the current request, typically by a non-interactive authentication mechanism, such as pre-authentication or remember-me  footnote:[
 Authentication by mechanisms which perform a redirect after authenticating (such as form-login) will not be detected by `SessionManagementFilter`, as the filter will not be invoked during the authenticating request.
 Session-management functionality has to be handled separately in these cases.
@@ -203,7 +203,7 @@ The most common behaviour is just to redirect to a fixed URL and this is encapsu
 The latter is also used when configuring an invalid session URL through the namespace, <<session-mgmt,as described earlier>>.
 
 
-=== SessionAuthenticationStrategy
+== SessionAuthenticationStrategy
 `SessionAuthenticationStrategy` is used by both `SessionManagementFilter` and `AbstractAuthenticationProcessingFilter`, so if you are using a customized form-login class, for example, you will need to inject it into both of these.
 In this case, a typical configuration, combining the namespace and custom beans might look like this:
 
@@ -230,7 +230,7 @@ Note that the use of the default, `SessionFixationProtectionStrategy` may cause
 See the Javadoc for this class for more information.
 
 [[concurrent-sessions]]
-=== Concurrency Control
+== Concurrency Control
 Spring Security is able to prevent a principal from concurrently authenticating to the same application more than a specified number of times.
 Many ISVs take advantage of this to enforce licensing, whilst network administrators like this feature because it helps prevent people from sharing login names.
 You can, for example, stop user "Batman" from logging onto the web application from two different sessions.
@@ -327,7 +327,7 @@ Without it, a user will never be able to log back in again once they have exceed
 
 
 [[list-authenticated-principals]]
-==== Querying the SessionRegistry for currently authenticated users and their sessions
+=== Querying the SessionRegistry for currently authenticated users and their sessions
 Setting up concurrency-control, either through the namespace or using plain beans has the useful side effect of providing you with a reference to the `SessionRegistry` which you can use directly within your application, so even if you don't want to restrict the number of sessions a user may have, it may be worth setting up the infrastructure anyway.
 You can set the `maximumSession` property to -1 to allow unlimited sessions.
 If you're using the namespace, you can set an alias for the internally-created `SessionRegistry` using the `session-registry-alias` attribute, providing a reference which you can inject into your own beans.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/x509.adoc b/docs/modules/ROOT/pages/servlet/authentication/x509.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authentication/x509.adoc
rename to docs/modules/ROOT/pages/servlet/authentication/x509.adoc
index 138721e127..5dc29b08d1 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/x509.adoc
+++ b/docs/modules/ROOT/pages/servlet/authentication/x509.adoc
@@ -1,9 +1,9 @@
 [[servlet-x509]]
-== X.509 Authentication
+= X.509 Authentication
 
 
 [[x509-overview]]
-=== Overview
+== Overview
 The most common use of X.509 certificate authentication is in verifying the identity of a server when using SSL, most commonly when using HTTPS from a browser.
 The browser will automatically check that the certificate presented by a server has been issued (ie digitally signed) by one of a list of trusted certificate authorities which it maintains.
 
@@ -19,7 +19,7 @@ For example, if you're using Tomcat then read the instructions here https://tomc
 It's important that you get this working before trying it out with Spring Security
 
 
-=== Adding X.509 Authentication to Your Web Application
+== Adding X.509 Authentication to Your Web Application
 Enabling X.509 client authentication is very straightforward.
 Just add the `<x509/>` element to your http security namespace configuration.
 
@@ -51,7 +51,7 @@ If no certificate is found, or no corresponding user could be found then the sec
 This means that you can easily use X.509 authentication with other options such as a form-based login.
 
 [[x509-ssl-config]]
-=== Setting up SSL in Tomcat
+== Setting up SSL in Tomcat
 There are some pre-generated certificates in the {gh-samples-url}/servlet/java-configuration/authentication/x509/server[Spring Security Samples repository].
 You can use these to enable SSL for testing if you don't want to generate your own.
 The file `server.jks` contains the server certificate, private key and the issuing certificate authority certificate.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/acls.adoc b/docs/modules/ROOT/pages/servlet/authorization/acls.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/acls.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/acls.adoc
index 32ef05e387..1735e9000b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/acls.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/acls.adoc
@@ -1,8 +1,8 @@
 [[domain-acls]]
-== Domain Object Security (ACLs)
+= Domain Object Security (ACLs)
 
 [[domain-acls-overview]]
-=== Overview
+== Overview
 Complex applications often will find the need to define access permissions not simply at a web request or method invocation level.
 Instead, security decisions need to comprise both who (`Authentication`), where (`MethodInvocation`) and what (`SomeDomainObject`).
 In other words, authorization decisions also need to consider the actual domain object instance subject of a method invocation.
@@ -37,7 +37,7 @@ Fortunately, there is another alternative, which we'll talk about below.
 
 
 [[domain-acls-key-concepts]]
-=== Key Concepts
+== Key Concepts
 Spring Security's ACL services are shipped in the `spring-security-acl-xxx.jar`.
 You will need to add this JAR to your classpath to use Spring Security's domain object instance security capabilities.
 
@@ -130,7 +130,7 @@ We suggest taking a look over these for examples.
 
 
 [[domain-acls-getting-started]]
-=== Getting Started
+== Getting Started
 To get starting using Spring Security's ACL capability, you will need to store your ACL information somewhere.
 This necessitates the instantiation of a `DataSource` using Spring.
 The `DataSource` is then injected into a `JdbcMutableAclService` and `BasicLookupStrategy` instance.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc b/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/architecture.adoc
index 25bf39f375..dd4ad3ee19 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc
@@ -2,11 +2,11 @@
 
 [[authz-arch]]
 = Authorization Architecture
-
+:figures: servlet/authorization
 
 [[authz-authorities]]
 == Authorities
-<<servlet-authentication-authentication,`Authentication`>>, discusses how all `Authentication` implementations store a list of `GrantedAuthority` objects.
+xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`], discusses how all `Authentication` implementations store a list of `GrantedAuthority` objects.
 These represent the authorities that have been granted to the principal.
 The `GrantedAuthority` objects are inserted into the `Authentication` object by the `AuthenticationManager` and are later read by ``AccessDecisionManager``s when making authorization decisions.
 
@@ -70,7 +70,7 @@ Whilst users can implement their own `AccessDecisionManager` to control all aspe
 
 [[authz-access-voting]]
 .Voting Decision Manager
-image::images/access-decision-voting.png[]
+image::{figures}/access-decision-voting.png[]
 
 
 
@@ -140,7 +140,7 @@ Whilst you could easily implement your own AOP concern to achieve this, Spring S
 
 [[authz-after-invocation]]
 .After Invocation Implementation
-image::images/after-invocation.png[]
+image::{figures}/after-invocation.png[]
 
 Like many other parts of Spring Security, `AfterInvocationManager` has a single concrete implementation, `AfterInvocationProviderManager`, which polls a list of ``AfterInvocationProvider``s.
 Each `AfterInvocationProvider` is allowed to modify the return object or throw an `AccessDeniedException`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/authorize-requests.adoc b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
similarity index 79%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/authorize-requests.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
index 31ce88ecee..bbf771a73b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/authorize-requests.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
@@ -1,24 +1,23 @@
 [[servlet-authorization-filtersecurityinterceptor]]
 = Authorize HttpServletRequest with FilterSecurityInterceptor
-:figures: images/servlet/authorization
-:icondir: images/icons
+:figures: servlet/authorization
 
-This section builds on <<servlet-architecture,Servlet Architecture and Implementation>> by digging deeper into how <<servlet-authorization,authorization>> works within Servlet based applications.
+This section builds on xref:servlet/architecture.adoc#servlet-architecture[Servlet Architecture and Implementation] by digging deeper into how xref:servlet/authorization/index.adoc#servlet-authorization[authorization] works within Servlet based applications.
 
-The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides <<servlet-authorization,authorization>> for ``HttpServletRequest``s.
-It is inserted into the <<servlet-filterchainproxy>> as one of the <<servlet-security-filters>>.
+The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides xref:servlet/authorization/index.adoc#servlet-authorization[authorization] for ``HttpServletRequest``s.
+It is inserted into the xref:servlet/architecture.adoc#servlet-filterchainproxy[FilterChainProxy] as one of the xref:servlet/architecture.adoc#servlet-security-filters[Security Filters].
 
 .Authorize HttpServletRequest
 image::{figures}/filtersecurityinterceptor.png[]
 
-* image:{icondir}/number_1.png[] First, the `FilterSecurityInterceptor` obtains an  <<servlet-authentication-authentication>> from the <<servlet-authentication-securitycontextholder>>.
+* image:{icondir}/number_1.png[] First, the `FilterSecurityInterceptor` obtains an  xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[Authentication] from the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
 * image:{icondir}/number_2.png[] Second, `FilterSecurityInterceptor` creates a {security-api-url}org/springframework/security/web/FilterInvocation.html[`FilterInvocation`] from the `HttpServletRequest`, `HttpServletResponse`, and `FilterChain` that are passed into the `FilterSecurityInterceptor`.
 // FIXME: link to FilterInvocation
 * image:{icondir}/number_3.png[] Next, it passes the `FilterInvocation` to `SecurityMetadataSource` to get the ``ConfigAttribute``s.
 * image:{icondir}/number_4.png[] Finally, it passes the `Authentication`, `FilterInvocation`, and ``ConfigAttribute``s to the `AccessDecisionManager`.
 ** image:{icondir}/number_5.png[] If authorization is denied, an `AccessDeniedException` is thrown.
-In this case the <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> handles the `AccessDeniedException`.
-** image:{icondir}/number_6.png[] If access is granted, `FilterSecurityInterceptor` continues with the <<servlet-filters-review,FilterChain>> which allows the application to process normally.
+In this case the xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] handles the `AccessDeniedException`.
+** image:{icondir}/number_6.png[] If access is granted, `FilterSecurityInterceptor` continues with the xref:servlet/architecture.adoc#servlet-filters-review[FilterChain] which allows the application to process normally.
 
 // configuration (xml/java)
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc b/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc
index 1070783c92..f5b916d636 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/expression-based.adoc
@@ -1,18 +1,18 @@
 
 [[el-access]]
-== Expression-Based Access Control
+= Expression-Based Access Control
 Spring Security 3.0 introduced the ability to use Spring EL expressions as an authorization mechanism in addition to the simple use of configuration attributes and access-decision voters which have been seen before.
 Expression-based access control is built on the same architecture but allows complicated Boolean logic to be encapsulated in a single expression.
 
 
-=== Overview
+== Overview
 Spring Security uses Spring EL for expression support and you should look at how that works if you are interested in understanding the topic in more depth.
 Expressions are evaluated with a "root object" as part of the evaluation context.
 Spring Security uses specific classes for web and method security as the root object, in order to provide built-in expressions and access to values such as the current principal.
 
 
 [[el-common-built-in]]
-==== Common Built-In Expressions
+=== Common Built-In Expressions
 The base class for expression root objects is `SecurityExpressionRoot`.
 This provides some common expressions which are available in both web and method security.
 
@@ -83,7 +83,7 @@ For example, `hasPermission(1, 'com.example.domain.Message', 'read')`
 
 
 [[el-access-web]]
-=== Web Security Expressions
+== Web Security Expressions
 To use expressions to secure individual URLs, you would first need to set the `use-expressions` attribute in the `<http>` element to `true`.
 Spring Security will then expect the `access` attributes of the `<intercept-url>` elements to contain Spring EL expressions.
 The expressions should evaluate to a Boolean, defining whether access should be allowed or not.
@@ -109,7 +109,7 @@ If expressions are being used, a `WebExpressionVoter` will be added to the `Acce
 So if you aren't using the namespace and want to use expressions, you will have to add one of these to your configuration.
 
 [[el-access-web-beans]]
-==== Referring to Beans in Web Security Expressions
+=== Referring to Beans in Web Security Expressions
 
 If you wish to extend the expressions that are available, you can easily refer to any Spring Bean you expose.
 For example, assuming you have a Bean with the name of `webSecurity` that contains the following method signature:
@@ -172,7 +172,7 @@ http {
 ====
 
 [[el-access-web-path-variables]]
-==== Path Variables in Web Security Expressions
+=== Path Variables in Web Security Expressions
 
 At times it is nice to be able to refer to path variables within a URL.
 For example, consider a RESTful application that looks up a user by id from the URL path in the format `+/user/{userId}+`.
@@ -240,13 +240,13 @@ http {
 In this configuration URLs that match would pass in the path variable (and convert it) into checkUserId method.
 For example, if the URL were `/user/123/resource`, then the id passed in would be `123`.
 
-=== Method Security Expressions
+== Method Security Expressions
 Method security is a bit more complicated than a simple allow or deny rule.
 Spring Security 3.0 introduced some new annotations in order to allow comprehensive support for the use of expressions.
 
 
 [[el-pre-post-annotations]]
-==== @Pre and @Post Annotations
+=== @Pre and @Post Annotations
 There are four annotations which support expression attributes to allow pre and post-invocation authorization checks and also to support filtering of submitted collection arguments or return values.
 They are `@PreAuthorize`, `@PreFilter`, `@PostAuthorize` and `@PostFilter`.
 Their use is enabled through the `global-method-security` namespace element:
@@ -256,7 +256,7 @@ Their use is enabled through the `global-method-security` namespace element:
 <global-method-security pre-post-annotations="enabled"/>
 ----
 
-===== Access Control using @PreAuthorize and @PostAuthorize
+==== Access Control using @PreAuthorize and @PostAuthorize
 The most obviously useful annotation is `@PreAuthorize` which decides whether a method can actually be invoked or not.
 For example (from the {gh-samples-url}/servlet/xml/java/contacts[Contacts] sample application)
 
@@ -412,7 +412,7 @@ This can be achieved using the `@PostAuthorize` annotation.
 To access the return value from a method, use the built-in name `returnObject` in the expression.
 --
 
-===== Filtering using @PreFilter and @PostFilter
+==== Filtering using @PreFilter and @PostFilter
 Spring Security supports filtering of collections, arrays, maps and streams using expressions.
 This is most commonly performed on the return value of a method.
 For example:
@@ -447,13 +447,13 @@ If you are filtering large collections and removing many of the entries then thi
 
 
 [[el-method-built-in]]
-==== Built-In Expressions
+=== Built-In Expressions
 There are some built-in expressions which are specific to method security, which we have already seen in use above.
 The `filterTarget` and `returnValue` values are simple enough, but the use of the `hasPermission()` expression warrants a closer look.
 
 
 [[el-permission-evaluator]]
-===== The PermissionEvaluator interface
+==== The PermissionEvaluator interface
 `hasPermission()` expressions are delegated to an instance of `PermissionEvaluator`.
 It is intended to bridge between the expression system and Spring Security's ACL system, allowing you to specify authorization constraints on domain objects, based on abstract permissions.
 It has no explicit dependencies on the ACL module, so you could swap that out for an alternative implementation if required.
@@ -494,7 +494,7 @@ Where `myPermissionEvaluator` is the bean which implements `PermissionEvaluator`
 Usually this will be the implementation from the ACL module which is called `AclPermissionEvaluator`.
 See the {gh-samples-url}/servlet/xml/java/contacts[Contacts] sample application configuration for more details.
 
-===== Method Security Meta Annotations
+==== Method Security Meta Annotations
 
 You can make use of meta annotations for method security to make your code more readable.
 This is especially convenient if you find that you are repeating the same complex expression throughout your code base.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/index.adoc b/docs/modules/ROOT/pages/servlet/authorization/index.adoc
similarity index 68%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/index.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/index.adoc
index 2e4dfc59ac..fec5d6b31f 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/index.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/index.adoc
@@ -6,15 +6,10 @@ Irrespective of how you choose to authenticate - whether using a Spring Security
 In this part we'll explore the different `AbstractSecurityInterceptor` implementations, which were introduced in Part I.
 We then move on to explore how to fine-tune authorization through use of domain access control lists.
 
-include::architecture.adoc[leveloffset=+1]
-
-include::authorize-requests.adoc[leveloffset=+1]
-
-include::expression-based.adoc[]
-
-include::secure-objects.adoc[]
-
-include::method-security.adoc[]
-
-include::acls.adoc[]
+* xref:servlet/authorization/architecture.adoc[leveloffset=+1]
+* xref:servlet/authorization/authorize-requests.adoc[leveloffset=+1]
+* xref:servlet/authorization/expression-based.adoc[]
+* xref:servlet/authorization/secure-objects.adoc[]
+* xref:servlet/authorization/method-security.adoc[]
+* xref:servlet/authorization/acls.adoc[]
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/method-security.adoc b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc
similarity index 98%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/method-security.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/method-security.adoc
index b960be9e22..8b194fd275 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/method-security.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc
@@ -1,12 +1,12 @@
 [[jc-method]]
-== Method Security
+= Method Security
 
 From version 2.0 onwards Spring Security has improved support substantially for adding security to your service layer methods.
 It provides support for JSR-250 annotation security as well as the framework's original `@Secured` annotation.
-From 3.0 you can also make use of new <<el-access,expression-based annotations>>.
+From 3.0 you can also make use of new xref:servlet/authorization/expression-based.adoc#el-access[expression-based annotations].
 You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts.
 
-=== EnableMethodSecurity
+== EnableMethodSecurity
 
 In Spring Security 5.6, we can enable annotation-based security using the `@EnableMethodSecurity` annotation on any `@Configuration` instance.
 
@@ -149,7 +149,7 @@ class MethodSecurityConfig {
 ----
 ====
 
-==== Customizing Authorization
+=== Customizing Authorization
 
 Spring Security's `@PreAuthorize`, `@PostAuthorize`, `@PreFilter`, and `@PostFilter` ship with rich expression-based support.
 
@@ -245,7 +245,7 @@ We expose `GrantedAuthorityDefaults` using a `static` method to ensure that Spri
 ====
 
 [[jc-method-security-custom-authorization-manager]]
-==== Custom Authorization Managers
+=== Custom Authorization Managers
 
 Method authorization is a combination of before- and after-method authorization.
 
@@ -598,7 +598,7 @@ class MethodSecurityConfig {
 and it will be invoked after the `@PostAuthorize` interceptor.
 
 [[jc-enable-global-method-security]]
-=== EnableGlobalMethodSecurity
+== EnableGlobalMethodSecurity
 
 We can enable annotation-based security using the `@EnableGlobalMethodSecurity` annotation on any `@Configuration` instance.
 For example, the following would enable Spring Security's `@Secured` annotation.
@@ -740,7 +740,7 @@ interface BankService {
 ----
 ====
 
-=== GlobalMethodSecurityConfiguration
+== GlobalMethodSecurityConfiguration
 
 Sometimes you may need to perform operations that are more complicated than are possible with the `@EnableGlobalMethodSecurity` annotation allow.
 For these instances, you can extend the `GlobalMethodSecurityConfiguration` ensuring that the `@EnableGlobalMethodSecurity` annotation is present on your subclass.
@@ -776,7 +776,7 @@ open class MethodSecurityConfig : GlobalMethodSecurityConfiguration() {
 For additional information about methods that can be overridden, refer to the `GlobalMethodSecurityConfiguration` Javadoc.
 
 [[ns-global-method]]
-=== The <global-method-security> Element
+== The <global-method-security> Element
 This element is used to enable annotation-based security in your application (by setting the appropriate attributes on the element), and also to group together security pointcut declarations which will be applied across your entire application context.
 You should only declare one `<global-method-security>` element.
 The following declaration would enable support for Spring Security's `@Secured`:
@@ -889,7 +889,7 @@ If two annotations are found which apply to a particular method, then only one o
 ====
 
 [[ns-protect-pointcut]]
-=== Adding Security Pointcuts using protect-pointcut
+== Adding Security Pointcuts using protect-pointcut
 
 The use of `protect-pointcut` is particularly powerful, as it allows you to apply security to many beans with only a simple declaration.
 Consider the following example:
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/secure-objects.adoc b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc
similarity index 95%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/authorization/secure-objects.adoc
rename to docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc
index 3182ac322f..b85afb3a5a 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/secure-objects.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc
@@ -1,11 +1,11 @@
 
 [[secure-object-impls]]
-== Secure Object Implementations
+= Secure Object Implementations
 
 [[aop-alliance]]
-=== AOP Alliance (MethodInvocation) Security Interceptor
+== AOP Alliance (MethodInvocation) Security Interceptor
 Prior to Spring Security 2.0, securing ``MethodInvocation``s needed quite a lot of boiler plate configuration.
-Now the recommended approach for method security is to use <<ns-method-security,namespace configuration>>.
+Now the recommended approach for method security is to use xref:servlet/configuration/xml-namespace.adoc#ns-method-security[namespace configuration].
 This way the method security infrastructure beans are configured automatically for you so you don't really need to know about the implementation classes.
 We'll just provide a quick overview of the classes that are involved here.
 
@@ -15,7 +15,7 @@ The interceptor uses a `MethodSecurityMetadataSource` instance to obtain the con
 `MapBasedMethodSecurityMetadataSource` is used to store configuration attributes keyed by method names (which can be wildcarded) and will be used internally when the attributes are defined in the application context using the `<intercept-methods>` or `<protect-point>` elements.
 Other implementations will be used to handle annotation-based configuration.
 
-==== Explicit MethodSecurityInterceptor Configuration
+=== Explicit MethodSecurityInterceptor Configuration
 You can of course configure a `MethodSecurityInterceptor` directly in your application context for use with one of Spring AOP's proxying mechanisms:
 
 [source,xml]
@@ -36,7 +36,7 @@ You can of course configure a `MethodSecurityInterceptor` directly in your appli
 ----
 
 [[aspectj]]
-=== AspectJ (JoinPoint) Security Interceptor
+== AspectJ (JoinPoint) Security Interceptor
 The AspectJ security interceptor is very similar to the AOP Alliance security interceptor discussed in the previous section.
 Indeed we will only discuss the differences in this section.
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc b/docs/modules/ROOT/pages/servlet/configuration/java.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc
rename to docs/modules/ROOT/pages/servlet/configuration/java.adoc
index 48205a64a6..bf100524cc 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc
+++ b/docs/modules/ROOT/pages/servlet/configuration/java.adoc
@@ -5,7 +5,7 @@
 General support for https://docs.spring.io/spring/docs/3.1.x/spring-framework-reference/html/beans.html#beans-java[Java Configuration] was added to Spring Framework in Spring 3.1.
 Since Spring Security 3.2 there has been Spring Security Java Configuration support which enables users to easily configure Spring Security without the use of any XML.
 
-If you are familiar with the <<ns-config>> then you should find quite a few similarities between it and the Security Java Configuration support.
+If you are familiar with the xref:servlet/configuration/xml-namespace.adoc#ns-config[Security Namespace Configuration] then you should find quite a few similarities between it and the Security Java Configuration support.
 
 NOTE: Spring Security provides https://github.com/spring-projects/spring-security-samples/tree/main/servlet/java-configuration[lots of sample applications] which demonstrate the use of Spring Security Java Configuration.
 
@@ -312,7 +312,7 @@ public class Config extends WebSecurityConfigurerAdapter {
 
 Spring Security's Java Configuration does not expose every property of every object that it configures.
 This simplifies the configuration for a majority of users.
-After all, if every property was exposed, users could use standard bean configuration.
+Afterall, if every property was exposed, users could use standard bean configuration.
 
 While there are good reasons to not directly expose every property, users may still need more advanced configuration options.
 To address this Spring Security introduces the concept of an `ObjectPostProcessor` which can be used to modify or replace many of the Object instances created by the Java Configuration.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/kotlin-configuration/index.adoc b/docs/modules/ROOT/pages/servlet/configuration/kotlin.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/kotlin-configuration/index.adoc
rename to docs/modules/ROOT/pages/servlet/configuration/kotlin.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/namespace/index.adoc b/docs/modules/ROOT/pages/servlet/configuration/xml-namespace.adoc
similarity index 94%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/namespace/index.adoc
rename to docs/modules/ROOT/pages/servlet/configuration/xml-namespace.adoc
index f0d98efc6c..0168114c1b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/namespace/index.adoc
+++ b/docs/modules/ROOT/pages/servlet/configuration/xml-namespace.adoc
@@ -18,7 +18,7 @@ For example, adding the following element from the security namespace to an appl
 
 This is much simpler than wiring up the equivalent Apache Directory Server beans.
 The most common alternative configuration requirements are supported by attributes on the `ldap-server` element and the user is isolated from worrying about which beans they need to create and what the bean property names are.
-footnote:[You can find out more about the use of the `ldap-server` element in the chapter on pass:specialcharacters,macros[<<servlet-authentication-ldap>>].].
+footnote:[You can find out more about the use of the `ldap-server` element in the chapter on pass:specialcharacters,macros[xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[LDAP Authentication]].].
 Use of a good XML editor while editing the application context file should provide information on the attributes and elements that are available.
 We would recommend that you try out the https://spring.io/tools[Eclipse IDE with Spring Tools] as it has special features for working with standard Spring namespaces.
 
@@ -126,7 +126,7 @@ All you need to enable web security to begin with is
 
 Which says that we want all URLs within our application to be secured, requiring the role `ROLE_USER` to access them, we want to log in to the application using a form with username and password, and that we want a logout URL registered which will allow us to log out of the application.
 `<http>` element is the parent for all web-related namespace functionality.
-The `<intercept-url>` element defines a `pattern` which is matched against the URLs of incoming requests using an ant path style syntax footnote:[See the section on pass:specialcharacters,macros[<<servlet-httpfirewall,`HttpFirewall`>>] for more details on how matches are actually performed.].
+The `<intercept-url>` element defines a `pattern` which is matched against the URLs of incoming requests using an ant path style syntax footnote:[See the section on pass:specialcharacters,macros[xref:servlet/exploits/firewall.adoc#servlet-httpfirewall[`HttpFirewall`]] for more details on how matches are actually performed.].
 You can also use regular-expression matching as an alternative (see the namespace appendix for more details).
 The `access` attribute defines the access requirements for requests matching the given pattern.
 With the default configuration, this is typically a comma-separated list of roles, one of which a user must have to be allowed to make the request.
@@ -134,7 +134,7 @@ The prefix "ROLE_" is a marker which indicates that a simple comparison with the
 In other words, a normal role-based check should be used.
 Access-control in Spring Security is not limited to the use of simple roles (hence the use of the prefix to differentiate between different types of security attributes).
 We'll see later how the interpretation can vary footnote:[The interpretation of the comma-separated values in the `access` attribute depends on the implementation of the <<ns-access-manager,AccessDecisionManager>> which is used.].
-In Spring Security 3.0, the attribute can also be populated with an <<el-access,EL expression>>.
+In Spring Security 3.0, the attribute can also be populated with an xref:servlet/authorization/expression-based.adoc#el-access[EL expression].
 
 
 [NOTE]
@@ -192,13 +192,13 @@ Common problems like incorrect filter ordering are no longer an issue as the fil
 
 The `<authentication-provider>` element creates a `DaoAuthenticationProvider` bean and the `<user-service>` element creates an `InMemoryDaoImpl`.
 All `authentication-provider` elements must be children of the `<authentication-manager>` element, which creates a `ProviderManager` and registers the authentication providers with it.
-You can find more detailed information on the beans that are created in the <<appendix-namespace,namespace appendix>>.
+You can find more detailed information on the beans that are created in the xref:servlet/appendix/namespace.adoc#appendix-namespace[namespace appendix].
 It's worth cross-checking this if you want to start understanding what the important classes in the framework are and how they are used, particularly if you want to customise things later.
 ****
 
 The configuration above defines two users, their passwords and their roles within the application (which will be used for access control).
 It is also possible to load user information from a standard properties file using the `properties` attribute on `user-service`.
-See the section on <<servlet-authentication-inmemory,in-memory authentication>> for more details on the file format.
+See the section on xref:servlet/authentication/passwords/in-memory.adoc#servlet-authentication-inmemory[in-memory authentication] for more details on the file format.
 Using the `<authentication-provider>` element means that the user information will be used by the authentication manager to process authentication requests.
 You can have multiple `<authentication-provider>` elements to define different authentication sources and each will be consulted in turn.
 
@@ -353,7 +353,7 @@ Remove any elements which create filters whose functionality you want to replace
 
 Note that you can't replace filters which are created by the use of the `<http>` element itself - `SecurityContextPersistenceFilter`, `ExceptionTranslationFilter` or `FilterSecurityInterceptor`.
 Some other filters are added by default, but you can disable them.
-An `AnonymousAuthenticationFilter` is added by default and unless you have <<ns-session-fixation,session-fixation protection>> disabled, a `SessionManagementFilter` will also be added to the filter chain.
+An `AnonymousAuthenticationFilter` is added by default and unless you have xref:servlet/authentication/session-management.adoc#ns-session-fixation[session-fixation protection] disabled, a `SessionManagementFilter` will also be added to the filter chain.
 
 ====
 
@@ -365,7 +365,7 @@ If you're replacing a namespace filter which requires an authentication entry po
 == Method Security
 From version 2.0 onwards Spring Security has improved support substantially for adding security to your service layer methods.
 It provides support for JSR-250 annotation security as well as the framework's original `@Secured` annotation.
-From 3.0 you can also make use of new <<el-access,expression-based annotations>>.
+From 3.0 you can also make use of new xref:servlet/authorization/expression-based.adoc#el-access[expression-based annotations].
 You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts.
 
 [[ns-access-manager]]
@@ -376,7 +376,7 @@ If you don't you can skip it and come back to it later, as this section is only
 When you use a namespace configuration, a default instance of `AccessDecisionManager` is automatically registered for you and will be used for making access decisions for method invocations and web URL access, based on the access attributes you specify in your `intercept-url` and `protect-pointcut` declarations (and in annotations if you are using annotation secured methods).
 
 The default strategy is to use an `AffirmativeBased` `AccessDecisionManager` with a `RoleVoter` and an `AuthenticatedVoter`.
-You can find out more about these in the chapter on <<authz-arch,authorization>>.
+You can find out more about these in the chapter on xref:servlet/authorization/architecture.adoc#authz-arch[authorization].
 
 
 [[ns-custom-access-mgr]]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/csrf.adoc b/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc
similarity index 88%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/exploits/csrf.adoc
rename to docs/modules/ROOT/pages/servlet/exploits/csrf.adoc
index 117de637a2..fc2d490735 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/csrf.adoc
+++ b/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc
@@ -1,7 +1,7 @@
 [[servlet-csrf]]
 = Cross Site Request Forgery (CSRF) for Servlet Environments
 
-This section discusses Spring Security's <<csrf,Cross Site Request Forgery (CSRF)>> support for servlet environments.
+This section discusses Spring Security's xref:features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] support for servlet environments.
 
 [[servlet-csrf-using]]
 == Using Spring Security CSRF Protection
@@ -14,7 +14,7 @@ The steps to using Spring Security's CSRF protection are outlined below:
 [[servlet-csrf-idempotent]]
 === Use proper HTTP verbs
 The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs.
-This is covered in detail in <<csrf-protection-idempotent,Safe Methods Must be Idempotent>>.
+This is covered in detail in xref:features/exploits/csrf.adoc#csrf-protection-idempotent[Safe Methods Must be Idempotent].
 
 [[servlet-csrf-configure]]
 === Configure CSRF Protection
@@ -105,7 +105,7 @@ If you do not need the ability to read the cookie with JavaScript directly, it i
 [[servlet-csrf-configure-disable]]
 ==== Disable CSRF Protection
 CSRF protection is enabled by default.
-However, it is simple to disable CSRF protection if it <<csrf-when,makes sense for your application>>.
+However, it is simple to disable CSRF protection if it xref:features/exploits/csrf.adoc#csrf-when[makes sense for your application].
 
 The XML configuration below will disable CSRF protection.
 
@@ -162,7 +162,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-csrf-include]]
 === Include the CSRF Token
 
-In order for the <<csrf-protection-stp,synchronizer token pattern>> to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request.
+In order for the xref:features/exploits/csrf.adoc#csrf-protection-stp[synchronizer token pattern] to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request.
 This must be included in a part of the request (i.e. form parameter, HTTP header, etc) that is not automatically included in the HTTP request by the browser.
 
 Spring Security's https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfFilter.html[CsrfFilter] exposes a https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfToken.html[CsrfToken] as an `HttpServletRequest` attribute named `_csrf`.
@@ -196,7 +196,7 @@ This means that if you leverage https://docs.spring.io/spring/docs/current/sprin
 ===== csrfInput Tag
 
 If you are using JSPs, then you can use https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-view-jsp-formtaglib[Spring’s form tag library].
-However, if that is not an option, you can also easily include the token with the <<taglibs-csrfinput,csrfInput>> tag.
+However, if that is not an option, you can also easily include the token with the xref:servlet/integrations/jsp-taglibs.adoc#taglibs-csrfinput[csrfInput] tag.
 
 [[servlet-csrf-include-form-attr]]
 ===== CsrfToken Request Attribute
@@ -274,7 +274,7 @@ $(function () {
 [[servlet-csrf-include-ajax-meta-tag]]
 ====== csrfMeta tag
 
-If you are using JSPs a simple way to write the CSRF token to the `meta` tags is by leveraging the <<taglibs-csrfmeta,csrfMeta>> tag.
+If you are using JSPs a simple way to write the CSRF token to the `meta` tags is by leveraging the xref:servlet/integrations/jsp-taglibs.adoc#taglibs-csrfmeta[csrfMeta] tag.
 
 [[servlet-csrf-include-ajax-meta-attr]]
 ====== CsrfToken Request Attribute
@@ -301,19 +301,19 @@ An example of doing this with a JSP is shown below:
 == CSRF Considerations
 There are a few special considerations to consider when implementing protection against CSRF attacks.
 This section discusses those considerations as it pertains to servlet environments.
-Refer to <<csrf-considerations>> for a more general discussion.
+Refer to xref:features/exploits/csrf.adoc#csrf-considerations[CSRF Considerations] for a more general discussion.
 
 
 [[servlet-considerations-csrf-login]]
 === Logging In
 
-It is important to <<csrf-considerations-login,require CSRF for log in>> requests to protect against forging log in attempts.
+It is important to xref:features/exploits/csrf.adoc#csrf-considerations-login[require CSRF for log in] requests to protect against forging log in attempts.
 Spring Security's servlet support does this out of the box.
 
 [[servlet-considerations-csrf-logout]]
 === Logging Out
 
-It is important to <<csrf-considerations-logout,require CSRF for log out>> requests to protect against forging log out attempts.
+It is important to xref:features/exploits/csrf.adoc#csrf-considerations-logout[require CSRF for log out] requests to protect against forging log out attempts.
 If CSRF protection is enabled (default), Spring Security's `LogoutFilter` to only process HTTP POST.
 This ensures that log out requires a CSRF token and that a malicious user cannot forcibly log out your users.
 
@@ -367,7 +367,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 By default Spring Security stores the CSRF token in the `HttpSession`.
 This can lead to a situation where the session expires which means there is not an expected CSRF token to validate against.
 
-We've already discussed <<csrf-considerations-login,general solutions>> to session timeouts.
+We've already discussed xref:features/exploits/csrf.adoc#csrf-considerations-login[general solutions] to session timeouts.
 This section discusses the specifics of CSRF timeouts as it pertains to the servlet support.
 
 It is simple to change storage of the expected CSRF token to be in a cookie.
@@ -375,13 +375,13 @@ For details, refer to the <<servlet-csrf-configure-custom-repository>> section.
 
 If a token does expire, you might want to customize how it is handled by specifying a custom `AccessDeniedHandler`.
 The custom `AccessDeniedHandler` can process the `InvalidCsrfTokenException` any way you like.
-For an example of how to customize the `AccessDeniedHandler` refer to the provided links for both <<nsa-access-denied-handler,xml>> and {gh-url}/config/src/test/java/org/springframework/security/config/annotation/web/configurers/NamespaceHttpServerAccessDeniedHandlerTests.java#L64[Java configuration].
+For an example of how to customize the `AccessDeniedHandler` refer to the provided links for both xref:servlet/appendix/namespace.adoc#nsa-access-denied-handler[xml] and {gh-url}/config/src/test/java/org/springframework/security/config/annotation/web/configurers/NamespaceHttpServerAccessDeniedHandlerTests.java#L64[Java configuration].
 // FIXME: We should add a custom AccessDeniedHandler section in the reference and update the links above
 
 
 [[servlet-csrf-considerations-multipart]]
 === Multipart (file upload)
-We have <<csrf-considerations-multipart,already discussed>> how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem.
 This section discusses how to implement placing the CSRF token in the <<servlet-csrf-considerations-multipart-body,body>> and <<servlet-csrf-considerations-multipart-url,url>> within a servlet application.
 
 [NOTE]
@@ -392,7 +392,7 @@ More information about using multipart forms with Spring can be found within the
 [[servlet-csrf-considerations-multipart-body]]
 ==== Place CSRF Token in the Body
 
-We have <<csrf-considerations-multipart-body,already discussed>> the tradeoffs of placing the CSRF token in the body.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart-body[already discussed] the tradeoffs of placing the CSRF token in the body.
 In this section we will discuss how to configure Spring Security to read the CSRF from the body.
 
 In order to read the CSRF token from the body, the `MultipartFilter` is specified before the Spring Security filter.
@@ -473,7 +473,7 @@ An example with a jsp is shown below
 
 [[servlet-csrf-considerations-override-method]]
 === HiddenHttpMethodFilter
-We have <<csrf-considerations-multipart-body,already discussed>> the trade-offs of placing the CSRF token in the body.
+We have xref:features/exploits/csrf.adoc#csrf-considerations-multipart-body[already discussed] the trade-offs of placing the CSRF token in the body.
 
 In Spring's Servlet support, overriding the HTTP method is done using https://docs.spring.io/spring-framework/docs/5.2.x/javadoc-api/org/springframework/web/filter/reactive/HiddenHttpMethodFilter.html[HiddenHttpMethodFilter].
 More information can be found in https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/web.html#mvc-rest-method-conversion[HTTP Method Conversion] section of the reference documentation.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/firewall.adoc b/docs/modules/ROOT/pages/servlet/exploits/firewall.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/exploits/firewall.adoc
rename to docs/modules/ROOT/pages/servlet/exploits/firewall.adoc
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/headers.adoc b/docs/modules/ROOT/pages/servlet/exploits/headers.adoc
similarity index 93%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/exploits/headers.adoc
rename to docs/modules/ROOT/pages/servlet/exploits/headers.adoc
index e45c5c96c9..535f3e976b 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/headers.adoc
+++ b/docs/modules/ROOT/pages/servlet/exploits/headers.adoc
@@ -1,13 +1,13 @@
 [[servlet-headers]]
 = Security HTTP Response Headers
 
-<<headers,Security HTTP Response Headers>> can be used to increase the security of web applications.
+xref:features/exploits/headers.adoc#headers[Security HTTP Response Headers] can be used to increase the security of web applications.
 This section is dedicated to servlet based support for Security HTTP Response Headers.
 
 [[servlet-headers-default]]
 == Default Security Headers
 
-Spring Security provides a <<headers-default,default set of Security HTTP Response Headers>> to provide secure defaults.
+Spring Security provides a xref:features/exploits/headers.adoc#headers-default[default set of Security HTTP Response Headers] to provide secure defaults.
 While each of these headers are considered best practice, it should be noted that not all clients utilize the headers, so additional testing is encouraged.
 
 You can customize specific headers.
@@ -71,7 +71,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 If you do not want the defaults to be added and want explicit control over what should be used, you can disable the defaults.
 An example is provided below:
 
-If you are using Spring Security's Configuration the following will only add <<headers-cache-control,Cache Control>>.
+If you are using Spring Security's Configuration the following will only add xref:features/exploits/headers.adoc#headers-cache-control[Cache Control].
 
 .Customize Cache Control Headers
 ====
@@ -177,7 +177,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-cache-control]]
 == Cache Control
 
-Spring Security includes <<headers-cache-control,Cache Control>> headers by default.
+Spring Security includes xref:features/exploits/headers.adoc#headers-cache-control[Cache Control] headers by default.
 
 However, if you actually want to cache specific responses, your application can selectively invoke https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletResponse.html#setHeader(java.lang.String,java.lang.String)[HttpServletResponse.setHeader(String,String)] to override the header set by Spring Security.
 This is useful to ensure things like CSS, JavaScript, and images are properly cached.
@@ -242,7 +242,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-content-type-options]]
 == Content Type Options
 
-Spring Security includes <<headers-content-type-options,Content-Type>> headers by default.
+Spring Security includes xref:features/exploits/headers.adoc#headers-content-type-options[Content-Type] headers by default.
 However, you can disable it with:
 
 .Content Type Options Disabled
@@ -300,7 +300,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-hsts]]
 == HTTP Strict Transport Security (HSTS)
 
-Spring Security provides the <<headers-hsts,Strict Transport Security>> header by default.
+Spring Security provides the xref:features/exploits/headers.adoc#headers-hsts[Strict Transport Security] header by default.
 However, you can customize the results explicitly.
 For example, the following is an example of explicitly providing HSTS:
 
@@ -366,7 +366,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 
 [[servlet-headers-hpkp]]
 == HTTP Public Key Pinning (HPKP)
-For passivity reasons, Spring Security provides servlet support for <<headers-hpkp,HTTP Public Key Pinning>> but it is <<headers-hpkp-deprecated,no longer recommended>>.
+For passivity reasons, Spring Security provides servlet support for xref:features/exploits/headers.adoc#headers-hpkp[HTTP Public Key Pinning] but it is xref:features/exploits/headers.adoc#headers-hpkp-deprecated[no longer recommended].
 
 You can enable HPKP headers with the following Configuration:
 
@@ -437,7 +437,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-frame-options]]
 == X-Frame-Options
 
-By default, Spring Security disables rendering within an iframe using <<headers-frame-options,X-Frame-Options>>.
+By default, Spring Security disables rendering within an iframe using xref:features/exploits/headers.adoc#headers-frame-options[X-Frame-Options].
 
 You can customize frame options to use the same origin within a Configuration using the following:
 
@@ -560,7 +560,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-csp]]
 == Content Security Policy (CSP)
 
-Spring Security does not add <<headers-csp,Content Security Policy>> by default, because a reasonable default is impossible to know without context of the application.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-csp[Content Security Policy] by default, because a reasonable default is impossible to know without context of the application.
 The web application author must declare the security policy(s) to enforce and/or monitor for the protected resources.
 
 For example, given the following security policy:
@@ -693,7 +693,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-referrer]]
 == Referrer Policy
 
-Spring Security does not add <<headers-referrer,Referrer Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-referrer[Referrer Policy] headers by default.
 You can enable the Referrer Policy header using the configuration as shown below:
 
 .Referrer Policy
@@ -753,7 +753,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-feature]]
 == Feature Policy
 
-Spring Security does not add <<headers-feature,Feature Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-feature[Feature Policy] headers by default.
 The following `Feature-Policy` header:
 
 .Feature-Policy Example
@@ -819,7 +819,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-permissions]]
 == Permissions Policy
 
-Spring Security does not add <<headers-permissions,Permissions Policy>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-permissions[Permissions Policy] headers by default.
 The following `Permissions-Policy` header:
 
 .Permissions-Policy Example
@@ -889,7 +889,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() {
 [[servlet-headers-clear-site-data]]
 == Clear Site Data
 
-Spring Security does not add <<headers-clear-site-data,Clear-Site-Data>> headers by default.
+Spring Security does not add xref:features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default.
 The following Clear-Site-Data header:
 
 .Clear-Site-Data Example
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc b/docs/modules/ROOT/pages/servlet/exploits/http.adoc
similarity index 80%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc
rename to docs/modules/ROOT/pages/servlet/exploits/http.adoc
index f9d8c3275b..3dc10d8ac7 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc
+++ b/docs/modules/ROOT/pages/servlet/exploits/http.adoc
@@ -1,7 +1,7 @@
 [[servlet-http]]
 = HTTP
 
-All HTTP based communication should be protected <<http,using TLS>>.
+All HTTP based communication should be protected xref:features/exploits/http.adoc#http[using TLS].
 
 Below you can find details around Servlet specific features that assist with HTTPS usage.
 
@@ -69,9 +69,9 @@ The following XML configuration will redirect all HTTP requests to HTTPS
 [[servlet-hsts]]
 == Strict Transport Security
 
-Spring Security provides support for <<servlet-headers-hsts,Strict Transport Security>> and enables it by default.
+Spring Security provides support for xref:servlet/exploits/headers.adoc#servlet-headers-hsts[Strict Transport Security] and enables it by default.
 
 [[servlet-http-proxy-server]]
 == Proxy Server Configuration
 
-Spring Security <<http-proxy-server,integrates with proxy servers>>.
+Spring Security xref:features/exploits/http.adoc#http-proxy-server[integrates with proxy servers].
diff --git a/docs/modules/ROOT/pages/servlet/exploits/index.adoc b/docs/modules/ROOT/pages/servlet/exploits/index.adoc
new file mode 100644
index 0000000000..71c3a5eeb9
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/exploits/index.adoc
@@ -0,0 +1,9 @@
+[[servlet-exploits]]
+= Protection Against Exploits
+
+This section discusses Servlet specific support for xref:features/exploits/index.adoc#exploits[Spring Security's protection against common exploits].
+
+* xref:servlet/exploits/csrf.adoc[]
+* xref:servlet/exploits/headers.adoc[]
+* xref:servlet/exploits/http.adoc[]
+* xref:servlet/exploits/firewall.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc b/docs/modules/ROOT/pages/servlet/getting-started.adoc
similarity index 91%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc
rename to docs/modules/ROOT/pages/servlet/getting-started.adoc
index 21d8497ad7..adf4aa555f 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/hello/index.adoc
+++ b/docs/modules/ROOT/pages/servlet/getting-started.adoc
@@ -12,7 +12,7 @@ For your convenience, you can download a minimal Spring Boot + Spring Security a
 [[servlet-hello-dependencies]]
 == Updating Dependencies
 
-The only step you need to do is update the dependencies by using <<getting-maven-boot,Maven>> or <<getting-gradle-boot,Gradle>>.
+The only step you need to do is update the dependencies by using xref:getting-spring-security.adoc#getting-maven-boot[Maven] or xref:getting-spring-security.adoc#getting-gradle-boot[Gradle].
 
 [[servlet-hello-starting]]
 == Starting Hello Spring Security Boot
@@ -67,8 +67,8 @@ A summary of the features follows:
 ** X-Frame-Options integration to help prevent https://en.wikipedia.org/wiki/Clickjacking[Clickjacking]
 * Integrate with the following Servlet API methods:
 ** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[`HttpServletRequest#getRemoteUser()`]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest#getUserPrincipal()`]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest#isUserInRole(java.lang.String)`]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest#login(java.lang.String, java.lang.String)`]
-** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest#logout()`]
+** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[`HttpServletRequest.html#getUserPrincipal()`]
+** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[`HttpServletRequest.html#isUserInRole(java.lang.String)`]
+** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login(java.lang.String,%20java.lang.String)[`HttpServletRequest.html#login(java.lang.String, java.lang.String)`]
+** https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout()[`HttpServletRequest.html#logout()`]
 
diff --git a/docs/modules/ROOT/pages/servlet/index.adoc b/docs/modules/ROOT/pages/servlet/index.adoc
new file mode 100644
index 0000000000..5c8f216973
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/index.adoc
@@ -0,0 +1,4 @@
+[[servlet-applications]]
+= Servlet Applications
+
+Spring Security integrates with the Servlet Container by using a standard Servlet `Filter`. This means it works with any application that runs in a Servlet Container. More concretely, you do not need to use Spring in your Servlet-based application to take advantage of Spring Security.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/cors.adoc b/docs/modules/ROOT/pages/servlet/integrations/cors.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/cors.adoc
rename to docs/modules/ROOT/pages/servlet/integrations/cors.adoc
index cf9eae9629..aa5cb3ff17 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/cors.adoc
+++ b/docs/modules/ROOT/pages/servlet/integrations/cors.adoc
@@ -1,5 +1,5 @@
 [[cors]]
-== CORS
+= CORS
 
 Spring Framework provides https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-cors[first class support for CORS].
 CORS must be processed before Spring Security because the pre-flight request will not contain any cookies (i.e. the `JSESSIONID`).
diff --git a/docs/modules/ROOT/pages/servlet/integrations/index.adoc b/docs/modules/ROOT/pages/servlet/integrations/index.adoc
new file mode 100644
index 0000000000..0e549ff221
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/integrations/index.adoc
@@ -0,0 +1,10 @@
+= Integrations
+
+Spring Security integrates with numerous frameworks and APIs.
+In this section, we discuss Spring Security integration with:
+
+* xref:servlet/integrations/servlet-api.adoc[Servlet APIs]
+* xref:servlet/integrations/mvc.adoc[Spring MVC]
+* xref:servlet/integrations/websocket.adoc[WebSocket]
+* xref:servlet/integrations/cors.adoc[Spring's CORS Support]
+* xref:servlet/integrations/jsp-taglibs.adoc[JSP Taglib]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jsp-taglibs.adoc b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jsp-taglibs.adoc
rename to docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc
index 3f31683258..05bd1ea02c 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/jsp-taglibs.adoc
+++ b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc
@@ -1,9 +1,9 @@
 [[taglibs]]
-== JSP Tag Libraries
+= JSP Tag Libraries
 Spring Security has its own taglib which provides basic support for accessing security information and applying security constraints in JSPs.
 
 
-=== Declaring the Taglib
+== Declaring the Taglib
 To use any of the tags, you must have the security taglib declared in your JSP:
 
 [source,xml]
@@ -12,12 +12,12 @@ To use any of the tags, you must have the security taglib declared in your JSP:
 ----
 
 [[taglibs-authorize]]
-=== The authorize Tag
+== The authorize Tag
 This tag is used to determine whether its contents should be evaluated or not.
 In Spring Security 3.0, it can be used in two ways footnote:[
 The legacy options from Spring Security 2.0 are also supported, but discouraged.
 ].
-The first approach uses a <<el-access-web,web-security expression>>, specified in the `access` attribute of the tag.
+The first approach uses a xref:servlet/authorization/expression-based.adoc#el-access-web[web-security expression], specified in the `access` attribute of the tag.
 The expression evaluation will be delegated to the `SecurityExpressionHandler<FilterInvocation>` defined in the application context (you should have web expressions enabled in your `<http>` namespace configuration to make sure this service is available).
 So, for example, you might have
 
@@ -65,7 +65,7 @@ This approach can also be combined with a `method` attribute, supplying the HTTP
 The Boolean result of evaluating the tag (whether it grants or denies access) can be stored in a page context scope variable by setting the `var` attribute to the variable name, avoiding the need for duplicating and re-evaluating the condition at other points in the page.
 
 
-==== Disabling Tag Authorization for Testing
+=== Disabling Tag Authorization for Testing
 Hiding a link in a page for unauthorized users doesn't prevent them from accessing the URL.
 They could just type it into their browser directly, for example.
 As part of your testing process, you may want to reveal the hidden areas in order to check that links really are secured at the back end.
@@ -77,7 +77,7 @@ Try running the "tutorial" sample application with this property enabled, for ex
 You can also set the properties `spring.security.securedUIPrefix` and `spring.security.securedUISuffix` if you want to change surrounding text from the default `span` tags (or use empty strings to remove it completely).
 
 
-=== The authentication Tag
+== The authentication Tag
 This tag allows access to the current `Authentication` object stored in the security context.
 It renders a property of the object directly in the JSP.
 So, for example, if the `principal` property of the `Authentication` is an instance of Spring Security's `UserDetails` object, then using `<sec:authentication property="principal.username" />` will render the name of the current user.
@@ -86,7 +86,7 @@ Of course, it isn't necessary to use JSP tags for this kind of thing and some pe
 You can access the `Authentication` object in your MVC controller (by calling `SecurityContextHolder.getContext().getAuthentication()`) and add the data directly to your model for rendering by the view.
 
 
-=== The accesscontrollist Tag
+== The accesscontrollist Tag
 This tag is only valid when used with Spring Security's ACL module.
 It checks a comma-separated list of required permissions for a specified domain object.
 If the current user has all of those permissions, then the tag body will be evaluated.
@@ -113,7 +113,7 @@ The `Acl` will be invoked with the required permissions to check if all of them
 This tag also supports the `var` attribute, in the same way as the `authorize` tag.
 
 [[taglibs-csrfinput]]
-=== The csrfInput Tag
+== The csrfInput Tag
 If CSRF protection is enabled, this tag inserts a hidden form field with the correct name and value for the CSRF protection token.
 If CSRF protection is not enabled, this tag outputs nothing.
 
@@ -134,7 +134,7 @@ Spring Security handles Spring forms automatically.
 ----
 
 [[taglibs-csrfmeta]]
-=== The csrfMetaTags Tag
+== The csrfMetaTags Tag
 If CSRF protection is enabled, this tag inserts meta tags containing the CSRF protection token form field and header names and CSRF protection token value.
 These meta tags are useful for employing CSRF protection within JavaScript in your applications.
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/mvc.adoc b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc
similarity index 95%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/mvc.adoc
rename to docs/modules/ROOT/pages/servlet/integrations/mvc.adoc
index 796be873fd..23bb16ccac 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/mvc.adoc
+++ b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc
@@ -1,11 +1,11 @@
 [[mvc]]
-== Spring MVC Integration
+= Spring MVC Integration
 
 Spring Security provides a number of optional integrations with Spring MVC.
 This section covers the integration in further detail.
 
 [[mvc-enablewebmvcsecurity]]
-=== @EnableWebMvcSecurity
+== @EnableWebMvcSecurity
 
 NOTE: As of Spring Security 4.0, `@EnableWebMvcSecurity` is deprecated.
 The replacement is `@EnableWebSecurity` which will determine adding the Spring MVC features based upon the classpath.
@@ -16,7 +16,7 @@ NOTE: Spring Security provides the configuration using Spring MVC's https://docs
 This means that if you are using more advanced options, like integrating with `WebMvcConfigurationSupport` directly, then you will need to manually provide the Spring Security configuration.
 
 [[mvc-requestmatcher]]
-=== MvcRequestMatcher
+== MvcRequestMatcher
 
 Spring Security provides deep integration with how Spring MVC matches on URLs with `MvcRequestMatcher`.
 This is helpful to ensure your Security rules match the logic used to handle your requests.
@@ -212,7 +212,7 @@ or in XML
 ----
 
 [[mvc-authentication-principal]]
-=== @AuthenticationPrincipal
+== @AuthenticationPrincipal
 
 Spring Security provides `AuthenticationPrincipalArgumentResolver` which can automatically resolve the current `Authentication.getPrincipal()` for Spring MVC arguments.
 By using `@EnableWebSecurity` you will automatically have this added to your Spring MVC configuration.
@@ -448,7 +448,7 @@ open fun findMessagesForUser(@CurrentUser customUser: CustomUser?): ModelAndView
 
 
 [[mvc-async]]
-=== Spring MVC Async Integration
+== Spring MVC Async Integration
 
 Spring Web MVC 3.2+ has excellent support for https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/mvc.html#mvc-ann-async[Asynchronous Request Processing].
 With no additional configuration, Spring Security will automatically setup the `SecurityContext` to the `Thread` that invokes a `Callable` returned by your controllers.
@@ -492,14 +492,14 @@ The `SecurityContext` that is used to process the `Callable` is the `SecurityCon
 
 There is no automatic integration with a `DeferredResult` that is returned by controllers.
 This is because `DeferredResult` is processed by the users and thus there is no way of automatically integrating with it.
-However, you can still use <<concurrency,Concurrency Support>> to provide transparent integration with Spring Security.
+However, you can still use xref:features/integrations/concurrency.adoc#concurrency[Concurrency Support] to provide transparent integration with Spring Security.
 
 [[mvc-csrf]]
-=== Spring MVC and CSRF Integration
+== Spring MVC and CSRF Integration
 
-==== Automatic Token Inclusion
+=== Automatic Token Inclusion
 
-Spring Security will automatically <<servlet-csrf-include,include the CSRF Token>> within forms that use the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/view.html#view-jsp-formtaglib-formtag[Spring MVC form tag].
+Spring Security will automatically xref:servlet/exploits/csrf.adoc#servlet-csrf-include[include the CSRF Token] within forms that use the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/view.html#view-jsp-formtaglib-formtag[Spring MVC form tag].
 For example, the following JSP:
 
 [source,xml]
@@ -541,10 +541,10 @@ Will output HTML that is similar to the following:
 ----
 
 [[mvc-csrf-resolver]]
-==== Resolving the CsrfToken
+=== Resolving the CsrfToken
 
 Spring Security provides `CsrfTokenArgumentResolver` which can automatically resolve the current `CsrfToken` for Spring MVC arguments.
-By using <<jc-hello-wsca,@EnableWebSecurity>> you will automatically have this added to your Spring MVC configuration.
+By using xref:servlet/configuration/java.adoc#jc-hello-wsca[@EnableWebSecurity] you will automatically have this added to your Spring MVC configuration.
 If you use XML based configuration, you must add this yourself.
 
 Once `CsrfTokenArgumentResolver` is properly configured, you can expose the `CsrfToken` to your static HTML based application.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/servlet-api.adoc b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc
similarity index 94%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/servlet-api.adoc
rename to docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc
index ad76aa54a0..741a0629f7 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/servlet-api.adoc
+++ b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc
@@ -1,14 +1,14 @@
 [[servletapi]]
-== Servlet API integration
+= Servlet API integration
 This section describes how Spring Security is integrated with the Servlet API.
 
 
 [[servletapi-25]]
-=== Servlet 2.5+ Integration
+== Servlet 2.5+ Integration
 
 
 [[servletapi-remote-user]]
-==== HttpServletRequest.getRemoteUser()
+=== HttpServletRequest.getRemoteUser()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest.getRemoteUser()] will return the result of `SecurityContextHolder.getContext().getAuthentication().getName()` which is typically the current username.
 This can be useful if you want to display the current username in your application.
 Additionally, checking if this is null can be used to indicate if a user has authenticated or is anonymous.
@@ -16,7 +16,7 @@ Knowing if the user is authenticated or not can be useful for determining if cer
 
 
 [[servletapi-user-principal]]
-==== HttpServletRequest.getUserPrincipal()
+=== HttpServletRequest.getUserPrincipal()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.getUserPrincipal()] will return the result of `SecurityContextHolder.getContext().getAuthentication()`.
 This means it is an `Authentication` which is typically an instance of `UsernamePasswordAuthenticationToken` when using username and password based authentication.
 This can be useful if you need additional information about your user.
@@ -55,7 +55,7 @@ Instead, one should centralize it to reduce any coupling of Spring Security and
 ====
 
 [[servletapi-user-in-role]]
-==== HttpServletRequest.isUserInRole(String)
+=== HttpServletRequest.isUserInRole(String)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.isUserInRole(String)] will determine if `SecurityContextHolder.getContext().getAuthentication().getAuthorities()` contains a `GrantedAuthority` with the role passed into `isUserInRole(String)`.
 Typically users should not pass in the "ROLE_" prefix into this method since it is added automatically.
 For example, if you want to determine if the current user has the authority "ROLE_ADMIN", you could use the following:
@@ -78,18 +78,18 @@ This might be useful to determine if certain UI components should be displayed.
 For example, you might display admin links only if the current user is an admin.
 
 [[servletapi-3]]
-=== Servlet 3+ Integration
+== Servlet 3+ Integration
 The following section describes the Servlet 3 methods that Spring Security integrates with.
 
 
 [[servletapi-authenticate]]
-==== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
+=== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#authenticate%28javax.servlet.http.HttpServletResponse%29[HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)] method can be used to ensure that a user is authenticated.
 If they are not authenticated, the configured AuthenticationEntryPoint will be used to request the user to authenticate (i.e. redirect to the login page).
 
 
 [[servletapi-login]]
-==== HttpServletRequest.login(String,String)
+=== HttpServletRequest.login(String,String)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login%28java.lang.String,%20java.lang.String%29[HttpServletRequest.login(String,String)] method can be used to authenticate the user with the current `AuthenticationManager`.
 For example, the following would attempt to authenticate with the username "user" and password "password":
 
@@ -121,7 +121,7 @@ It is not necessary to catch the ServletException if you want Spring Security to
 ====
 
 [[servletapi-logout]]
-==== HttpServletRequest.logout()
+=== HttpServletRequest.logout()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout%28%29[HttpServletRequest.logout()] method can be used to log the current user out.
 
 Typically this means that the SecurityContextHolder will be cleared out, the HttpSession will be invalidated, any "Remember Me" authentication will be cleaned up, etc.
@@ -130,7 +130,7 @@ It is important to note that after HttpServletRequest.logout() has been invoked,
 Typically this would involve a redirect to the welcome page.
 
 [[servletapi-start-runnable]]
-==== AsyncContext.start(Runnable)
+=== AsyncContext.start(Runnable)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/AsyncContext.html#start%28java.lang.Runnable%29[AsyncContext.start(Runnable)] method that ensures your credentials will be propagated to the new Thread.
 Using Spring Security's concurrency support, Spring Security overrides the AsyncContext.start(Runnable) to ensure that the current SecurityContext is used when processing the Runnable.
 For example, the following would output the current user's Authentication:
@@ -174,7 +174,7 @@ async.start {
 ====
 
 [[servletapi-async]]
-==== Async Servlet Support
+=== Async Servlet Support
 If you are using Java Based configuration, you are ready to go.
 If you are using XML configuration, there are a few updates that are necessary.
 The first step is to ensure you have updated your web.xml to use at least the 3.0 schema as shown below:
@@ -265,9 +265,9 @@ When Spring Security automatically saved the SecurityContext on committing the H
 Since version 3.2, Spring Security is smart enough to no longer automatically save the SecurityContext on committing the HttpServletResponse as soon as HttpServletRequest.startAsync() is invoked.
 
 [[servletapi-31]]
-=== Servlet 3.1+ Integration
+== Servlet 3.1+ Integration
 The following section describes the Servlet 3.1 methods that Spring Security integrates with.
 
 [[servletapi-change-session-id]]
-==== HttpServletRequest#changeSessionId()
-The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against <<ns-session-fixation,Session Fixation>> attacks in Servlet 3.1 and higher.
+=== HttpServletRequest#changeSessionId()
+The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against xref:servlet/authentication/session-management.adoc#ns-session-fixation[Session Fixation] attacks in Servlet 3.1 and higher.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/websocket.adoc b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc
similarity index 92%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/integrations/websocket.adoc
rename to docs/modules/ROOT/pages/servlet/integrations/websocket.adoc
index 43b83c752e..6ae9b57a86 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/integrations/websocket.adoc
+++ b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc
@@ -1,5 +1,5 @@
 [[websocket]]
-== WebSocket Security
+= WebSocket Security
 
 Spring Security 4 added support for securing https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html[Spring's WebSocket support].
 This section describes how to use Spring Security's WebSocket support.
@@ -12,7 +12,7 @@ Additionally, JSR-356 does not provide a way to intercept messages, so security
 ****
 
 [[websocket-configuration]]
-=== WebSocket Configuration
+== WebSocket Configuration
 
 Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction.
 To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`.
@@ -51,7 +51,7 @@ This will ensure that:
 <2> The SecurityContextHolder is populated with the user within the simpUser header attribute for any inbound request.
 <3> Our messages require the proper authorization. Specifically, any inbound message that starts with "/user/" will require ROLE_USER. Additional details on authorization can be found in <<websocket-authorization>>
 
-Spring Security also provides <<nsa-websocket-security,XML Namespace>> support for securing WebSockets.
+Spring Security also provides xref:servlet/appendix/namespace.adoc#nsa-websocket-security[XML Namespace] support for securing WebSockets.
 A comparable XML based configuration looks like the following:
 
 [source,xml]
@@ -69,7 +69,7 @@ This will ensure that:
 <3> Our messages require the proper authorization. Specifically, any inbound message that starts with "/user/" will require ROLE_USER. Additional details on authorization can be found in <<websocket-authorization>>
 
 [[websocket-authentication]]
-=== WebSocket Authentication
+== WebSocket Authentication
 
 WebSockets reuse the same authentication information that is found in the HTTP request when the WebSocket connection was made.
 This means that the `Principal` on the `HttpServletRequest` will be handed off to WebSockets.
@@ -78,7 +78,7 @@ If you are using Spring Security, the `Principal` on the `HttpServletRequest` is
 More concretely, to ensure a user has authenticated to your WebSocket application, all that is necessary is to ensure that you setup Spring Security to authenticate your HTTP based web application.
 
 [[websocket-authorization]]
-=== WebSocket Authorization
+== WebSocket Authorization
 
 Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction.
 To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`.
@@ -132,7 +132,7 @@ This will ensure that:
 <5> Any other message of type MESSAGE or SUBSCRIBE is rejected. Due to 6 we do not need this step, but it illustrates how one can match on specific message types.
 <6> Any other Message is rejected. This is a good idea to ensure that you do not miss any messages.
 
-Spring Security also provides <<nsa-websocket-security,XML Namespace>> support for securing WebSockets.
+Spring Security also provides xref:servlet/appendix/namespace.adoc#nsa-websocket-security[XML Namespace] support for securing WebSockets.
 A comparable XML based configuration looks like the following:
 
 [source,xml]
@@ -168,12 +168,12 @@ This will ensure that:
 <6> Any other message with a destination is rejected. This is a good idea to ensure that you do not miss any messages.
 
 [[websocket-authorization-notes]]
-==== WebSocket Authorization Notes
+=== WebSocket Authorization Notes
 
 In order to properly secure your application it is important to understand Spring's WebSocket support.
 
 [[websocket-authorization-notes-messagetypes]]
-===== WebSocket Authorization on Message Types
+==== WebSocket Authorization on Message Types
 
 It is important to understand the distinction between SUBSCRIBE and MESSAGE types of messages and how it works within Spring.
 
@@ -188,7 +188,7 @@ If we allowed sending a MESSAGE to "/topic/system/notifications", then clients c
 In general, it is common for applications to deny any MESSAGE sent to a destination that starts with the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp[broker prefix] (i.e. "/topic/" or "/queue/").
 
 [[websocket-authorization-notes-destinations]]
-===== WebSocket Authorization on Destinations
+==== WebSocket Authorization on Destinations
 
 It is also is important to understand how destinations are transformed.
 
@@ -206,7 +206,7 @@ In general, it is common for applications to deny any SUBSCRIBE sent to a messag
 Of course we may provide exceptions to account for things like
 
 [[websocket-authorization-notes-outbound]]
-==== Outbound Messages
+=== Outbound Messages
 
 Spring contains a section titled https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp-message-flow[Flow of Messages] that describes how messages flow through the system.
 It is important to note that Spring Security only secures the `clientInboundChannel`.
@@ -217,13 +217,13 @@ For every message that goes in, there are typically many more that go out.
 Instead of securing the outbound messages, we encourage securing the subscription to the endpoints.
 
 [[websocket-sameorigin]]
-=== Enforcing Same Origin Policy
+== Enforcing Same Origin Policy
 
 It is important to emphasize that the browser does not enforce the https://en.wikipedia.org/wiki/Same-origin_policy[Same Origin Policy] for WebSocket connections.
 This is an extremely important consideration.
 
 [[websocket-sameorigin-why]]
-==== Why Same Origin?
+=== Why Same Origin?
 
 Consider the following scenario.
 A user visits bank.com and authenticates to their account.
@@ -238,15 +238,15 @@ Since SockJS tries to emulate WebSockets it also bypasses the Same Origin Policy
 This means developers need to explicitly protect their applications from external domains when using SockJS.
 
 [[websocket-sameorigin-spring]]
-==== Spring WebSocket Allowed Origin
+=== Spring WebSocket Allowed Origin
 
 Fortunately, since Spring 4.1.5 Spring's WebSocket and SockJS support restricts access to the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-server-allowed-origins[current domain].
 Spring Security adds an additional layer of protection to provide https://en.wikipedia.org/wiki/Defense_in_depth_(computing)[defence in depth].
 
 [[websocket-sameorigin-csrf]]
-==== Adding CSRF to Stomp Headers
+=== Adding CSRF to Stomp Headers
 
-By default Spring Security requires the <<csrf,CSRF token>> in any CONNECT message type.
+By default Spring Security requires the xref:features/exploits/csrf.adoc#csrf[CSRF token] in any CONNECT message type.
 This ensures that only a site that has access to the CSRF token can connect.
 Since only the *Same Origin* can access the CSRF token, external domains are not allowed to make a connection.
 
@@ -254,7 +254,7 @@ Typically we need to include the CSRF token in an HTTP header or an HTTP paramet
 However, SockJS does not allow for these options.
 Instead, we must include the token in the Stomp headers
 
-Applications can <<servlet-csrf-include,obtain a CSRF token>> by accessing the request attribute named _csrf.
+Applications can xref:servlet/exploits/csrf.adoc#servlet-csrf-include[obtain a CSRF token] by accessing the request attribute named _csrf.
 For example, the following will allow accessing the `CsrfToken` in a JSP:
 
 [source,javascript]
@@ -310,7 +310,7 @@ stompClient.connect(headers, function(frame) {
 ----
 
 [[websocket-sameorigin-disable]]
-==== Disable CSRF within WebSockets
+=== Disable CSRF within WebSockets
 
 If you want to allow other domains to access your site, you can disable Spring Security's protection.
 For example, in Java Configuration you can use the following:
@@ -348,19 +348,19 @@ open class WebSocketSecurityConfig : AbstractSecurityWebSocketMessageBrokerConfi
 
 
 [[websocket-sockjs]]
-=== Working with SockJS
+== Working with SockJS
 
 https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-fallback[SockJS] provides fallback transports to support older browsers.
 When using the fallback options we need to relax a few security constraints to allow SockJS to work with Spring Security.
 
 [[websocket-sockjs-sameorigin]]
-==== SockJS & frame-options
+=== SockJS & frame-options
 
 SockJS may use an https://github.com/sockjs/sockjs-client/tree/v0.3.4[transport that leverages an iframe].
-By default Spring Security will <<headers-frame-options,deny>> the site from being framed to prevent Clickjacking attacks.
+By default Spring Security will xref:features/exploits/headers.adoc#headers-frame-options[deny] the site from being framed to prevent Clickjacking attacks.
 To allow SockJS frame based transports to work, we need to configure Spring Security to allow the same origin to frame the content.
 
-You can customize X-Frame-Options with the <<nsa-frame-options,frame-options>> element.
+You can customize X-Frame-Options with the xref:servlet/appendix/namespace.adoc#nsa-frame-options[frame-options] element.
 For example, the following will instruct Spring Security to use "X-Frame-Options: SAMEORIGIN" which allows iframes within the same domain:
 
 [source,xml]
@@ -418,7 +418,7 @@ open class WebSecurityConfig : WebSecurityConfigurerAdapter() {
 ====
 
 [[websocket-sockjs-csrf]]
-==== SockJS & Relaxing CSRF
+=== SockJS & Relaxing CSRF
 
 SockJS uses a POST on the CONNECT messages for any HTTP based transport.
 Typically we need to include the CSRF token in an HTTP header or an HTTP parameter.
@@ -486,7 +486,7 @@ open class WebSecurityConfig : WebSecurityConfigurerAdapter() {
 ----
 ====
 
-If we are using XML based configuration, we can use the <<nsa-csrf-request-matcher-ref,csrf@request-matcher-ref>>.
+If we are using XML based configuration, we can use the xref:servlet/appendix/namespace.adoc#nsa-csrf-request-matcher-ref[csrf@request-matcher-ref].
 For example:
 
 [source,xml]
diff --git a/docs/modules/ROOT/pages/servlet/oauth2/index.adoc b/docs/modules/ROOT/pages/servlet/oauth2/index.adoc
new file mode 100644
index 0000000000..df50a690b6
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/oauth2/index.adoc
@@ -0,0 +1,8 @@
+= OAuth2
+
+Spring Security provides comprehensive OAuth 2 support.
+This section discusses how to integrate OAuth 2 into your servlet based application.
+
+* xref:servlet/oauth2/oauth2-login.adoc[]
+* xref:servlet/oauth2/oauth2-client.adoc[]
+* xref:servlet/oauth2/oauth2-resourceserver.adoc[]
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-client.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-client.adoc
rename to docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc
index 9bae570fe7..c02a4a0bc6 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-client.adoc
+++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc
@@ -1,5 +1,5 @@
 [[oauth2client]]
-== OAuth 2.0 Client
+= OAuth 2.0 Client
 
 The OAuth 2.0 Client features provide support for the Client role as defined in the https://tools.ietf.org/html/rfc6749#section-1.1[OAuth 2.0 Authorization Framework].
 
@@ -74,7 +74,7 @@ class OAuth2ClientSecurityConfig : WebSecurityConfigurerAdapter() {
 
 In addition to the `HttpSecurity.oauth2Client()` DSL, XML configuration is also supported.
 
-The following code shows the complete configuration options available in the <<nsa-oauth2-client, security namespace>>:
+The following code shows the complete configuration options available in the xref:servlet/appendix/namespace.adoc#nsa-oauth2-client[ security namespace]:
 
 .OAuth2 Client XML Configuration Options
 ====
@@ -166,11 +166,11 @@ The following sections will go into more detail on the core components used by O
 
 
 [[oauth2Client-core-interface-class]]
-=== Core Interfaces / Classes
+== Core Interfaces / Classes
 
 
 [[oauth2Client-client-registration]]
-==== ClientRegistration
+=== ClientRegistration
 
 `ClientRegistration` is a representation of a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider.
 
@@ -256,7 +256,7 @@ The above code will query in series `https://idp.example.com/issuer/.well-known/
 As an alternative, you can use `ClientRegistrations.fromOidcIssuerLocation()` to only query the OpenID Connect Provider's Configuration endpoint.
 
 [[oauth2Client-client-registration-repo]]
-==== ClientRegistrationRepository
+=== ClientRegistrationRepository
 
 The `ClientRegistrationRepository` serves as a repository for OAuth 2.0 / OpenID Connect 1.0 `ClientRegistration`(s).
 
@@ -318,7 +318,7 @@ class OAuth2ClientController {
 ====
 
 [[oauth2Client-authorized-client]]
-==== OAuth2AuthorizedClient
+=== OAuth2AuthorizedClient
 
 `OAuth2AuthorizedClient` is a representation of an Authorized Client.
 A client is considered to be authorized when the end-user (Resource Owner) has granted authorization to the client to access its protected resources.
@@ -327,7 +327,7 @@ A client is considered to be authorized when the end-user (Resource Owner) has g
 
 
 [[oauth2Client-authorized-repo-service]]
-==== OAuth2AuthorizedClientRepository / OAuth2AuthorizedClientService
+=== OAuth2AuthorizedClientRepository / OAuth2AuthorizedClientService
 
 `OAuth2AuthorizedClientRepository` is responsible for persisting `OAuth2AuthorizedClient`(s) between web requests.
 Whereas, the primary role of `OAuth2AuthorizedClientService` is to manage `OAuth2AuthorizedClient`(s) at the application-level.
@@ -392,11 +392,11 @@ The default implementation of `OAuth2AuthorizedClientService` is `InMemoryOAuth2
 Alternatively, the JDBC implementation `JdbcOAuth2AuthorizedClientService` may be configured for persisting `OAuth2AuthorizedClient`(s) in a database.
 
 [NOTE]
-`JdbcOAuth2AuthorizedClientService` depends on the table definition described in <<dbschema-oauth2-client, OAuth 2.0 Client Schema>>.
+`JdbcOAuth2AuthorizedClientService` depends on the table definition described in xref:servlet/appendix/database-schema.adoc#dbschema-oauth2-client[ OAuth 2.0 Client Schema].
 
 
 [[oauth2Client-authorized-manager-provider]]
-==== OAuth2AuthorizedClientManager / OAuth2AuthorizedClientProvider
+=== OAuth2AuthorizedClientManager / OAuth2AuthorizedClientProvider
 
 The `OAuth2AuthorizedClientManager` is responsible for the overall management of `OAuth2AuthorizedClient`(s).
 
@@ -608,23 +608,23 @@ fun authorizedClientManager(
 
 
 [[oauth2Client-auth-grant-support]]
-=== Authorization Grant Support
+== Authorization Grant Support
 
 
 [[oauth2Client-auth-code-grant]]
-==== Authorization Code
+=== Authorization Code
 
 [NOTE]
 Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.1[Authorization Code] grant.
 
 
-===== Obtaining Authorization
+==== Obtaining Authorization
 
 [NOTE]
 Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.1[Authorization Request/Response] protocol flow for the Authorization Code grant.
 
 
-===== Initiating the Authorization Request
+==== Initiating the Authorization Request
 
 The `OAuth2AuthorizationRequestRedirectFilter` uses an `OAuth2AuthorizationRequestResolver` to resolve an `OAuth2AuthorizationRequest` and initiate the Authorization Code grant flow by redirecting the end-user's user-agent to the Authorization Server's Authorization Endpoint.
 
@@ -702,10 +702,10 @@ spring:
 [NOTE]
 `+{baseUrl}+` resolves to `+{baseScheme}://{baseHost}{basePort}{basePath}+`
 
-Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a <<http-proxy-server,Proxy Server>>.
+Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a xref:features/exploits/http.adoc#http-proxy-server[Proxy Server].
 This ensures that the `X-Forwarded-*` headers are used when expanding the `redirect-uri`.
 
-===== Customizing the Authorization Request
+==== Customizing the Authorization Request
 
 One of the primary use cases an `OAuth2AuthorizationRequestResolver` can realize is the ability to customize the Authorization Request with additional parameters above the standard parameters defined in the OAuth 2.0 Authorization Framework.
 
@@ -852,7 +852,7 @@ private fun authorizationRequestCustomizer(): Consumer<OAuth2AuthorizationReques
 ====
 
 
-===== Storing the Authorization Request
+==== Storing the Authorization Request
 
 The `AuthorizationRequestRepository` is responsible for the persistence of the `OAuth2AuthorizationRequest` from the time the Authorization Request is initiated to the time the Authorization Response is received (the callback).
 
@@ -913,7 +913,7 @@ class OAuth2ClientSecurityConfig : WebSecurityConfigurerAdapter() {
 ----
 ====
 
-===== Requesting an Access Token
+==== Requesting an Access Token
 
 [NOTE]
 Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request/Response] protocol flow for the Authorization Code grant.
@@ -923,7 +923,7 @@ The default implementation of `OAuth2AccessTokenResponseClient` for the Authoriz
 The `DefaultAuthorizationCodeTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
 
 
-===== Customizing the Access Token Request
+==== Customizing the Access Token Request
 
 If you need to customize the pre-processing of the Token Request, you can provide `DefaultAuthorizationCodeTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<OAuth2AuthorizationCodeGrantRequest, RequestEntity<?>>`.
 The default implementation `OAuth2AuthorizationCodeGrantRequestEntityConverter` builds a `RequestEntity` representation of a standard https://tools.ietf.org/html/rfc6749#section-4.1.3[OAuth 2.0 Access Token Request].
@@ -932,7 +932,7 @@ However, providing a custom `Converter`, would allow you to extend the standard
 IMPORTANT: The custom `Converter` must return a valid `RequestEntity` representation of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
 
 
-===== Customizing the Access Token Response
+==== Customizing the Access Token Response
 
 On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultAuthorizationCodeTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
 The default `RestOperations` is configured as follows:
@@ -1021,13 +1021,13 @@ class OAuth2ClientSecurityConfig : WebSecurityConfigurerAdapter() {
 
 
 [[oauth2Client-refresh-token-grant]]
-==== Refresh Token
+=== Refresh Token
 
 [NOTE]
 Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.5[Refresh Token].
 
 
-===== Refreshing an Access Token
+==== Refreshing an Access Token
 
 [NOTE]
 Please refer to the https://tools.ietf.org/html/rfc6749#section-6[Access Token Request/Response] protocol flow for the Refresh Token grant.
@@ -1037,7 +1037,7 @@ The default implementation of `OAuth2AccessTokenResponseClient` for the Refresh
 The `DefaultRefreshTokenTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
 
 
-===== Customizing the Access Token Request
+==== Customizing the Access Token Request
 
 If you need to customize the pre-processing of the Token Request, you can provide `DefaultRefreshTokenTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<OAuth2RefreshTokenGrantRequest, RequestEntity<?>>`.
 The default implementation `OAuth2RefreshTokenGrantRequestEntityConverter` builds a `RequestEntity` representation of a standard https://tools.ietf.org/html/rfc6749#section-6[OAuth 2.0 Access Token Request].
@@ -1046,7 +1046,7 @@ However, providing a custom `Converter`, would allow you to extend the standard
 IMPORTANT: The custom `Converter` must return a valid `RequestEntity` representation of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
 
 
-===== Customizing the Access Token Response
+==== Customizing the Access Token Response
 
 On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultRefreshTokenTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
 The default `RestOperations` is configured as follows:
@@ -1127,13 +1127,13 @@ If the `OAuth2AuthorizedClient.getRefreshToken()` is available and the `OAuth2Au
 
 
 [[oauth2Client-client-creds-grant]]
-==== Client Credentials
+=== Client Credentials
 
 [NOTE]
 Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials] grant.
 
 
-===== Requesting an Access Token
+==== Requesting an Access Token
 
 [NOTE]
 Please refer to the https://tools.ietf.org/html/rfc6749#section-4.4.2[Access Token Request/Response] protocol flow for the Client Credentials grant.
@@ -1143,7 +1143,7 @@ The default implementation of `OAuth2AccessTokenResponseClient` for the Client C
 The `DefaultClientCredentialsTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
 
 
-===== Customizing the Access Token Request
+==== Customizing the Access Token Request
 
 If you need to customize the pre-processing of the Token Request, you can provide `DefaultClientCredentialsTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<OAuth2ClientCredentialsGrantRequest, RequestEntity<?>>`.
 The default implementation `OAuth2ClientCredentialsGrantRequestEntityConverter` builds a `RequestEntity` representation of a standard https://tools.ietf.org/html/rfc6749#section-4.4.2[OAuth 2.0 Access Token Request].
@@ -1152,7 +1152,7 @@ However, providing a custom `Converter`, would allow you to extend the standard
 IMPORTANT: The custom `Converter` must return a valid `RequestEntity` representation of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
 
 
-===== Customizing the Access Token Response
+==== Customizing the Access Token Response
 
 On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultClientCredentialsTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
 The default `RestOperations` is configured as follows:
@@ -1226,7 +1226,7 @@ authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
 `OAuth2AuthorizedClientProviderBuilder.builder().clientCredentials()` configures a `ClientCredentialsOAuth2AuthorizedClientProvider`,
 which is an implementation of an `OAuth2AuthorizedClientProvider` for the Client Credentials grant.
 
-===== Using the Access Token
+==== Using the Access Token
 
 Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
 
@@ -1361,13 +1361,13 @@ If not provided, it will default to `ServletRequestAttributes` using `RequestCon
 
 
 [[oauth2Client-password-grant]]
-==== Resource Owner Password Credentials
+=== Resource Owner Password Credentials
 
 [NOTE]
 Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials] grant.
 
 
-===== Requesting an Access Token
+==== Requesting an Access Token
 
 [NOTE]
 Please refer to the https://tools.ietf.org/html/rfc6749#section-4.3.2[Access Token Request/Response] protocol flow for the Resource Owner Password Credentials grant.
@@ -1377,7 +1377,7 @@ The default implementation of `OAuth2AccessTokenResponseClient` for the Resource
 The `DefaultPasswordTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
 
 
-===== Customizing the Access Token Request
+==== Customizing the Access Token Request
 
 If you need to customize the pre-processing of the Token Request, you can provide `DefaultPasswordTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<OAuth2PasswordGrantRequest, RequestEntity<?>>`.
 The default implementation `OAuth2PasswordGrantRequestEntityConverter` builds a `RequestEntity` representation of a standard https://tools.ietf.org/html/rfc6749#section-4.3.2[OAuth 2.0 Access Token Request].
@@ -1386,7 +1386,7 @@ However, providing a custom `Converter`, would allow you to extend the standard
 IMPORTANT: The custom `Converter` must return a valid `RequestEntity` representation of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
 
 
-===== Customizing the Access Token Response
+==== Customizing the Access Token Response
 
 On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultPasswordTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
 The default `RestOperations` is configured as follows:
@@ -1461,7 +1461,7 @@ authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
 `OAuth2AuthorizedClientProviderBuilder.builder().password()` configures a `PasswordOAuth2AuthorizedClientProvider`,
 which is an implementation of an `OAuth2AuthorizedClientProvider` for the Resource Owner Password Credentials grant.
 
-===== Using the Access Token
+==== Using the Access Token
 
 Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
 
@@ -1639,13 +1639,13 @@ If not provided, it will default to `ServletRequestAttributes` using `RequestCon
 
 
 [[oauth2Client-jwt-bearer-grant]]
-==== JWT Bearer
+=== JWT Bearer
 
 [NOTE]
 Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on the https://datatracker.ietf.org/doc/html/rfc7523[JWT Bearer] grant.
 
 
-===== Requesting an Access Token
+==== Requesting an Access Token
 
 [NOTE]
 Please refer to the https://datatracker.ietf.org/doc/html/rfc7523#section-2.1[Access Token Request/Response] protocol flow for the JWT Bearer grant.
@@ -1655,14 +1655,14 @@ The default implementation of `OAuth2AccessTokenResponseClient` for the JWT Bear
 The `DefaultJwtBearerTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
 
 
-===== Customizing the Access Token Request
+==== Customizing the Access Token Request
 
 If you need to customize the pre-processing of the Token Request, you can provide `DefaultJwtBearerTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<JwtBearerGrantRequest, RequestEntity<?>>`.
 The default implementation `JwtBearerGrantRequestEntityConverter` builds a `RequestEntity` representation of a https://datatracker.ietf.org/doc/html/rfc7523#section-2.1[OAuth 2.0 Access Token Request].
 However, providing a custom `Converter`, would allow you to extend the Token Request and add custom parameter(s).
 
 
-===== Customizing the Access Token Response
+==== Customizing the Access Token Response
 
 On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultJwtBearerTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
 The default `RestOperations` is configured as follows:
@@ -1738,7 +1738,7 @@ authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
 ----
 ====
 
-===== Using the Access Token
+==== Using the Access Token
 
 Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
 
@@ -1857,11 +1857,11 @@ class OAuth2ResourceServerController {
 
 
 [[oauth2Client-client-auth-support]]
-=== Client Authentication Support
+== Client Authentication Support
 
 
 [[oauth2Client-jwt-bearer-auth]]
-==== JWT Bearer
+=== JWT Bearer
 
 [NOTE]
 Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on https://datatracker.ietf.org/doc/html/rfc7523#section-2.2[JWT Bearer] Client Authentication.
@@ -1874,7 +1874,7 @@ The `java.security.PrivateKey` or `javax.crypto.SecretKey` used for signing the
 is supplied by the `com.nimbusds.jose.jwk.JWK` resolver associated with `NimbusJwtClientAuthenticationParametersConverter`.
 
 
-===== Authenticate using `private_key_jwt`
+==== Authenticate using `private_key_jwt`
 
 Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
 
@@ -1949,7 +1949,7 @@ tokenResponseClient.setRequestEntityConverter(requestEntityConverter)
 ====
 
 
-===== Authenticate using `client_secret_jwt`
+==== Authenticate using `client_secret_jwt`
 
 Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
 
@@ -2024,11 +2024,11 @@ tokenResponseClient.setRequestEntityConverter(requestEntityConverter)
 
 
 [[oauth2Client-additional-features]]
-=== Additional Features
+== Additional Features
 
 
 [[oauth2Client-registered-authorized-client]]
-==== Resolving an Authorized Client
+=== Resolving an Authorized Client
 
 The `@RegisteredOAuth2AuthorizedClient` annotation provides the capability of resolving a method parameter to an argument value of type `OAuth2AuthorizedClient`.
 This is a convenient alternative compared to accessing the `OAuth2AuthorizedClient` using the `OAuth2AuthorizedClientManager` or `OAuth2AuthorizedClientService`.
@@ -2072,7 +2072,7 @@ The `@RegisteredOAuth2AuthorizedClient` annotation is handled by `OAuth2Authoriz
 
 
 [[oauth2Client-webclient-servlet]]
-=== WebClient integration for Servlet Environments
+== WebClient integration for Servlet Environments
 
 The OAuth 2.0 Client support integrates with `WebClient` using an `ExchangeFilterFunction`.
 
@@ -2114,7 +2114,7 @@ fun webClient(authorizedClientManager: OAuth2AuthorizedClientManager?): WebClien
 ----
 ====
 
-==== Providing the Authorized Client
+=== Providing the Authorized Client
 
 The `ServletOAuth2AuthorizedClientExchangeFilterFunction` determines the client to use (for a request) by resolving the `OAuth2AuthorizedClient` from the `ClientRequest.attributes()` (request attributes).
 
@@ -2213,7 +2213,7 @@ fun index(): String {
 <1> `clientRegistrationId()` is a `static` method in `ServletOAuth2AuthorizedClientExchangeFilterFunction`.
 
 
-==== Defaulting the Authorized Client
+=== Defaulting the Authorized Client
 
 If neither `OAuth2AuthorizedClient` or `ClientRegistration.getRegistrationId()` is provided as a request attribute, the `ServletOAuth2AuthorizedClientExchangeFilterFunction` can determine the _default_ client to use depending on it's configuration.
 
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-login.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-login.adoc
rename to docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc
index 3981eda033..db5ee9c506 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-login.adoc
+++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc
@@ -1,5 +1,5 @@
 [[oauth2login]]
-== OAuth 2.0 Login
+= OAuth 2.0 Login
 
 The OAuth 2.0 Login feature provides an application with the capability to have users log in to the application by using their existing account at an OAuth 2.0 Provider (e.g. GitHub) or OpenID Connect 1.0 Provider (such as Google).
 OAuth 2.0 Login implements the use cases: "Login with Google" or "Login with GitHub".
@@ -8,7 +8,7 @@ NOTE: OAuth 2.0 Login is implemented by using the *Authorization Code Grant*, as
 
 
 [[oauth2login-sample-boot]]
-=== Spring Boot 2.x Sample
+== Spring Boot 2.x Sample
 
 Spring Boot 2.x brings full auto-configuration capabilities for OAuth 2.0 Login.
 
@@ -21,7 +21,7 @@ This section shows how to configure the {gh-samples-url}/servlet/spring-boot/jav
 
 
 [[oauth2login-sample-initial-setup]]
-==== Initial setup
+=== Initial setup
 
 To use Google's OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.
 
@@ -33,21 +33,21 @@ After completing the "Obtain OAuth 2.0 credentials" instructions, you should hav
 
 
 [[oauth2login-sample-redirect-uri]]
-==== Setting the redirect URI
+=== Setting the redirect URI
 
 The redirect URI is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with Google and have granted access to the OAuth Client _(<<oauth2login-sample-initial-setup,created in the previous step>>)_ on the Consent page.
 
 In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`.
 
 TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`.
-The *_registrationId_* is a unique identifier for the <<oauth2Client-client-registration,ClientRegistration>>.
+The *_registrationId_* is a unique identifier for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration].
 
-IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check <<http-proxy-server,Proxy Server Configuration>> to ensure the application is correctly configured.
-Also, see the supported <<oauth2Client-auth-code-redirect-uri, `URI` template variables>> for `redirect-uri`.
+IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check xref:features/exploits/http.adoc#http-proxy-server[Proxy Server Configuration] to ensure the application is correctly configured.
+Also, see the supported xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-code-redirect-uri[ `URI` template variables] for `redirect-uri`.
 
 
 [[oauth2login-sample-application-config]]
-==== Configure application.yml
+=== Configure application.yml
 
 Now that you have a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_.
 To do so:
@@ -69,14 +69,14 @@ spring:
 .OAuth Client properties
 ====
 <1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties.
-<2> Following the base property prefix is the ID for the <<oauth2Client-client-registration,ClientRegistration>>, such as google.
+<2> Following the base property prefix is the ID for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration], such as google.
 ====
 
 . Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
 
 
 [[oauth2login-sample-boot-application]]
-==== Boot up the application
+=== Boot up the application
 
 Launch the Spring Boot 2.x sample and go to `http://localhost:8080`.
 You are then redirected to the default _auto-generated_ login page, which displays a link for Google.
@@ -91,9 +91,9 @@ At this point, the OAuth Client retrieves your email address and basic profile i
 
 
 [[oauth2login-boot-property-mappings]]
-=== Spring Boot 2.x Property Mappings
+== Spring Boot 2.x Property Mappings
 
-The following table outlines the mapping of the Spring Boot 2.x OAuth Client properties to the <<oauth2Client-client-registration,ClientRegistration>> properties.
+The following table outlines the mapping of the Spring Boot 2.x OAuth Client properties to the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration] properties.
 
 |===
 |Spring Boot 2.x |ClientRegistration
@@ -149,7 +149,7 @@ A `ClientRegistration` can be initially configured using discovery of an OpenID
 
 
 [[oauth2login-common-oauth2-provider]]
-=== CommonOAuth2Provider
+== CommonOAuth2Provider
 
 `CommonOAuth2Provider` pre-defines a set of default client properties for a number of well known providers: Google, GitHub, Facebook, and Okta.
 
@@ -196,7 +196,7 @@ spring:
 
 
 [[oauth2login-custom-provider-properties]]
-=== Configuring Custom Provider Properties
+== Configuring Custom Provider Properties
 
 There are some OAuth 2.0 Providers that support multi-tenancy, which results in different protocol endpoints for each tenant (or sub-domain).
 
@@ -229,7 +229,7 @@ spring:
 
 
 [[oauth2login-override-boot-autoconfig]]
-=== Overriding Spring Boot 2.x Auto-configuration
+== Overriding Spring Boot 2.x Auto-configuration
 
 The Spring Boot 2.x auto-configuration class for OAuth Client support is `OAuth2ClientAutoConfiguration`.
 
@@ -246,7 +246,7 @@ If you need to override the auto-configuration based on your specific requiremen
 
 
 [[oauth2login-register-clientregistrationrepository-bean]]
-==== Register a ClientRegistrationRepository @Bean
+=== Register a ClientRegistrationRepository @Bean
 
 The following example shows how to register a `ClientRegistrationRepository` `@Bean`:
 
@@ -313,7 +313,7 @@ class OAuth2LoginConfig {
 
 
 [[oauth2login-provide-websecurityconfigureradapter]]
-==== Provide a WebSecurityConfigurerAdapter
+=== Provide a WebSecurityConfigurerAdapter
 
 The following example shows how to provide a `WebSecurityConfigurerAdapter` with `@EnableWebSecurity` and enable OAuth 2.0 login through `httpSecurity.oauth2Login()`:
 
@@ -356,7 +356,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 
 
 [[oauth2login-completely-override-autoconfiguration]]
-==== Completely Override the Auto-configuration
+=== Completely Override the Auto-configuration
 
 The following example shows how to completely override the auto-configuration by registering a `ClientRegistrationRepository` `@Bean` and providing a `WebSecurityConfigurerAdapter`.
 
@@ -451,7 +451,7 @@ class OAuth2LoginConfig {
 
 
 [[oauth2login-javaconfig-wo-boot]]
-=== Java Configuration without Spring Boot 2.x
+== Java Configuration without Spring Boot 2.x
 
 If you are not able to use Spring Boot 2.x and would like to configure one of the pre-defined providers in `CommonOAuth2Provider` (for example, Google), apply the following configuration:
 
@@ -575,7 +575,7 @@ open class OAuth2LoginConfig {
 
 
 [[oauth2login-advanced]]
-=== Advanced Configuration
+== Advanced Configuration
 
 `HttpSecurity.oauth2Login()` provides a number of configuration options for customizing OAuth 2.0 Login.
 The main configuration options are grouped into their protocol endpoint counterparts.
@@ -737,7 +737,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 
 In addition to the `oauth2Login()` DSL, XML configuration is also supported.
 
-The following code shows the complete configuration options available in the <<nsa-oauth2-login, security namespace>>:
+The following code shows the complete configuration options available in the xref:servlet/appendix/namespace.adoc#nsa-oauth2-login[ security namespace]:
 
 .OAuth2 Login XML Configuration Options
 ====
@@ -770,7 +770,7 @@ The following sections go into more detail on each of the configuration options
 
 
 [[oauth2login-advanced-login-page]]
-==== OAuth 2.0 Login Page
+=== OAuth 2.0 Login Page
 
 By default, the OAuth 2.0 Login Page is auto-generated by the `DefaultLoginPageGeneratingFilter`.
 The default login page shows each configured OAuth Client with its `ClientRegistration.clientName` as a link, which is capable of initiating the Authorization Request (or OAuth 2.0 Login).
@@ -865,7 +865,7 @@ The following line shows an example:
 
 
 [[oauth2login-advanced-redirection-endpoint]]
-==== Redirection Endpoint
+=== Redirection Endpoint
 
 The Redirection Endpoint is used by the Authorization Server for returning the Authorization Response (which contains the authorization credentials) to the client via the Resource Owner user-agent.
 
@@ -956,7 +956,7 @@ return CommonOAuth2Provider.GOOGLE.getBuilder("google")
 
 
 [[oauth2login-advanced-userinfo-endpoint]]
-==== UserInfo Endpoint
+=== UserInfo Endpoint
 
 The UserInfo Endpoint includes a number of configuration options, as described in the following sub-sections:
 
@@ -966,7 +966,7 @@ The UserInfo Endpoint includes a number of configuration options, as described i
 
 
 [[oauth2login-advanced-map-authorities]]
-===== Mapping User Authorities
+==== Mapping User Authorities
 
 After the user successfully authenticates with the OAuth 2.0 Provider, the `OAuth2User.getAuthorities()` (or `OidcUser.getAuthorities()`) may be mapped to a new set of `GrantedAuthority` instances, which will be supplied to `OAuth2AuthenticationToken` when completing the authentication.
 
@@ -980,7 +980,7 @@ There are a couple of options to choose from when mapping user authorities:
 
 
 [[oauth2login-advanced-map-authorities-grantedauthoritiesmapper]]
-====== Using a GrantedAuthoritiesMapper
+===== Using a GrantedAuthoritiesMapper
 
 Provide an implementation of `GrantedAuthoritiesMapper` and configure it as shown in the following example:
 
@@ -1126,7 +1126,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 ====
 
 [[oauth2login-advanced-map-authorities-oauth2userservice]]
-====== Delegation-based strategy with OAuth2UserService
+===== Delegation-based strategy with OAuth2UserService
 
 This strategy is advanced compared to using a `GrantedAuthoritiesMapper`, however, it's also more flexible as it gives you access to the `OAuth2UserRequest` and `OAuth2User` (when using an OAuth 2.0 UserService) or `OidcUserRequest` and `OidcUser` (when using an OpenID Connect 1.0 UserService).
 
@@ -1228,7 +1228,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 
 
 [[oauth2login-advanced-oauth2-user-service]]
-===== OAuth 2.0 UserService
+==== OAuth 2.0 UserService
 
 `DefaultOAuth2UserService` is an implementation of an `OAuth2UserService` that supports standard OAuth 2.0 Provider's.
 
@@ -1304,7 +1304,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 
 
 [[oauth2login-advanced-oidc-user-service]]
-===== OpenID Connect 1.0 UserService
+==== OpenID Connect 1.0 UserService
 
 `OidcUserService` is an implementation of an `OAuth2UserService` that supports OpenID Connect 1.0 Provider's.
 
@@ -1364,7 +1364,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 
 
 [[oauth2login-advanced-idtoken-verify]]
-==== ID Token Signature Verification
+=== ID Token Signature Verification
 
 OpenID Connect 1.0 Authentication introduces the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID Token], which is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when used by a Client.
 
@@ -1409,7 +1409,7 @@ If more than one `ClientRegistration` is configured for OpenID Connect 1.0 Authe
 
 
 [[oauth2login-advanced-oidc-logout]]
-==== OpenID Connect 1.0 Logout
+=== OpenID Connect 1.0 Logout
 
 OpenID Connect Session Management 1.0 allows the ability to log out the End-User at the Provider using the Client.
 One of the strategies available is https://openid.net/specs/openid-connect-session-1_0.html#RPLogout[RP-Initiated Logout].
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-resourceserver.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc
similarity index 93%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-resourceserver.adoc
rename to docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc
index c57881a269..14732c21a6 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-resourceserver.adoc
+++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc
@@ -1,7 +1,6 @@
 [[oauth2resourceserver]]
-== OAuth 2.0 Resource Server
-:figures: images/servlet/oauth2
-:icondir: images/icons
+= OAuth 2.0 Resource Server
+:figures: servlet/oauth2
 
 Spring Security supports protecting endpoints using two forms of OAuth 2.0 https://tools.ietf.org/html/rfc6750.html[Bearer Tokens]:
 
@@ -19,19 +18,19 @@ Working samples for both {gh-samples-url}/servlet/spring-boot/java/oauth2/resour
 ====
 
 Let's take a look at how Bearer Token Authentication works within Spring Security.
-First, we see that, like <<servlet-authentication-basic,Basic Authentication>>, the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client.
+First, we see that, like xref:servlet/authentication/passwords/basic.adoc#servlet-authentication-basic[Basic Authentication], the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client.
 
 .Sending WWW-Authenticate Header
 image::{figures}/bearerauthenticationentrypoint.png[]
 
-The figure above builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure above builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
 image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
 
-image:{icondir}/number_2.png[] Spring Security's <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
+image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
 
-image:{icondir}/number_3.png[] Since the user is not authenticated, <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__.
-The configured <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>> is an instance of {security-api-url}org/springframework/security/oauth2/server/resource/web/BearerTokenAuthenticationEntryPoint.html[`BearerTokenAuthenticationEntryPoint`] which sends a WWW-Authenticate header.
+image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/oauth2/server/resource/web/BearerTokenAuthenticationEntryPoint.html[`BearerTokenAuthenticationEntryPoint`] which sends a WWW-Authenticate header.
 The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested.
 
 When a client receives the `WWW-Authenticate: Bearer` header, it knows it should retry with a bearer token.
@@ -41,36 +40,36 @@ Below is the flow for the bearer token being processed.
 .Authenticating Bearer Token
 image::{figures}/bearertokenauthenticationfilter.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
 
-image:{icondir}/number_1.png[] When the user submits their bearer token, the `BearerTokenAuthenticationFilter` creates a `BearerTokenAuthenticationToken` which is a type of <<servlet-authentication-authentication,`Authentication`>> by extracting the token from the `HttpServletRequest`.
+image:{icondir}/number_1.png[] When the user submits their bearer token, the `BearerTokenAuthenticationFilter` creates a `BearerTokenAuthenticationToken` which is a type of xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] by extracting the token from the `HttpServletRequest`.
 
 image:{icondir}/number_2.png[] Next, the `HttpServletRequest` is passed to the `AuthenticationManagerResolver`, which selects the `AuthenticationManager`. The `BearerTokenAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated.
 The details of what `AuthenticationManager` looks like depends on whether you're configured for <<oauth2resourceserver-jwt-minimalconfiguration,JWT>> or <<oauth2resourceserver-opaque-minimalconfiguration,opaque token>>.
 
 image:{icondir}/number_3.png[] If authentication fails, then __Failure__
 
-* The <<servlet-authentication-securitycontextholder>> is cleared out.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder] is cleared out.
 * The `AuthenticationEntryPoint` is invoked to trigger the WWW-Authenticate header to be sent again.
 
 image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
 
-* The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[Authentication] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
 * The `BearerTokenAuthenticationFilter` invokes `FilterChain.doFilter(request,response)` to continue with the rest of the application logic.
 
 [[oauth2resourceserver-jwt-minimaldependencies]]
-=== Minimal Dependencies for JWT
+== Minimal Dependencies for JWT
 
 Most Resource Server support is collected into `spring-security-oauth2-resource-server`.
 However, the support for decoding and verifying JWTs is in `spring-security-oauth2-jose`, meaning that both are necessary in order to have a working resource server that supports JWT-encoded Bearer Tokens.
 
 [[oauth2resourceserver-jwt-minimalconfiguration]]
-=== Minimal Configuration for JWTs
+== Minimal Configuration for JWTs
 
 When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a resource server consists of two basic steps.
 First, include the needed dependencies and second, indicate the location of the authorization server.
 
-==== Specifying the Authorization Server
+=== Specifying the Authorization Server
 
 In a Spring Boot application, to specify which authorization server to use, simply do:
 
@@ -93,7 +92,7 @@ This endpoint is referred to as a https://openid.net/specs/openid-connect-discov
 
 And that's it!
 
-==== Startup Expectations
+=== Startup Expectations
 
 When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens.
 
@@ -109,7 +108,7 @@ A consequence of this process is that the authorization server must be up and re
 [NOTE]
 If the authorization server is down when Resource Server queries it (given appropriate timeouts), then startup will fail.
 
-==== Runtime Expectations
+=== Runtime Expectations
 
 Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
 
@@ -139,21 +138,21 @@ From here, consider jumping to:
 * <<oauth2resourceserver-jwt-sansboot,How to Configure without Spring Boot>>
 
 [[oauth2resourceserver-jwt-architecture]]
-=== How JWT Authentication Works
+== How JWT Authentication Works
 
 Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7519[JWT] Authentication in servlet-based applications, like the one we just saw.
 
-{security-api-url}org/springframework/security/oauth2/server/resource/authentication/JwtAuthenticationProvider.html[`JwtAuthenticationProvider`] is an <<servlet-authentication-authenticationprovider,`AuthenticationProvider`>> implementation that leverages a <<oauth2resourceserver-jwt-decoder,`JwtDecoder`>> and <<oauth2resourceserver-jwt-authorization-extraction,`JwtAuthenticationConverter`>> to authenticate a JWT.
+{security-api-url}org/springframework/security/oauth2/server/resource/authentication/JwtAuthenticationProvider.html[`JwtAuthenticationProvider`] is an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <<oauth2resourceserver-jwt-decoder,`JwtDecoder`>> and <<oauth2resourceserver-jwt-authorization-extraction,`JwtAuthenticationConverter`>> to authenticate a JWT.
 
 Let's take a look at how `JwtAuthenticationProvider` works within Spring Security.
-The figure explains details of how the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> in figures from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> works.
+The figure explains details of how the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> works.
 
 .`JwtAuthenticationProvider` Usage
 image::{figures}/jwtauthenticationprovider.png[]
 
-image:{icondir}/number_1.png[] The authentication `Filter` from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by <<servlet-authentication-providermanager,`ProviderManager`>>.
+image:{icondir}/number_1.png[] The authentication `Filter` from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
 
-image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <<servlet-authentication-authenticationprovider>> of type `JwtAuthenticationProvider`.
+image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[AuthenticationProvider] of type `JwtAuthenticationProvider`.
 
 [[oauth2resourceserver-jwt-architecture-jwtdecoder]]
 image:{icondir}/number_3.png[] `JwtAuthenticationProvider` decodes, verifies, and validates the `Jwt` using a <<oauth2resourceserver-jwt-decoder,`JwtDecoder`>>.
@@ -161,11 +160,11 @@ image:{icondir}/number_3.png[] `JwtAuthenticationProvider` decodes, verifies, an
 [[oauth2resourceserver-jwt-architecture-jwtauthenticationconverter]]
 image:{icondir}/number_4.png[] `JwtAuthenticationProvider` then uses the <<oauth2resourceserver-jwt-authorization-extraction,`JwtAuthenticationConverter`>> to convert the `Jwt` into a `Collection` of granted authorities.
 
-image:{icondir}/number_5.png[] When authentication is successful, the <<servlet-authentication-authentication,`Authentication`>> that is returned is of type `JwtAuthenticationToken` and has a principal that is the `Jwt` returned by the configured `JwtDecoder`.
-Ultimately, the returned `JwtAuthenticationToken` will be set on the <<servlet-authentication-securitycontextholder,`SecurityContextHolder`>> by the authentication `Filter`.
+image:{icondir}/number_5.png[] When authentication is successful, the xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `JwtAuthenticationToken` and has a principal that is the `Jwt` returned by the configured `JwtDecoder`.
+Ultimately, the returned `JwtAuthenticationToken` will be set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
 
 [[oauth2resourceserver-jwt-jwkseturi]]
-=== Specifying the Authorization Server JWK Set Uri Directly
+== Specifying the Authorization Server JWK Set Uri Directly
 
 If the authorization server doesn't support any configuration endpoints, or if Resource Server must be able to start up independently from the authorization server, then the `jwk-set-uri` can be supplied as well:
 
@@ -190,7 +189,7 @@ We still specify the `issuer-uri` so that Resource Server still validates the `i
 This property can also be supplied directly on the <<oauth2resourceserver-jwt-jwkseturi-dsl,DSL>>.
 
 [[oauth2resourceserver-jwt-sansboot]]
-=== Overriding or Replacing Boot Auto Configuration
+== Overriding or Replacing Boot Auto Configuration
 
 There are two ``@Bean``s that Spring Boot generates on Resource Server's behalf.
 
@@ -343,7 +342,7 @@ And the `JwtDecoder` like so:
 ====
 
 [[oauth2resourceserver-jwt-jwkseturi-dsl]]
-==== Using `jwkSetUri()`
+=== Using `jwkSetUri()`
 
 An authorization server's JWK Set Uri can be configured <<oauth2resourceserver-jwt-jwkseturi,as a configuration property>> or it can be supplied in the DSL:
 
@@ -403,7 +402,7 @@ class DirectlyConfiguredJwkSetUri : WebSecurityConfigurerAdapter() {
 Using `jwkSetUri()` takes precedence over any configuration property.
 
 [[oauth2resourceserver-jwt-decoder-dsl]]
-==== Using `decoder()`
+=== Using `decoder()`
 
 More powerful than `jwkSetUri()` is `decoder()`, which will completely replace any Boot auto configuration of <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>>:
 
@@ -463,7 +462,7 @@ class DirectlyConfiguredJwtDecoder : WebSecurityConfigurerAdapter() {
 This is handy when deeper configuration, like <<oauth2resourceserver-jwt-validation,validation>>, <<oauth2resourceserver-jwt-claimsetmapping,mapping>>, or <<oauth2resourceserver-jwt-timeouts,request timeouts>>, is necessary.
 
 [[oauth2resourceserver-jwt-decoder-bean]]
-==== Exposing a `JwtDecoder` `@Bean`
+=== Exposing a `JwtDecoder` `@Bean`
 
 Or, exposing a <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>> `@Bean` has the same effect as `decoder()`:
 
@@ -488,14 +487,14 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-decoder-algorithm]]
-=== Configuring Trusted Algorithms
+== Configuring Trusted Algorithms
 
 By default, `NimbusJwtDecoder`, and hence Resource Server, will only trust and verify tokens using `RS256`.
 
 You can customize this via <<oauth2resourceserver-jwt-boot-algorithm,Spring Boot>>, <<oauth2resourceserver-jwt-decoder-builder,the NimbusJwtDecoder builder>>, or from the <<oauth2resourceserver-jwt-decoder-jwk-response,JWK Set response>>.
 
 [[oauth2resourceserver-jwt-boot-algorithm]]
-==== Via Spring Boot
+=== Via Spring Boot
 
 The simplest way to set the algorithm is as a property:
 
@@ -511,7 +510,7 @@ spring:
 ----
 
 [[oauth2resourceserver-jwt-decoder-builder]]
-==== Using a Builder
+=== Using a Builder
 
 For greater power, though, we can use a builder that ships with `NimbusJwtDecoder`:
 
@@ -592,7 +591,7 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-decoder-jwk-response]]
-==== From JWK Set response
+=== From JWK Set response
 
 Since Spring Security's JWT support is based off of Nimbus, you can use all it's great features as well.
 
@@ -632,13 +631,13 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-decoder-public-key]]
-=== Trusting a Single Asymmetric Key
+== Trusting a Single Asymmetric Key
 
 Simpler than backing a Resource Server with a JWK Set endpoint is to hard-code an RSA public key.
 The public key can be provided via <<oauth2resourceserver-jwt-decoder-public-key-boot,Spring Boot>> or by <<oauth2resourceserver-jwt-decoder-public-key-builder,Using a Builder>>.
 
 [[oauth2resourceserver-jwt-decoder-public-key-boot]]
-==== Via Spring Boot
+=== Via Spring Boot
 
 Specifying a key via Spring Boot is quite simple.
 The key's location can be specified like so:
@@ -705,7 +704,7 @@ val key: RSAPublicKey? = null
 ====
 
 [[oauth2resourceserver-jwt-decoder-public-key-builder]]
-==== Using a Builder
+=== Using a Builder
 
 To wire an `RSAPublicKey` directly, you can simply use the appropriate `NimbusJwtDecoder` builder, like so:
 
@@ -730,7 +729,7 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-decoder-secret-key]]
-=== Trusting a Single Symmetric Key
+== Trusting a Single Symmetric Key
 
 Using a single symmetric key is also simple.
 You can simply load in your `SecretKey` and use the appropriate `NimbusJwtDecoder` builder, like so:
@@ -756,7 +755,7 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-authorization]]
-=== Configuring Authorization
+== Configuring Authorization
 
 A JWT that is issued from an OAuth 2.0 Authorization Server will typically either have a `scope` or `scp` attribute, indicating the scopes (or authorities) it's been granted, for example:
 
@@ -837,7 +836,7 @@ fun getMessages(): List<Message> { }
 ====
 
 [[oauth2resourceserver-jwt-authorization-extraction]]
-==== Extracting Authorities Manually
+=== Extracting Authorities Manually
 
 However, there are a number of circumstances where this default is insufficient.
 For example, some authorization servers don't use the `scope` attribute, but instead have their own custom attribute.
@@ -1024,14 +1023,14 @@ class CustomAuthenticationConverterConfig : WebSecurityConfigurerAdapter() {
 ====
 
 [[oauth2resourceserver-jwt-validation]]
-=== Configuring Validation
+== Configuring Validation
 
 Using <<oauth2resourceserver-jwt-minimalconfiguration,minimal Spring Boot configuration>>, indicating the authorization server's issuer uri, Resource Server will default to verifying the `iss` claim as well as the `exp` and `nbf` timestamp claims.
 
 In circumstances where validation needs to be customized, Resource Server ships with two standard validators and also accepts custom `OAuth2TokenValidator` instances.
 
 [[oauth2resourceserver-jwt-validation-clockskew]]
-==== Customizing Timestamp Validation
+=== Customizing Timestamp Validation
 
 JWT's typically have a window of validity, with the start of the window indicated in the `nbf` claim and the end indicated in the `exp` claim.
 
@@ -1081,7 +1080,7 @@ fun jwtDecoder(): JwtDecoder {
 By default, Resource Server configures a clock skew of 60 seconds.
 
 [[oauth2resourceserver-jwt-validation-custom]]
-==== Configuring a Custom Validator
+=== Configuring a Custom Validator
 
 Adding a check for the `aud` claim is simple with the `OAuth2TokenValidator` API:
 
@@ -1192,7 +1191,7 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-claimsetmapping]]
-=== Configuring Claim Set Mapping
+== Configuring Claim Set Mapping
 
 Spring Security uses the https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home[Nimbus] library for parsing JWTs and validating their signatures.
 Consequently, Spring Security is subject to Nimbus's interpretation of each field value and how to coerce each into a Java type.
@@ -1206,7 +1205,7 @@ Or, quite simply, a resource server may want to add or remove claims from a JWT
 For these purposes, Resource Server supports mapping the JWT claim set with `MappedJwtClaimSetConverter`.
 
 [[oauth2resourceserver-jwt-claimsetmapping-singleclaim]]
-==== Customizing the Conversion of a Single Claim
+=== Customizing the Conversion of a Single Claim
 
 By default, `MappedJwtClaimSetConverter` will attempt to coerce claims into the following types:
 
@@ -1257,7 +1256,7 @@ fun jwtDecoder(): JwtDecoder {
 This will keep all the defaults, except it will override the default claim converter for `sub`.
 
 [[oauth2resourceserver-jwt-claimsetmapping-add]]
-==== Adding a Claim
+=== Adding a Claim
 
 `MappedJwtClaimSetConverter` can also be used to add a custom claim, for example, to adapt to an existing system:
 
@@ -1276,7 +1275,7 @@ MappedJwtClaimSetConverter.withDefaults(mapOf("custom" to Converter<Any, String>
 ====
 
 [[oauth2resourceserver-jwt-claimsetmapping-remove]]
-==== Removing a Claim
+=== Removing a Claim
 
 And removing a claim is also simple, using the same API:
 
@@ -1295,7 +1294,7 @@ MappedJwtClaimSetConverter.withDefaults(mapOf("legacyclaim" to Converter<Any, An
 ====
 
 [[oauth2resourceserver-jwt-claimsetmapping-rename]]
-==== Renaming a Claim
+=== Renaming a Claim
 
 In more sophisticated scenarios, like consulting multiple claims at once or renaming a claim, Resource Server accepts any class that implements `Converter<Map<String, Object>, Map<String,Object>>`:
 
@@ -1360,7 +1359,7 @@ fun jwtDecoder(): JwtDecoder {
 ====
 
 [[oauth2resourceserver-jwt-timeouts]]
-=== Configuring Timeouts
+== Configuring Timeouts
 
 By default, Resource Server uses connection and socket timeouts of 30 seconds each for coordinating with the authorization server.
 
@@ -1436,14 +1435,14 @@ NOTE: Whether it's socket or cache timeouts, you may instead want to work with N
 To do so, remember that `NimbusJwtDecoder` ships with a constructor that takes Nimbus's `JWTProcessor`.
 
 [[oauth2resourceserver-opaque-minimaldependencies]]
-=== Minimal Dependencies for Introspection
+== Minimal Dependencies for Introspection
 As described in <<oauth2resourceserver-jwt-minimaldependencies,Minimal Dependencies for JWT>> most of Resource Server support is collected in `spring-security-oauth2-resource-server`.
 However unless a custom <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>> is provided, the Resource Server will fallback to NimbusOpaqueTokenIntrospector.
 Meaning that both `spring-security-oauth2-resource-server` and `oauth2-oidc-sdk` are necessary in order to have a working minimal Resource Server that supports opaque Bearer Tokens.
 Please refer to `spring-security-oauth2-resource-server` in order to determin the correct version for `oauth2-oidc-sdk`.
 
 [[oauth2resourceserver-opaque-minimalconfiguration]]
-=== Minimal Configuration for Introspection
+== Minimal Configuration for Introspection
 
 Typically, an opaque token can be verified via an https://tools.ietf.org/html/rfc7662[OAuth 2.0 Introspection Endpoint], hosted by the authorization server.
 This can be handy when revocation is a requirement.
@@ -1452,7 +1451,7 @@ When using https://spring.io/projects/spring-boot[Spring Boot], configuring an a
 First, include the needed dependencies and second, indicate the introspection endpoint details.
 
 [[oauth2resourceserver-opaque-introspectionuri]]
-==== Specifying the Authorization Server
+=== Specifying the Authorization Server
 
 To specify where the introspection endpoint is, simply do:
 
@@ -1477,13 +1476,13 @@ If the authorization server responses that the token is valid, then it is.
 
 And that's it!
 
-==== Startup Expectations
+=== Startup Expectations
 
 When this property and these dependencies are used, Resource Server will automatically configure itself to validate Opaque Bearer Tokens.
 
 This startup process is quite a bit simpler than for JWTs since no endpoints need to be discovered and no additional validation rules get added.
 
-==== Runtime Expectations
+=== Runtime Expectations
 
 Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header:
 
@@ -1510,29 +1509,29 @@ From here, you may want to jump to:
 * <<oauth2resourceserver-opaque-jwt-introspector,Using Introspection with JWTs>>
 
 [[oauth2resourceserver-opaque-architecture]]
-=== How Opaque Token Authentication Works
+== How Opaque Token Authentication Works
 
 Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7662[opaque token] Authentication in servlet-based applications, like the one we just saw.
 
-{security-api-url}org/springframework/security/oauth2/server/resource/authentication/OpaqueTokenAuthenticationProvider.html[`OpaqueTokenAuthenticationProvider`] is an <<servlet-authentication-authenticationprovider,`AuthenticationProvider`>> implementation that leverages a <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>> to authenticate an opaque token.
+{security-api-url}org/springframework/security/oauth2/server/resource/authentication/OpaqueTokenAuthenticationProvider.html[`OpaqueTokenAuthenticationProvider`] is an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>> to authenticate an opaque token.
 
 Let's take a look at how `OpaqueTokenAuthenticationProvider` works within Spring Security.
-The figure explains details of how the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> in figures from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> works.
+The figure explains details of how the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> works.
 
 .`OpaqueTokenAuthenticationProvider` Usage
 image::{figures}/opaquetokenauthenticationprovider.png[]
 
-image:{icondir}/number_1.png[] The authentication `Filter` from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by <<servlet-authentication-providermanager,`ProviderManager`>>.
+image:{icondir}/number_1.png[] The authentication `Filter` from <<oauth2resourceserver-authentication-bearertokenauthenticationfilter,Reading the Bearer Token>> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
 
-image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <<servlet-authentication-authenticationprovider>> of type `OpaqueTokenAuthenticationProvider`.
+image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationprovider[AuthenticationProvider] of type `OpaqueTokenAuthenticationProvider`.
 
 [[oauth2resourceserver-opaque-architecture-introspector]]
 image:{icondir}/number_3.png[] `OpaqueTokenAuthenticationProvider` introspects the opaque token and adds granted authorities using an <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>>.
-When authentication is successful, the <<servlet-authentication-authentication,`Authentication`>> that is returned is of type `BearerTokenAuthentication` and has a principal that is the `OAuth2AuthenticatedPrincipal` returned by the configured <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>>.
-Ultimately, the returned `BearerTokenAuthentication` will be set on the <<servlet-authentication-securitycontextholder,`SecurityContextHolder`>> by the authentication `Filter`.
+When authentication is successful, the xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `BearerTokenAuthentication` and has a principal that is the `OAuth2AuthenticatedPrincipal` returned by the configured <<oauth2resourceserver-opaque-introspector,`OpaqueTokenIntrospector`>>.
+Ultimately, the returned `BearerTokenAuthentication` will be set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
 
 [[oauth2resourceserver-opaque-attributes]]
-=== Looking Up Attributes Post-Authentication
+== Looking Up Attributes Post-Authentication
 
 Once a token is authenticated, an instance of `BearerTokenAuthentication` is set in the `SecurityContext`.
 
@@ -1580,7 +1579,7 @@ fun foo(@AuthenticationPrincipal principal: OAuth2AuthenticatedPrincipal): Strin
 ----
 ====
 
-==== Looking Up Attributes Via SpEL
+=== Looking Up Attributes Via SpEL
 
 Of course, this also means that attributes can be accessed via SpEL.
 
@@ -1607,7 +1606,7 @@ fun forFoosEyesOnly(): String {
 ====
 
 [[oauth2resourceserver-opaque-sansboot]]
-=== Overriding or Replacing Boot Auto Configuration
+== Overriding or Replacing Boot Auto Configuration
 
 There are two ``@Bean``s that Spring Boot generates on Resource Server's behalf.
 
@@ -1758,7 +1757,7 @@ And the <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntr
 ====
 
 [[oauth2resourceserver-opaque-introspectionuri-dsl]]
-==== Using `introspectionUri()`
+=== Using `introspectionUri()`
 
 An authorization server's Introspection Uri can be configured <<oauth2resourceserver-opaque-introspectionuri,as a configuration property>> or it can be supplied in the DSL:
 
@@ -1820,7 +1819,7 @@ class DirectlyConfiguredIntrospectionUri : WebSecurityConfigurerAdapter() {
 Using `introspectionUri()` takes precedence over any configuration property.
 
 [[oauth2resourceserver-opaque-introspector-dsl]]
-==== Using `introspector()`
+=== Using `introspector()`
 
 More powerful than `introspectionUri()` is `introspector()`, which will completely replace any Boot auto configuration of <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>>:
 
@@ -1880,7 +1879,7 @@ class DirectlyConfiguredIntrospector : WebSecurityConfigurerAdapter() {
 This is handy when deeper configuration, like <<oauth2resourceserver-opaque-authorization-extraction,authority mapping>>, <<oauth2resourceserver-opaque-jwt-introspector,JWT revocation>>, or <<oauth2resourceserver-opaque-timeouts,request timeouts>>, is necessary.
 
 [[oauth2resourceserver-opaque-introspector-bean]]
-==== Exposing a `OpaqueTokenIntrospector` `@Bean`
+=== Exposing a `OpaqueTokenIntrospector` `@Bean`
 
 Or, exposing a <<oauth2resourceserver-opaque-architecture-introspector,`OpaqueTokenIntrospector`>> `@Bean` has the same effect as `introspector()`:
 
@@ -1893,7 +1892,7 @@ public OpaqueTokenIntrospector introspector() {
 ----
 
 [[oauth2resourceserver-opaque-authorization]]
-=== Configuring Authorization
+== Configuring Authorization
 
 An OAuth 2.0 Introspection endpoint will typically return a `scope` attribute, indicating the scopes (or authorities) it's been granted, for example:
 
@@ -1974,7 +1973,7 @@ fun getMessages(): List<Message?> {}
 ====
 
 [[oauth2resourceserver-opaque-authorization-extraction]]
-==== Extracting Authorities Manually
+=== Extracting Authorities Manually
 
 By default, Opaque Token support will extract the scope claim from an introspection response and parse it into individual `GrantedAuthority` instances.
 
@@ -2058,7 +2057,7 @@ fun introspector(): OpaqueTokenIntrospector {
 ====
 
 [[oauth2resourceserver-opaque-timeouts]]
-=== Configuring Timeouts
+== Configuring Timeouts
 
 By default, Resource Server uses connection and socket timeouts of 30 seconds each for coordinating with the authorization server.
 
@@ -2099,7 +2098,7 @@ fun introspector(builder: RestTemplateBuilder, properties: OAuth2ResourceServerP
 ====
 
 [[oauth2resourceserver-opaque-jwt-introspector]]
-=== Using Introspection with JWTs
+== Using Introspection with JWTs
 
 A common question is whether or not introspection is compatible with JWTs.
 Spring Security's Opaque Token support has been designed to not care about the format of the token -- it will gladly pass any token to the introspection endpoint provided.
@@ -2204,7 +2203,7 @@ fun introspector(): OpaqueTokenIntrospector {
 ====
 
 [[oauth2resourceserver-opaque-userinfo]]
-=== Calling a `/userinfo` Endpoint
+== Calling a `/userinfo` Endpoint
 
 Generally speaking, a Resource Server doesn't care about the underlying user, but instead about the authorities that have been granted.
 
@@ -2324,7 +2323,7 @@ fun introspector(): OpaqueTokenIntrospector {
 ====
 
 [[oauth2reourceserver-opaqueandjwt]]
-=== Supporting both JWT and Opaque Token
+== Supporting both JWT and Opaque Token
 
 In some cases, you may have a need to access both kinds of tokens.
 For example, you may support more than one tenant where one tenant issues JWTs and the other issues opaque tokens.
@@ -2407,7 +2406,7 @@ http {
 ====
 
 [[oauth2resourceserver-multitenancy]]
-=== Multi-tenancy
+== Multi-tenancy
 
 A resource server is considered multi-tenant when there are multiple strategies for verifying a bearer token, keyed by some tenant identifier.
 
@@ -2419,7 +2418,7 @@ In each case, there are two things that need to be done and trade-offs associate
 1. Resolve the tenant
 2. Propagate the tenant
 
-==== Resolving the Tenant By Claim
+=== Resolving the Tenant By Claim
 
 One way to differentiate tenants is by the issuer claim. Since the issuer claim accompanies signed JWTs, this can be done with the `JwtIssuerAuthenticationManagerResolver`, like so:
 
@@ -2478,7 +2477,7 @@ This is nice because the issuer endpoints are loaded lazily.
 In fact, the corresponding `JwtAuthenticationProvider` is instantiated only when the first request with the corresponding issuer is sent.
 This allows for an application startup that is independent from those authorization servers being up and available.
 
-===== Dynamic Tenants
+==== Dynamic Tenants
 
 Of course, you may not want to restart the application each time a new tenant is added.
 In this case, you can configure the `JwtIssuerAuthenticationManagerResolver` with a repository of `AuthenticationManager` instances, which you can edit at runtime, like so:
@@ -2538,7 +2537,7 @@ This approach allows us to add and remove elements from the repository (shown as
 NOTE: It would be unsafe to simply take any issuer and construct an `AuthenticationManager` from it.
 The issuer should be one that the code can verify from a trusted source like a list of allowed issuers.
 
-===== Parsing the Claim Only Once
+==== Parsing the Claim Only Once
 
 You may have observed that this strategy, while simple, comes with the trade-off that the JWT is parsed once by the `AuthenticationManagerResolver` and then again by the <<oauth2resourceserver-jwt-architecture-jwtdecoder,`JwtDecoder`>> later on in the request.
 
@@ -2768,12 +2767,12 @@ For example, if you are resolving it by subdomain, you may need to address the d
 However, if you resolve it by a claim in the bearer token, read on to learn about <<oauth2resourceserver-bearertoken-resolver,Spring Security's support for bearer token propagation>>.
 
 [[oauth2resourceserver-bearertoken-resolver]]
-=== Bearer Token Resolution
+== Bearer Token Resolution
 
 By default, Resource Server looks for a bearer token in the `Authorization` header.
 This, however, can be customized in a handful of ways.
 
-==== Reading the Bearer Token from a Custom Header
+=== Reading the Bearer Token from a Custom Header
 
 For example, you may have a need to read the bearer token from a custom header.
 To achieve this, you can expose a `DefaultBearerTokenResolver` as a bean, or wire an instance into the DSL, as you can see in the following example:
@@ -2818,7 +2817,7 @@ fun bearerTokenResolver(): BearerTokenResolver {
 
 Or, in circumstances where a provider is using both a custom header and value, you can use `HeaderBearerTokenResolver` instead.
 
-==== Reading the Bearer Token from a Form Parameter
+=== Reading the Bearer Token from a Form Parameter
 
 Or, you may wish to read the token from a form parameter, which you can do by configuring the `DefaultBearerTokenResolver`, as you can see below:
 
@@ -2861,7 +2860,7 @@ http {
 ----
 ====
 
-=== Bearer Token Propagation
+== Bearer Token Propagation
 
 Now that you're resource server has validated the token, it might be handy to pass it to downstream services.
 This is quite simple with `{security-api-url}org/springframework/security/oauth2/server/resource/web/reactive/function/client/ServletBearerExchangeFilterFunction.html[ServletBearerExchangeFilterFunction]`, which you can see in the following example:
@@ -2951,7 +2950,7 @@ In this case, the filter will fall back and simply forward the request onto the
 Unlike the {security-api-url}org/springframework/security/oauth2/client/web/reactive/function/client/ServletOAuth2AuthorizedClientExchangeFilterFunction.html[OAuth 2.0 Client filter function], this filter function makes no attempt to renew the token, should it be expired.
 To obtain this level of support, please use the OAuth 2.0 Client filter.
 
-==== `RestTemplate` support
+=== `RestTemplate` support
 
 There is no `RestTemplate` equivalent for `ServletBearerExchangeFilterFunction` at the moment, but you can propagate the request's bearer token quite simply with your own interceptor:
 
@@ -3008,10 +3007,10 @@ fun rest(): RestTemplate {
 
 [NOTE]
 Unlike the {security-api-url}org/springframework/security/oauth2/client/OAuth2AuthorizedClientManager.html[OAuth 2.0 Authorized Client Manager], this filter interceptor makes no attempt to renew the token, should it be expired.
-To obtain this level of support, please create an interceptor using the <<oauth2client,OAuth 2.0 Authorized Client Manager>>.
+To obtain this level of support, please create an interceptor using the xref:servlet/oauth2/oauth2-client.adoc#oauth2client[OAuth 2.0 Authorized Client Manager].
 
 [[oauth2resourceserver-bearertoken-failure]]
-=== Bearer Token Failure
+== Bearer Token Failure
 
 A bearer token may be invalid for a number of reasons. For example, the token may no longer be active.
 
@@ -3024,7 +3023,7 @@ HTTP/1.1 401 Unauthorized
 WWW-Authenticate: Bearer error_code="invalid_token", error_description="Unsupported algorithm of none", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
 ----
 
-Additionally, it is published as an `AuthenticationFailureBadCredentialsEvent`, which you can <<servlet-events,listen for in your application>> like so:
+Additionally, it is published as an `AuthenticationFailureBadCredentialsEvent`, which you can xref:servlet/authentication/events.adoc#servlet-events[listen for in your application] like so:
 
 ====
 .Java
diff --git a/docs/modules/ROOT/pages/servlet/saml2/index.adoc b/docs/modules/ROOT/pages/servlet/saml2/index.adoc
new file mode 100644
index 0000000000..43a9baf4d1
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/saml2/index.adoc
@@ -0,0 +1,1617 @@
+[[servlet-saml2]]
+= SAML2
+:figures: servlet/saml2
+
+Spring Security provides comprehensive SAML 2 support.
+This section discusses how to integrate SAML 2 into your servlet based application.
+
+[[servlet-saml2login]]
+== SAML 2.0 Login
+
+The SAML 2.0 Login feature provides an application with the capability to act as a SAML 2.0 Relying Party, having users https://wiki.shibboleth.net/confluence/display/CONCEPT/FlowsAndConfig[log in] to the application by using their existing account at a SAML 2.0 Asserting Party (Okta, ADFS, etc).
+
+NOTE: SAML 2.0 Login is implemented by using the *Web Browser SSO Profile*, as specified in
+https://www.oasis-open.org/committees/download.php/35389/sstc-saml-profiles-errata-2.0-wd-06-diff.pdf#page=15[SAML 2 Profiles].
+
+[[servlet-saml2login-spring-security-history]]
+Since 2009, support for relying parties has existed as an https://github.com/spring-projects/spring-security-saml/tree/1e013b07a7772defd6a26fcfae187c9bf661ee8f#spring-saml[extension project].
+In 2019, the process began to port that into https://github.com/spring-projects/spring-security[Spring Security] proper.
+This process is similar to the one started in 2017 for <<oauth2,Spring Security's OAuth 2.0 support>>.
+
+[NOTE]
+====
+A working sample for {gh-samples-url}/servlet/spring-boot/java/saml2-login[SAML 2.0 Login] is available in the {gh-samples-url}[Spring Security Samples repository].
+====
+
+Let's take a look at how SAML 2.0 Relying Party Authentication works within Spring Security.
+First, we see that, like xref:servlet/oauth2/oauth2-login.adoc#oauth2login[ OAuth 2.0 Login], Spring Security takes the user to a third-party for performing authentication.
+It does this through a series of redirects.
+
+.Redirecting to Asserting Party Authentication
+image::{figures}/saml2webssoauthenticationrequestfilter.png[]
+
+The figure above builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] and xref:servlet/authentication/architecture.adoc#servlet-authentication-abstractprocessingfilter[ `AbstractAuthenticationProcessingFilter`] diagrams:
+
+image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
+
+image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
+
+image:{icondir}/number_3.png[] Since the user lacks authorization, the xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`] which redirects to <<servlet-saml2login-sp-initiated-factory,the `<saml2:AuthnRequest>` generating endpoint>>, `Saml2WebSsoAuthenticationRequestFilter`.
+Or, if you've <<servlet-saml2login-relyingpartyregistrationrepository,configured more than one asserting party>>, it will first redirect to a picker page.
+
+image:{icondir}/number_4.png[] Next, the `Saml2WebSsoAuthenticationRequestFilter` creates, signs, serializes, and encodes a `<saml2:AuthnRequest>` using its configured <<servlet-saml2login-sp-initiated-factory,`Saml2AuthenticationRequestFactory`>>.
+
+image:{icondir}/number_5.png[] Then, the browser takes this `<saml2:AuthnRequest>` and presents it to the asserting party.
+The asserting party attempts to authentication the user.
+If successful, it will return a `<saml2:Response>` back to the browser.
+
+image:{icondir}/number_6.png[] The browser then POSTs the `<saml2:Response>` to the assertion consumer service endpoint.
+
+[[servlet-saml2login-authentication-saml2webssoauthenticationfilter]]
+.Authenticating a `<saml2:Response>`
+image::{figures}/saml2webssoauthenticationfilter.png[]
+
+The figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
+
+image:{icondir}/number_1.png[] When the browser submits a `<saml2:Response>` to the application, it <<servlet-saml2login-authenticate-responses, delegates to `Saml2WebSsoAuthenticationFilter`>>.
+This filter calls its configured `AuthenticationConverter` to create a `Saml2AuthenticationToken` by extracting the response from the `HttpServletRequest`.
+This converter additionally resolves the <<servlet-saml2login-relyingpartyregistration, `RelyingPartyRegistration`>> and supplies it to `Saml2AuthenticationToken`.
+
+image:{icondir}/number_2.png[] Next, the filter passes the token to its configured xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`AuthenticationManager`].
+By default, it will use the <<servlet-saml2login-architecture,`OpenSAML authentication provider`>>.
+
+image:{icondir}/number_3.png[] If authentication fails, then __Failure__
+
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`] is cleared out.
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is invoked to restart the authentication process.
+
+image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
+
+* The xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[ `Authentication`] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`].
+* The `Saml2WebSsoAuthenticationFilter` invokes `FilterChain#doFilter(request,response)` to continue with the rest of the application logic.
+
+[[servlet-saml2login-minimaldependencies]]
+=== Minimal Dependencies
+
+SAML 2.0 service provider support resides in `spring-security-saml2-service-provider`.
+It builds off of the OpenSAML library.
+
+[[servlet-saml2login-minimalconfiguration]]
+=== Minimal Configuration
+
+When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a service provider consists of two basic steps.
+First, include the needed dependencies and second, indicate the necessary asserting party metadata.
+
+[NOTE]
+Also, this presupposes that you've already <<servlet-saml2login-metadata, registered the relying party with your asserting party>>.
+
+==== Specifying Identity Provider Metadata
+
+In a Spring Boot application, to specify an identity provider's metadata, simply do:
+
+[source,yml]
+----
+spring:
+  security:
+    saml2:
+      relyingparty:
+        registration:
+          adfs:
+            identityprovider:
+              entity-id: https://idp.example.com/issuer
+              verification.credentials:
+                - certificate-location: "classpath:idp.crt"
+              singlesignon.url: https://idp.example.com/issuer/sso
+              singlesignon.sign-request: false
+----
+
+where
+
+* `https://idp.example.com/issuer` is the value contained in the `Issuer` attribute of the SAML responses that the identity provider will issue
+* `classpath:idp.crt` is the location on the classpath for the identity provider's certificate for verifying SAML responses, and
+* `https://idp.example.com/issuer/sso` is the endpoint where the identity provider is expecting `AuthnRequest` s.
+
+And that's it!
+
+[NOTE]
+Identity Provider and Asserting Party are synonymous, as are Service Provider and Relying Party.
+These are frequently abbreviated as AP and RP, respectively.
+
+==== Runtime Expectations
+
+As configured above, the application processes any `+POST /login/saml2/sso/{registrationId}+` request containing a `SAMLResponse` parameter:
+
+[source,html]
+----
+POST /login/saml2/sso/adfs HTTP/1.1
+
+SAMLResponse=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZ...
+----
+
+There are two ways to see induce your asserting party to generate a `SAMLResponse`:
+
+* First, you can navigate to your asserting party.
+It likely has some kind of link or button for each registered relying party that you can click to send the `SAMLResponse`.
+* Second, you can navigate to a protected page in your app, for example, `http://localhost:8080`.
+Your app then redirects to the configured asserting party which then sends the `SAMLResponse`.
+
+From here, consider jumping to:
+
+* <<servlet-saml2login-architecture,How SAML 2.0 Login Integrates with OpenSAML>>
+* <<servlet-saml2login-authenticatedprincipal,How to Use the `Saml2AuthenticatedPrincipal`>>
+* <<servlet-saml2login-sansboot,How to Override or Replace Spring Boot's Auto Configuration>>
+
+[[servlet-saml2login-architecture]]
+=== How SAML 2.0 Login Integrates with OpenSAML
+
+Spring Security's SAML 2.0 support has a couple of design goals:
+
+* First, rely on a library for SAML 2.0 operations and domain objects.
+To achieve this, Spring Security uses OpenSAML.
+* Second, ensure this library is not required when using Spring Security's SAML support.
+To achieve this, any interfaces or classes where Spring Security uses OpenSAML in the contract remain encapsulated.
+This makes it possible for you to switch out OpenSAML for some other library or even an unsupported version of OpenSAML.
+
+As a natural outcome of the above two goals, Spring Security's SAML API is quite small relative to other modules.
+Instead, classes like `OpenSaml4AuthenticationRequestFactory` and `OpenSaml4AuthenticationProvider` expose `Converter` s that customize various steps in the authentication process.
+
+For example, once your application receives a `SAMLResponse` and delegates to `Saml2WebSsoAuthenticationFilter`, the filter will delegate to `OpenSaml4AuthenticationProvider`.
+
+[NOTE]
+For backward compatibility, Spring Security will use the latest OpenSAML 3 by default.
+Note, though that OpenSAML 3 has reached it's end-of-life and updating to OpenSAML 4.x is recommended.
+For that reason, Spring Security supports both OpenSAML 3.x and 4.x.
+If you manage your OpenSAML dependency to 4.x, then Spring Security will select its OpenSAML 4.x implementations.
+
+.Authenticating an OpenSAML `Response`
+image:{figures}/opensamlauthenticationprovider.png[]
+
+This figure builds off of the <<servlet-saml2login-authentication-saml2webssoauthenticationfilter,`Saml2WebSsoAuthenticationFilter` diagram>>.
+
+image:{icondir}/number_1.png[] The `Saml2WebSsoAuthenticationFilter` formulates the `Saml2AuthenticationToken` and invokes the xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`AuthenticationManager`].
+
+image:{icondir}/number_2.png[] The xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`AuthenticationManager`] invokes the OpenSAML authentication provider.
+
+image:{icondir}/number_3.png[] The authentication provider deserializes the response into an OpenSAML `Response` and checks its signature.
+If the signature is invalid, authentication fails.
+
+image:{icondir}/number_4.png[] Then, the provider <<servlet-saml2login-opensamlauthenticationprovider-decryption,decrypts any `EncryptedAssertion` elements>>.
+If any decryptions fail, authentication fails.
+
+image:{icondir}/number_5.png[] Next, the provider validates the response's `Issuer` and `Destination` values.
+If they don't match what's in the `RelyingPartyRegistration`, authentication fails.
+
+image:{icondir}/number_6.png[] After that, the provider verifies the signature of each `Assertion`.
+If any signature is invalid, authentication fails.
+Also, if neither the response nor the assertions have signatures, authentication fails.
+Either the response or all the assertions must have signatures.
+
+image:{icondir}/number_7.png[] Then, the provider <<servlet-saml2login-opensamlauthenticationprovider-decryption,decrypts any `EncryptedID` or `EncryptedAttribute` elements>>.
+If any decryptions fail, authentication fails.
+
+image:{icondir}/number_8.png[] Next, the provider validates each assertion's `ExpiresAt` and `NotBefore` timestamps, the `<Subject>` and any `<AudienceRestriction>` conditions.
+If any validations fail, authentication fails.
+
+image:{icondir}/number_9.png[] Following that, the provider takes the first assertion's `AttributeStatement` and maps it to a `Map<String, List<Object>>`.
+It also grants the `ROLE_USER` granted authority.
+
+image:{icondir}/number_10.png[] And finally, it takes the `NameID` from the first assertion, the `Map` of attributes, and the `GrantedAuthority` and constructs a `Saml2AuthenticatedPrincipal`.
+Then, it places that principal and the authorities into a `Saml2Authentication`.
+
+The resulting `Authentication#getPrincipal` is a Spring Security `Saml2AuthenticatedPrincipal` object, and `Authentication#getName` maps to the first assertion's `NameID` element.
+
+[[servlet-saml2login-opensaml-customization]]
+==== Customizing OpenSAML Configuration
+
+Any class that uses both Spring Security and OpenSAML should statically initialize `OpenSamlInitializationService` at the beginning of the class, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+static {
+	OpenSamlInitializationService.initialize();
+}
+----
+
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+companion object {
+    init {
+        OpenSamlInitializationService.initialize()
+    }
+}
+----
+====
+
+This replaces OpenSAML's `InitializationService#initialize`.
+
+Occasionally, it can be valuable to customize how OpenSAML builds, marshalls, and unmarshalls SAML objects.
+In these circumstances, you may instead want to call `OpenSamlInitializationService#requireInitialize(Consumer)` that gives you access to OpenSAML's `XMLObjectProviderFactory`.
+
+For example, when sending an unsigned AuthNRequest, you may want to force reauthentication.
+In that case, you can register your own `AuthnRequestMarshaller`, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+static {
+    OpenSamlInitializationService.requireInitialize(factory -> {
+        AuthnRequestMarshaller marshaller = new AuthnRequestMarshaller() {
+            @Override
+            public Element marshall(XMLObject object, Element element) throws MarshallingException {
+                configureAuthnRequest((AuthnRequest) object);
+                return super.marshall(object, element);
+            }
+
+            public Element marshall(XMLObject object, Document document) throws MarshallingException {
+                configureAuthnRequest((AuthnRequest) object);
+                return super.marshall(object, document);
+            }
+
+            private void configureAuthnRequest(AuthnRequest authnRequest) {
+                authnRequest.setForceAuthn(true);
+            }
+        }
+
+        factory.getMarshallerFactory().registerMarshaller(AuthnRequest.DEFAULT_ELEMENT_NAME, marshaller);
+    });
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+companion object {
+    init {
+        OpenSamlInitializationService.requireInitialize {
+            val marshaller = object : AuthnRequestMarshaller() {
+                override fun marshall(xmlObject: XMLObject, element: Element): Element {
+                    configureAuthnRequest(xmlObject as AuthnRequest)
+                    return super.marshall(xmlObject, element)
+                }
+
+                override fun marshall(xmlObject: XMLObject, document: Document): Element {
+                    configureAuthnRequest(xmlObject as AuthnRequest)
+                    return super.marshall(xmlObject, document)
+                }
+
+                private fun configureAuthnRequest(authnRequest: AuthnRequest) {
+                    authnRequest.isForceAuthn = true
+                }
+            }
+            it.marshallerFactory.registerMarshaller(AuthnRequest.DEFAULT_ELEMENT_NAME, marshaller)
+        }
+    }
+}
+----
+====
+
+The `requireInitialize` method may only be called once per application instance.
+
+[[servlet-saml2login-sansboot]]
+=== Overriding or Replacing Boot Auto Configuration
+
+There are two `@Bean` s that Spring Boot generates for a relying party.
+
+The first is a `WebSecurityConfigurerAdapter` that configures the app as a relying party.
+When including `spring-security-saml2-service-provider`, the `WebSecurityConfigurerAdapter` looks like:
+
+.Default JWT Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+protected void configure(HttpSecurity http) {
+    http
+        .authorizeRequests(authorize -> authorize
+            .anyRequest().authenticated()
+        )
+        .saml2Login(withDefaults());
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+fun configure(http: HttpSecurity) {
+    http {
+        authorizeRequests {
+            authorize(anyRequest, authenticated)
+        }
+        saml2Login { }
+    }
+}
+----
+====
+
+If the application doesn't expose a `WebSecurityConfigurerAdapter` bean, then Spring Boot will expose the above default one.
+
+You can replace this by exposing the bean within the application:
+
+.Custom SAML 2.0 Login Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebSecurity
+public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests(authorize -> authorize
+                .mvcMatchers("/messages/**").hasAuthority("ROLE_USER")
+                .anyRequest().authenticated()
+            )
+            .saml2Login(withDefaults());
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebSecurity
+class MyCustomSecurityConfiguration : WebSecurityConfigurerAdapter() {
+    override fun configure(http: HttpSecurity) {
+        http {
+            authorizeRequests {
+                authorize("/messages/**", hasAuthority("ROLE_USER"))
+                authorize(anyRequest, authenticated)
+            }
+            saml2Login {
+            }
+        }
+    }
+}
+----
+====
+
+The above requires the role of `USER` for any URL that starts with `/messages/`.
+
+[[servlet-saml2login-relyingpartyregistrationrepository]]
+The second `@Bean` Spring Boot creates is a {security-api-url}org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistrationRepository.html[`RelyingPartyRegistrationRepository`], which represents the asserting party and relying party metadata.
+This includes things like the location of the SSO endpoint the relying party should use when requesting authentication from the asserting party.
+
+You can override the default by publishing your own `RelyingPartyRegistrationRepository` bean.
+For example, you can look up the asserting party's configuration by hitting its metadata endpoint like so:
+
+.Relying Party Registration Repository
+====
+.Java
+[source,java,role="primary"]
+----
+@Value("${metadata.location}")
+String assertingPartyMetadataLocation;
+
+@Bean
+public RelyingPartyRegistrationRepository relyingPartyRegistrations() {
+    RelyingPartyRegistration registration = RelyingPartyRegistrations
+            .fromMetadataLocation(assertingPartyMetadataLocation)
+            .registrationId("example")
+            .build();
+    return new InMemoryRelyingPartyRegistrationRepository(registration);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Value("\${metadata.location}")
+var assertingPartyMetadataLocation: String? = null
+
+@Bean
+open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository? {
+    val registration = RelyingPartyRegistrations
+        .fromMetadataLocation(assertingPartyMetadataLocation)
+        .registrationId("example")
+        .build()
+    return InMemoryRelyingPartyRegistrationRepository(registration)
+}
+----
+====
+
+Or you can provide each detail manually, as you can see below:
+
+.Relying Party Registration Repository Manual Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Value("${verification.key}")
+File verificationKey;
+
+@Bean
+public RelyingPartyRegistrationRepository relyingPartyRegistrations() throws Exception {
+    X509Certificate certificate = X509Support.decodeCertificate(this.verificationKey);
+    Saml2X509Credential credential = Saml2X509Credential.verification(certificate);
+    RelyingPartyRegistration registration = RelyingPartyRegistration
+            .withRegistrationId("example")
+            .assertingPartyDetails(party -> party
+                .entityId("https://idp.example.com/issuer")
+                .singleSignOnServiceLocation("https://idp.example.com/SSO.saml2")
+                .wantAuthnRequestsSigned(false)
+                .verificationX509Credentials(c -> c.add(credential))
+            )
+            .build();
+    return new InMemoryRelyingPartyRegistrationRepository(registration);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Value("\${verification.key}")
+var verificationKey: File? = null
+
+@Bean
+open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository {
+    val certificate: X509Certificate? = X509Support.decodeCertificate(verificationKey!!)
+    val credential: Saml2X509Credential = Saml2X509Credential.verification(certificate)
+    val registration = RelyingPartyRegistration
+        .withRegistrationId("example")
+        .assertingPartyDetails { party: AssertingPartyDetails.Builder ->
+            party
+                .entityId("https://idp.example.com/issuer")
+                .singleSignOnServiceLocation("https://idp.example.com/SSO.saml2")
+                .wantAuthnRequestsSigned(false)
+                .verificationX509Credentials { c: MutableCollection<Saml2X509Credential?> ->
+                    c.add(
+                        credential
+                    )
+                }
+        }
+        .build()
+    return InMemoryRelyingPartyRegistrationRepository(registration)
+}
+----
+====
+
+[NOTE]
+Note that `X509Support` is an OpenSAML class, used here in the snippet for brevity
+
+[[servlet-saml2login-relyingpartyregistrationrepository-dsl]]
+
+Alternatively, you can directly wire up the repository using the DSL, which will also override the auto-configured `WebSecurityConfigurerAdapter`:
+
+.Custom Relying Party Registration DSL
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebSecurity
+public class MyCustomSecurityConfiguration extends WebSecurityConfigurerAdapter {
+    protected void configure(HttpSecurity http) {
+        http
+            .authorizeRequests(authorize -> authorize
+                .mvcMatchers("/messages/**").hasAuthority("ROLE_USER")
+                .anyRequest().authenticated()
+            )
+            .saml2Login(saml2 -> saml2
+                .relyingPartyRegistrationRepository(relyingPartyRegistrations())
+            );
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebSecurity
+class MyCustomSecurityConfiguration : WebSecurityConfigurerAdapter() {
+    override fun configure(http: HttpSecurity) {
+        http {
+            authorizeRequests {
+                authorize("/messages/**", hasAuthority("ROLE_USER"))
+                authorize(anyRequest, authenticated)
+            }
+            saml2Login {
+                relyingPartyRegistrationRepository = relyingPartyRegistrations()
+            }
+        }
+    }
+}
+----
+====
+
+[NOTE]
+A relying party can be multi-tenant by registering more than one relying party in the `RelyingPartyRegistrationRepository`.
+
+[[servlet-saml2login-relyingpartyregistration]]
+=== RelyingPartyRegistration
+A {security-api-url}org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.html[`RelyingPartyRegistration`]
+instance represents a link between an relying party and assering party's metadata.
+
+In a `RelyingPartyRegistration`, you can provide relying party metadata like its `Issuer` value, where it expects SAML Responses to be sent to, and any credentials that it owns for the purposes of signing or decrypting payloads.
+
+Also, you can provide asserting party metadata like its `Issuer` value, where it expects AuthnRequests to be sent to, and any public credentials that it owns for the purposes of the relying party verifying or encrypting payloads.
+
+The following `RelyingPartyRegistration` is the minimum required for most setups:
+
+====
+.Java
+[source,java,role="primary"]
+----
+RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations
+        .fromMetadataLocation("https://ap.example.org/metadata")
+        .registrationId("my-id")
+        .build();
+----
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val relyingPartyRegistration = RelyingPartyRegistrations
+    .fromMetadataLocation("https://ap.example.org/metadata")
+    .registrationId("my-id")
+    .build()
+----
+====
+
+Note that you can also create a `RelyingPartyRegistration` from an arbitrary `InputStream` source.
+One such example is when the metadata is stored in a database:
+
+[source,java]
+----
+String xml = fromDatabase();
+try (InputStream source = new ByteArrayInputStream(xml.getBytes())) {
+    RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations
+            .fromMetadata(source)
+            .registrationId("my-id")
+            .build();
+}
+----
+
+Though a more sophisticated setup is also possible, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("my-id")
+        .entityId("{baseUrl}/{registrationId}")
+        .decryptionX509Credentials(c -> c.add(relyingPartyDecryptingCredential()))
+        .assertionConsumerServiceLocation("/my-login-endpoint/{registrationId}")
+        .assertingPartyDetails(party -> party
+                .entityId("https://ap.example.org")
+                .verificationX509Credentials(c -> c.add(assertingPartyVerifyingCredential()))
+                .singleSignOnServiceLocation("https://ap.example.org/SSO.saml2")
+        )
+        .build();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val relyingPartyRegistration =
+    RelyingPartyRegistration.withRegistrationId("my-id")
+        .entityId("{baseUrl}/{registrationId}")
+        .decryptionX509Credentials { c: MutableCollection<Saml2X509Credential?> ->
+            c.add(relyingPartyDecryptingCredential())
+        }
+        .assertionConsumerServiceLocation("/my-login-endpoint/{registrationId}")
+        .assertingPartyDetails { party -> party
+                .entityId("https://ap.example.org")
+                .verificationX509Credentials { c -> c.add(assertingPartyVerifyingCredential()) }
+                .singleSignOnServiceLocation("https://ap.example.org/SSO.saml2")
+        }
+        .build()
+----
+====
+
+[TIP]
+The top-level metadata methods are details about the relying party.
+The methods inside `assertingPartyDetails` are details about the asserting party.
+
+[NOTE]
+The location where a relying party is expecting SAML Responses is the Assertion Consumer Service Location.
+
+The default for the relying party's `entityId` is `+{baseUrl}/saml2/service-provider-metadata/{registrationId}+`.
+This is this value needed when configuring the asserting party to know about your relying party.
+
+The default for the `assertionConsumerServiceLocation` is `+/login/saml2/sso/{registrationId}+`.
+It's mapped by default to <<servlet-saml2login-authentication-saml2webssoauthenticationfilter,`Saml2WebSsoAuthenticationFilter`>> in the filter chain.
+
+[[servlet-saml2login-rpr-uripatterns]]
+==== URI Patterns
+
+You probably noticed in the above examples the `+{baseUrl}+` and `+{registrationId}+` placeholders.
+
+These are useful for generating URIs. As such, the relying party's `entityId` and `assertionConsumerServiceLocation` support the following placeholders:
+
+* `baseUrl` - the scheme, host, and port of a deployed application
+* `registrationId` - the registration id for this relying party
+* `baseScheme` - the scheme of a deployed application
+* `baseHost` - the host of a deployed application
+* `basePort` - the port of a deployed application
+
+For example, the `assertionConsumerServiceLocation` defined above was:
+
+`+/my-login-endpoint/{registrationId}+`
+
+which in a deployed application would translate to
+
+`+/my-login-endpoint/adfs+`
+
+The `entityId` above was defined as:
+
+`+{baseUrl}/{registrationId}+`
+
+which in a deployed application would translate to
+
+`+https://rp.example.com/adfs+`
+
+[[servlet-saml2login-rpr-credentials]]
+==== Credentials
+
+You also likely noticed the credential that was used.
+
+Oftentimes, a relying party will use the same key to sign payloads as well as decrypt them.
+Or it will use the same key to verify payloads as well as encrypt them.
+
+Because of this, Spring Security ships with `Saml2X509Credential`, a SAML-specific credential that simplifies configuring the same key for different use cases.
+
+At a minimum, it's necessary to have a certificate from the asserting party so that the asserting party's signed responses can be verified.
+
+To construct a `Saml2X509Credential` that you'll use to verify assertions from the asserting party, you can load the file and use
+the `CertificateFactory` like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+Resource resource = new ClassPathResource("ap.crt");
+try (InputStream is = resource.getInputStream()) {
+    X509Certificate certificate = (X509Certificate)
+            CertificateFactory.getInstance("X.509").generateCertificate(is);
+    return Saml2X509Credential.verification(certificate);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val resource = ClassPathResource("ap.crt")
+resource.inputStream.use {
+    return Saml2X509Credential.verification(
+        CertificateFactory.getInstance("X.509").generateCertificate(it) as X509Certificate?
+    )
+}
+----
+====
+
+Let's say that the asserting party is going to also encrypt the assertion.
+In that case, the relying party will need a private key to be able to decrypt the encrypted value.
+
+In that case, you'll need an `RSAPrivateKey` as well as its corresponding `X509Certificate`.
+You can load the first using Spring Security's `RsaKeyConverters` utility class and the second as you did before:
+
+====
+.Java
+[source,java,role="primary"]
+----
+X509Certificate certificate = relyingPartyDecryptionCertificate();
+Resource resource = new ClassPathResource("rp.crt");
+try (InputStream is = resource.getInputStream()) {
+    RSAPrivateKey rsa = RsaKeyConverters.pkcs8().convert(is);
+    return Saml2X509Credential.decryption(rsa, certificate);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val certificate: X509Certificate = relyingPartyDecryptionCertificate()
+val resource = ClassPathResource("rp.crt")
+resource.inputStream.use {
+    val rsa: RSAPrivateKey = RsaKeyConverters.pkcs8().convert(it)
+    return Saml2X509Credential.decryption(rsa, certificate)
+}
+----
+====
+
+[TIP]
+When you specify the locations of these files as the appropriate Spring Boot properties, then Spring Boot will perform these conversions for you.
+
+[[servlet-saml2login-rpr-relyingpartyregistrationresolver]]
+==== Resolving the Relying Party from the Request
+
+As seen so far, Spring Security resolves the `RelyingPartyRegistration` by looking for the registration id in the URI path.
+
+There are a number of reasons you may want to customize. Among them:
+
+* You may know that you will never be a multi-tenant application and so want to have a simpler URL scheme
+* You may identify tenants in a way other than by the URI path
+
+To customize the way that a `RelyingPartyRegistration` is resolved, you can configure a custom `Converter<HttpServletRequest, RelyingPartyRegistration>`.
+The default looks up the registration id from the URI's last path element and looks it up in your `RelyingPartyRegistrationRepository`.
+
+You can provide a simpler resolver that, for example, always returns the same relying party:
+
+====
+.Java
+[source,java,role="primary"]
+----
+public class SingleRelyingPartyRegistrationResolver
+        implements Converter<HttpServletRequest, RelyingPartyRegistration> {
+
+    @Override
+    public RelyingPartyRegistration convert(HttpServletRequest request) {
+        return this.relyingParty;
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+class SingleRelyingPartyRegistrationResolver : Converter<HttpServletRequest?, RelyingPartyRegistration?> {
+    override fun convert(request: HttpServletRequest?): RelyingPartyRegistration? {
+        return this.relyingParty
+    }
+}
+----
+====
+
+Then, you can provide this resolver to the appropriate filters that <<servlet-saml2login-sp-initiated-factory, produce `<saml2:AuthnRequest>` s>>, <<servlet-saml2login-authenticate-responses, authenticate `<saml2:Response>` s>>, and <<servlet-saml2login-metadata, produce `<saml2:SPSSODescriptor>` metadata>>.
+
+[NOTE]
+Remember that if you have any placeholders in your `RelyingPartyRegistration`, your resolver implementation should resolve them.
+
+[[servlet-saml2login-rpr-duplicated]]
+==== Duplicated Relying Party Configurations
+
+When an application uses multiple asserting parties, some configuration is duplicated between `RelyingPartyRegistration` instances:
+
+* The relying party's `entityId`
+* Its `assertionConsumerServiceLocation`, and
+* Its credentials, for example its signing or decryption credentials
+
+What's nice about this setup is credentials may be more easily rotated for some identity providers vs others.
+
+The duplication can be alleviated in a few different ways.
+
+First, in YAML this can be alleviated with references, like so:
+
+[source,yaml]
+----
+spring:
+  security:
+    saml2:
+      relyingparty:
+        okta:
+          signing.credentials: &relying-party-credentials
+            - private-key-location: classpath:rp.key
+            - certificate-location: classpath:rp.crt
+          identityprovider:
+            entity-id: ...
+        azure:
+          signing.credentials: *relying-party-credentials
+          identityprovider:
+            entity-id: ...
+----
+
+Second, in a database, it's not necessary to replicate `RelyingPartyRegistration` 's model.
+
+Third, in Java, you can create a custom configuration method, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+private RelyingPartyRegistration.Builder
+        addRelyingPartyDetails(RelyingPartyRegistration.Builder builder) {
+
+    Saml2X509Credential signingCredential = ...
+    builder.signingX509Credentials(c -> c.addAll(signingCredential));
+    // ... other relying party configurations
+}
+
+@Bean
+public RelyingPartyRegistrationRepository relyingPartyRegistrations() {
+    RelyingPartyRegistration okta = addRelyingPartyDetails(
+            RelyingPartyRegistrations
+                .fromMetadataLocation(oktaMetadataUrl)
+                .registrationId("okta")).build();
+
+    RelyingPartyRegistration azure = addRelyingPartyDetails(
+            RelyingPartyRegistrations
+                .fromMetadataLocation(oktaMetadataUrl)
+                .registrationId("azure")).build();
+
+    return new InMemoryRelyingPartyRegistrationRepository(okta, azure);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+private fun addRelyingPartyDetails(builder: RelyingPartyRegistration.Builder): RelyingPartyRegistration.Builder {
+    val signingCredential: Saml2X509Credential = ...
+    builder.signingX509Credentials { c: MutableCollection<Saml2X509Credential?> ->
+        c.add(
+            signingCredential
+        )
+    }
+    // ... other relying party configurations
+}
+
+@Bean
+open fun relyingPartyRegistrations(): RelyingPartyRegistrationRepository? {
+    val okta = addRelyingPartyDetails(
+        RelyingPartyRegistrations
+            .fromMetadataLocation(oktaMetadataUrl)
+            .registrationId("okta")
+    ).build()
+    val azure = addRelyingPartyDetails(
+        RelyingPartyRegistrations
+            .fromMetadataLocation(oktaMetadataUrl)
+            .registrationId("azure")
+    ).build()
+    return InMemoryRelyingPartyRegistrationRepository(okta, azure)
+}
+----
+====
+
+[[servlet-saml2login-sp-initiated-factory]]
+=== Producing `<saml2:AuthnRequest>` s
+
+As stated earlier, Spring Security's SAML 2.0 support produces a `<saml2:AuthnRequest>` to commence authentication with the asserting party.
+
+Spring Security achieves this in part by registering the `Saml2WebSsoAuthenticationRequestFilter` in the filter chain.
+This filter by default responds to endpoint `+/saml2/authenticate/{registrationId}+`.
+
+For example, if you were deployed to `https://rp.example.com` and you gave your registration an ID of `okta`, you could navigate to:
+
+`https://rp.example.org/saml2/authenticate/ping`
+
+and the result would be a redirect that included a `SAMLRequest` parameter containing the signed, deflated, and encoded `<saml2:AuthnRequest>`.
+
+[[servlet-saml2login-sp-initiated-factory-signing]]
+==== Changing How the `<saml2:AuthnRequest>` Gets Sent
+
+By default, Spring Security signs each `<saml2:AuthnRequest>` and send it as a GET to the asserting party.
+
+Many asserting parties don't require a signed `<saml2:AuthnRequest>`.
+This can be configured automatically via `RelyingPartyRegistrations`, or you can supply it manually, like so:
+
+
+.Not Requiring Signed AuthnRequests
+====
+.Boot
+[source,yaml,role="primary"]
+----
+spring:
+  security:
+    saml2:
+      relyingparty:
+        okta:
+          identityprovider:
+            entity-id: ...
+            singlesignon.sign-request: false
+----
+
+.Java
+[source,java,role="secondary"]
+----
+RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("okta")
+        // ...
+        .assertingPartyDetails(party -> party
+            // ...
+            .wantAuthnRequestsSigned(false)
+        )
+        .build();
+----
+
+.Kotlin
+[source,java,role="secondary"]
+----
+var relyingPartyRegistration: RelyingPartyRegistration =
+    RelyingPartyRegistration.withRegistrationId("okta")
+        // ...
+        .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party
+                // ...
+                .wantAuthnRequestsSigned(false)
+        }
+        .build();
+----
+====
+
+Otherwise, you will need to specify a private key to `RelyingPartyRegistration#signingX509Credentials` so that Spring Security can sign the `<saml2:AuthnRequest>` before sending.
+
+[[servlet-saml2login-sp-initiated-factory-algorithm]]
+By default, Spring Security will sign the `<saml2:AuthnRequest>` using `rsa-sha256`, though some asserting parties will require a different algorithm, as indicated in their metadata.
+
+You can configure the algorithm based on the asserting party's <<servlet-saml2login-relyingpartyregistrationrepository,metadata using `RelyingPartyRegistrations`>>.
+
+Or, you can provide it manually:
+
+====
+.Java
+[source,java,role="primary"]
+----
+String metadataLocation = "classpath:asserting-party-metadata.xml";
+RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistrations.fromMetadataLocation(metadataLocation)
+        // ...
+        .assertingPartyDetails((party) -> party
+            // ...
+            .signingAlgorithms((sign) -> sign.add(SignatureConstants.ALGO_ID_SIGNATURE_RSA_SHA512))
+        )
+        .build();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+var metadataLocation = "classpath:asserting-party-metadata.xml"
+var relyingPartyRegistration: RelyingPartyRegistration =
+    RelyingPartyRegistrations.fromMetadataLocation(metadataLocation)
+        // ...
+        .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party
+                // ...
+                .signingAlgorithms { sign: MutableList<String?> ->
+                    sign.add(
+                        SignatureConstants.ALGO_ID_SIGNATURE_RSA_SHA512
+                    )
+                }
+        }
+        .build();
+----
+====
+
+NOTE: The snippet above uses the OpenSAML `SignatureConstants` class to supply the algorithm name.
+But, that's just for convenience.
+Since the datatype is `String`, you can supply the name of the algorithm directly.
+
+[[servlet-saml2login-sp-initiated-factory-binding]]
+Some asserting parties require that the `<saml2:AuthnRequest>` be POSTed.
+This can be configured automatically via `RelyingPartyRegistrations`, or you can supply it manually, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+RelyingPartyRegistration relyingPartyRegistration = RelyingPartyRegistration.withRegistrationId("okta")
+        // ...
+        .assertingPartyDetails(party -> party
+            // ...
+            .singleSignOnServiceBinding(Saml2MessageBinding.POST)
+        )
+        .build();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+var relyingPartyRegistration: RelyingPartyRegistration? =
+    RelyingPartyRegistration.withRegistrationId("okta")
+        // ...
+        .assertingPartyDetails { party: AssertingPartyDetails.Builder -> party
+            // ...
+            .singleSignOnServiceBinding(Saml2MessageBinding.POST)
+        }
+        .build()
+----
+====
+
+[[servlet-saml2login-sp-initiated-factory-custom-authnrequest]]
+==== Customizing OpenSAML's `AuthnRequest` Instance
+
+There are a number of reasons that you may want to adjust an `AuthnRequest`.
+For example, you may want `ForceAuthN` to be set to `true`, which Spring Security sets to `false` by default.
+
+If you don't need information from the `HttpServletRequest` to make your decision, then the easiest way is to <<servlet-saml2login-opensaml-customization,register a custom `AuthnRequestMarshaller` with OpenSAML>>.
+This will give you access to post-process the `AuthnRequest` instance before it's serialized.
+
+But, if you do need something from the request, then you can use create a custom `Saml2AuthenticationRequestContext` implementation and then a `Converter<Saml2AuthenticationRequestContext, AuthnRequest>` to build an `AuthnRequest` yourself, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Component
+public class AuthnRequestConverter implements
+        Converter<MySaml2AuthenticationRequestContext, AuthnRequest> {
+
+    private final AuthnRequestBuilder authnRequestBuilder;
+    private final IssuerBuilder issuerBuilder;
+
+    // ... constructor
+
+    public AuthnRequest convert(Saml2AuthenticationRequestContext context) {
+        MySaml2AuthenticationRequestContext myContext = (MySaml2AuthenticationRequestContext) context;
+        Issuer issuer = issuerBuilder.buildObject();
+        issuer.setValue(myContext.getIssuer());
+
+        AuthnRequest authnRequest = authnRequestBuilder.buildObject();
+        authnRequest.setIssuer(issuer);
+        authnRequest.setDestination(myContext.getDestination());
+        authnRequest.setAssertionConsumerServiceURL(myContext.getAssertionConsumerServiceUrl());
+
+        // ... additional settings
+
+        authRequest.setForceAuthn(myContext.getForceAuthn());
+        return authnRequest;
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Component
+class AuthnRequestConverter : Converter<MySaml2AuthenticationRequestContext, AuthnRequest> {
+    private val authnRequestBuilder: AuthnRequestBuilder? = null
+    private val issuerBuilder: IssuerBuilder? = null
+
+    // ... constructor
+    override fun convert(context: MySaml2AuthenticationRequestContext): AuthnRequest {
+        val myContext: MySaml2AuthenticationRequestContext = context
+        val issuer: Issuer = issuerBuilder.buildObject()
+        issuer.value = myContext.getIssuer()
+        val authnRequest: AuthnRequest = authnRequestBuilder.buildObject()
+        authnRequest.issuer = issuer
+        authnRequest.destination = myContext.getDestination()
+        authnRequest.assertionConsumerServiceURL = myContext.getAssertionConsumerServiceUrl()
+
+        // ... additional settings
+        authRequest.setForceAuthn(myContext.getForceAuthn())
+        return authnRequest
+    }
+}
+----
+====
+
+Then, you can construct your own `Saml2AuthenticationRequestContextResolver` and `Saml2AuthenticationRequestFactory` and publish them as `@Bean` s:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+Saml2AuthenticationRequestContextResolver authenticationRequestContextResolver() {
+    Saml2AuthenticationRequestContextResolver resolver =
+            new DefaultSaml2AuthenticationRequestContextResolver();
+    return request -> {
+        Saml2AuthenticationRequestContext context = resolver.resolve(request);
+        return new MySaml2AuthenticationRequestContext(context, request.getParameter("force") != null);
+    };
+}
+
+@Bean
+Saml2AuthenticationRequestFactory authenticationRequestFactory(
+        AuthnRequestConverter authnRequestConverter) {
+
+    OpenSaml4AuthenticationRequestFactory authenticationRequestFactory =
+            new OpenSaml4AuthenticationRequestFactory();
+    authenticationRequestFactory.setAuthenticationRequestContextConverter(authnRequestConverter);
+    return authenticationRequestFactory;
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+open fun authenticationRequestContextResolver(): Saml2AuthenticationRequestContextResolver {
+    val resolver: Saml2AuthenticationRequestContextResolver = DefaultSaml2AuthenticationRequestContextResolver()
+    return Saml2AuthenticationRequestContextResolver { request: HttpServletRequest ->
+        val context = resolver.resolve(request)
+        MySaml2AuthenticationRequestContext(
+            context,
+            request.getParameter("force") != null
+        )
+    }
+}
+
+@Bean
+open fun authenticationRequestFactory(
+    authnRequestConverter: AuthnRequestConverter?
+): Saml2AuthenticationRequestFactory? {
+    val authenticationRequestFactory = OpenSaml4AuthenticationRequestFactory()
+    authenticationRequestFactory.setAuthenticationRequestContextConverter(authnRequestConverter)
+    return authenticationRequestFactory
+}
+----
+====
+
+[[servlet-saml2login-authenticate-responses]]
+=== Authenticating `<saml2:Response>` s
+
+To verify SAML 2.0 Responses, Spring Security uses <<servlet-saml2login-architecture,`OpenSaml4AuthenticationProvider`>> by default.
+
+You can configure this in a number of ways including:
+
+1. Setting a clock skew to timestamp validation
+2. Mapping the response to a list of `GrantedAuthority` instances
+3. Customizing the strategy for validating assertions
+4. Customizing the strategy for decrypting response and assertion elements
+
+To configure these, you'll use the `saml2Login#authenticationManager` method in the DSL.
+
+[[servlet-saml2login-opensamlauthenticationprovider-clockskew]]
+==== Setting a Clock Skew
+
+It's not uncommon for the asserting and relying parties to have system clocks that aren't perfectly synchronized.
+For that reason, you can configure `OpenSaml4AuthenticationProvider` 's default assertion validator with some tolerance:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebSecurity
+public class SecurityConfig extends WebSecurityConfigurerAdapter {
+
+    @Override
+    protected void configure(HttpSecurity http) throws Exception {
+        OpenSaml4AuthenticationProvider authenticationProvider = new OpenSaml4AuthenticationProvider();
+        authenticationProvider.setAssertionValidator(OpenSaml4AuthenticationProvider
+                .createDefaultAssertionValidator(assertionToken -> {
+                    Map<String, Object> params = new HashMap<>();
+                    params.put(CLOCK_SKEW, Duration.ofMinutes(10).toMillis());
+                    // ... other validation parameters
+                    return new ValidationContext(params);
+                })
+        );
+
+        http
+            .authorizeRequests(authz -> authz
+                .anyRequest().authenticated()
+            )
+            .saml2Login(saml2 -> saml2
+                .authenticationManager(new ProviderManager(authenticationProvider))
+            );
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebSecurity
+open class SecurityConfig : WebSecurityConfigurerAdapter() {
+    override fun configure(http: HttpSecurity) {
+        val authenticationProvider = OpenSaml4AuthenticationProvider()
+        authenticationProvider.setAssertionValidator(
+            OpenSaml4AuthenticationProvider
+                .createDefaultAssertionValidator(Converter<OpenSaml4AuthenticationProvider.AssertionToken, ValidationContext> {
+                    val params: MutableMap<String, Any> = HashMap()
+                    params[CLOCK_SKEW] =
+                        Duration.ofMinutes(10).toMillis()
+                    ValidationContext(params)
+                })
+        )
+        http {
+            authorizeRequests {
+                authorize(anyRequest, authenticated)
+            }
+            saml2Login {
+                authenticationManager = ProviderManager(authenticationProvider)
+            }
+        }
+    }
+}
+----
+====
+
+[[servlet-saml2login-opensamlauthenticationprovider-userdetailsservice]]
+==== Coordinating with a `UserDetailsService`
+
+Or, perhaps you would like to include user details from a legacy `UserDetailsService`.
+In that case, the response authentication converter can come in handy, as can be seen below:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebSecurity
+public class SecurityConfig extends WebSecurityConfigurerAdapter {
+    @Autowired
+    UserDetailsService userDetailsService;
+
+    @Override
+    protected void configure(HttpSecurity http) throws Exception {
+        OpenSaml4AuthenticationProvider authenticationProvider = new OpenSaml4AuthenticationProvider();
+        authenticationProvider.setResponseAuthenticationConverter(responseToken -> {
+            Saml2Authentication authentication = OpenSaml4AuthenticationProvider
+                    .createDefaultResponseAuthenticationConverter() <1>
+                    .convert(responseToken);
+            Assertion assertion = responseToken.getResponse().getAssertions().get(0);
+            String username = assertion.getSubject().getNameID().getValue();
+            UserDetails userDetails = this.userDetailsService.loadUserByUsername(username); <2>
+            return MySaml2Authentication(userDetails, authentication); <3>
+        });
+
+        http
+            .authorizeRequests(authz -> authz
+                .anyRequest().authenticated()
+            )
+            .saml2Login(saml2 -> saml2
+                .authenticationManager(new ProviderManager(authenticationProvider))
+            );
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebSecurity
+open class SecurityConfig : WebSecurityConfigurerAdapter() {
+    @Autowired
+    var userDetailsService: UserDetailsService? = null
+
+    override fun configure(http: HttpSecurity) {
+        val authenticationProvider = OpenSaml4AuthenticationProvider()
+        authenticationProvider.setResponseAuthenticationConverter { responseToken: OpenSaml4AuthenticationProvider.ResponseToken ->
+            val authentication = OpenSaml4AuthenticationProvider
+                .createDefaultResponseAuthenticationConverter() <1>
+                .convert(responseToken)
+            val assertion: Assertion = responseToken.response.assertions[0]
+            val username: String = assertion.subject.nameID.value
+            val userDetails = userDetailsService!!.loadUserByUsername(username) <2>
+            MySaml2Authentication(userDetails, authentication) <3>
+        }
+        http {
+            authorizeRequests {
+                authorize(anyRequest, authenticated)
+            }
+            saml2Login {
+                authenticationManager = ProviderManager(authenticationProvider)
+            }
+        }
+    }
+}
+----
+====
+<1> First, call the default converter, which extracts attributes and authorities from the response
+<2> Second, call the xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[ `UserDetailsService`] using the relevant information
+<3> Third, return a custom authentication that includes the user details
+
+[NOTE]
+It's not required to call `OpenSaml4AuthenticationProvider` 's default authentication converter.
+It returns a `Saml2AuthenticatedPrincipal` containing the attributes it extracted from `AttributeStatement` s as well as the single `ROLE_USER` authority.
+
+[[servlet-saml2login-opensamlauthenticationprovider-additionalvalidation]]
+==== Performing Additional Response Validation
+
+`OpenSaml4AuthenticationProvider` validates the `Issuer` and `Destination` values right after decrypting the `Response`.
+You can customize the validation by extending the default validator concatenating with your own response validator, or you can replace it entirely with yours.
+
+For example, you can throw a custom exception with any additional information available in the `Response` object, like so:
+[source,java]
+----
+OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider();
+provider.setResponseValidator((responseToken) -> {
+	Saml2ResponseValidatorResult result = OpenSamlAuthenticationProvider
+		.createDefaultResponseValidator()
+		.convert(responseToken)
+		.concat(myCustomValidator.convert(responseToken));
+	if (!result.getErrors().isEmpty()) {
+		String inResponseTo = responseToken.getInResponseTo();
+		throw new CustomSaml2AuthenticationException(result, inResponseTo);
+	}
+	return result;
+});
+----
+
+==== Performing Additional Assertion Validation
+`OpenSaml4AuthenticationProvider` performs minimal validation on SAML 2.0 Assertions.
+After verifying the signature, it will:
+
+1. Validate `<AudienceRestriction>` and `<DelegationRestriction>` conditions
+2. Validate `<SubjectConfirmation>` s, expect for any IP address information
+
+To perform additional validation, you can configure your own assertion validator that delegates to `OpenSaml4AuthenticationProvider` 's default and then performs its own.
+
+[[servlet-saml2login-opensamlauthenticationprovider-onetimeuse]]
+For example, you can use OpenSAML's `OneTimeUseConditionValidator` to also validate a `<OneTimeUse>` condition, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider();
+OneTimeUseConditionValidator validator = ...;
+provider.setAssertionValidator(assertionToken -> {
+    Saml2ResponseValidatorResult result = OpenSaml4AuthenticationProvider
+            .createDefaultAssertionValidator()
+            .convert(assertionToken);
+    Assertion assertion = assertionToken.getAssertion();
+    OneTimeUse oneTimeUse = assertion.getConditions().getOneTimeUse();
+    ValidationContext context = new ValidationContext();
+    try {
+        if (validator.validate(oneTimeUse, assertion, context) == ValidationResult.VALID) {
+            return result;
+        }
+    } catch (Exception e) {
+        return result.concat(new Saml2Error(INVALID_ASSERTION, e.getMessage()));
+    }
+    return result.concat(new Saml2Error(INVALID_ASSERTION, context.getValidationFailureMessage()));
+});
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+var provider = OpenSaml4AuthenticationProvider()
+var validator: OneTimeUseConditionValidator = ...
+provider.setAssertionValidator { assertionToken ->
+    val result = OpenSaml4AuthenticationProvider
+        .createDefaultAssertionValidator()
+        .convert(assertionToken)
+    val assertion: Assertion = assertionToken.assertion
+    val oneTimeUse: OneTimeUse = assertion.conditions.oneTimeUse
+    val context = ValidationContext()
+    try {
+        if (validator.validate(oneTimeUse, assertion, context) == ValidationResult.VALID) {
+            return@setAssertionValidator result
+        }
+    } catch (e: Exception) {
+        return@setAssertionValidator result.concat(Saml2Error(INVALID_ASSERTION, e.message))
+    }
+    result.concat(Saml2Error(INVALID_ASSERTION, context.validationFailureMessage))
+}
+----
+====
+
+[NOTE]
+While recommended, it's not necessary to call `OpenSaml4AuthenticationProvider` 's default assertion validator.
+A circumstance where you would skip it would be if you don't need it to check the `<AudienceRestriction>` or the `<SubjectConfirmation>` since you are doing those yourself.
+
+[[servlet-saml2login-opensamlauthenticationprovider-decryption]]
+==== Customizing Decryption
+
+Spring Security decrypts `<saml2:EncryptedAssertion>`, `<saml2:EncryptedAttribute>`, and `<saml2:EncryptedID>` elements automatically by using the decryption <<servlet-saml2login-rpr-credentials,`Saml2X509Credential` instances>> registered in the <<servlet-saml2login-relyingpartyregistration,`RelyingPartyRegistration`>>.
+
+`OpenSaml4AuthenticationProvider` exposes <<servlet-saml2login-architecture,two decryption strategies>>.
+The response decrypter is for decrypting encrypted elements of the `<saml2:Response>`, like `<saml2:EncryptedAssertion>`.
+The assertion decrypter is for decrypting encrypted elements of the `<saml2:Assertion>`, like `<saml2:EncryptedAttribute>` and `<saml2:EncryptedID>`.
+
+You can replace `OpenSaml4AuthenticationProvider`'s default decryption strategy with your own.
+For example, if you have a separate service that decrypts the assertions in a `<saml2:Response>`, you can use it instead like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+MyDecryptionService decryptionService = ...;
+OpenSaml4AuthenticationProvider provider = new OpenSaml4AuthenticationProvider();
+provider.setResponseElementsDecrypter((responseToken) -> decryptionService.decrypt(responseToken.getResponse()));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val decryptionService: MyDecryptionService = ...
+val provider = OpenSaml4AuthenticationProvider()
+provider.setResponseElementsDecrypter { responseToken -> decryptionService.decrypt(responseToken.response) }
+----
+====
+
+If you are also decrypting individual elements in a `<saml2:Assertion>`, you can customize the assertion decrypter, too:
+
+====
+.Java
+[source,java,role="primary"]
+----
+provider.setAssertionElementsDecrypter((assertionToken) -> decryptionService.decrypt(assertionToken.getAssertion()));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+provider.setAssertionElementsDecrypter { assertionToken -> decryptionService.decrypt(assertionToken.assertion) }
+----
+====
+
+NOTE: There are two separate decrypters since assertions can be signed separately from responses.
+Trying to decrypt a signed assertion's elements before signature verification may invalidate the signature.
+If your asserting party signs the response only, then it's safe to decrypt all elements using only the response decrypter.
+
+[[servlet-saml2login-authenticationmanager-custom]]
+==== Using a Custom Authentication Manager
+
+[[servlet-saml2login-opensamlauthenticationprovider-authenticationmanager]]
+Of course, the `authenticationManager` DSL method can be also used to perform a completely custom SAML 2.0 authentication.
+This authentication manager should expect a `Saml2AuthenticationToken` object containing the SAML 2.0 Response XML data.
+
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebSecurity
+public class SecurityConfig extends WebSecurityConfigurerAdapter {
+
+    @Override
+    protected void configure(HttpSecurity http) throws Exception {
+        AuthenticationManager authenticationManager = new MySaml2AuthenticationManager(...);
+        http
+            .authorizeRequests(authorize -> authorize
+                .anyRequest().authenticated()
+            )
+            .saml2Login(saml2 -> saml2
+                .authenticationManager(authenticationManager)
+            )
+        ;
+    }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebSecurity
+open class SecurityConfig : WebSecurityConfigurerAdapter() {
+    override fun configure(http: HttpSecurity) {
+        val customAuthenticationManager: AuthenticationManager = MySaml2AuthenticationManager(...)
+        http {
+            authorizeRequests {
+                authorize(anyRequest, authenticated)
+            }
+            saml2Login {
+                authenticationManager = customAuthenticationManager
+            }
+        }
+    }
+}
+----
+====
+
+[[servlet-saml2login-authenticatedprincipal]]
+=== Using `Saml2AuthenticatedPrincipal`
+
+With the relying party correctly configured for a given asserting party, it's ready to accept assertions.
+Once the relying party validates an assertion, the result is a `Saml2Authentication` with a `Saml2AuthenticatedPrincipal`.
+
+This means that you can access the principal in your controller like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Controller
+public class MainController {
+	@GetMapping("/")
+	public String index(@AuthenticationPrincipal Saml2AuthenticatedPrincipal principal, Model model) {
+		String email = principal.getFirstAttribute("email");
+		model.setAttribute("email", email);
+		return "index";
+	}
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Controller
+class MainController {
+    @GetMapping("/")
+    fun index(@AuthenticationPrincipal principal: Saml2AuthenticatedPrincipal, model: Model): String {
+        val email = principal.getFirstAttribute<String>("email")
+        model.setAttribute("email", email)
+        return "index"
+    }
+}
+----
+====
+
+[TIP]
+Because the SAML 2.0 specification allows for each attribute to have multiple values, you can either call `getAttribute` to get the list of attributes or `getFirstAttribute` to get the first in the list.
+`getFirstAttribute` is quite handy when you know that there is only one value.
+
+[[servlet-saml2login-metadata]]
+=== Producing `<saml2:SPSSODescriptor>` Metadata
+
+You can publish a metadata endpoint by adding the `Saml2MetadataFilter` to the filter chain, as you'll see below:
+
+====
+.Java
+[source,java,role="primary"]
+----
+Converter<HttpServletRequest, RelyingPartyRegistration> relyingPartyRegistrationResolver =
+        new DefaultRelyingPartyRegistrationResolver(this.relyingPartyRegistrationRepository);
+Saml2MetadataFilter filter = new Saml2MetadataFilter(
+        relyingPartyRegistrationResolver,
+        new OpenSamlMetadataResolver());
+
+http
+    // ...
+    .saml2Login(withDefaults())
+    .addFilterBefore(filter, Saml2WebSsoAuthenticationFilter.class);
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val relyingPartyRegistrationResolver: Converter<HttpServletRequest, RelyingPartyRegistration> =
+    DefaultRelyingPartyRegistrationResolver(this.relyingPartyRegistrationRepository)
+val filter = Saml2MetadataFilter(
+    relyingPartyRegistrationResolver,
+    OpenSamlMetadataResolver()
+)
+
+http {
+    //...
+    saml2Login { }
+    addFilterBefore<Saml2WebSsoAuthenticationFilter>(filter)
+}
+----
+====
+
+You can use this metadata endpoint to register your relying party with your asserting party.
+This is often as simple as finding the correct form field to supply the metadata endpoint.
+
+By default, the metadata endpoint is `+/saml2/service-provider-metadata/{registrationId}+`.
+You can change this by calling the `setRequestMatcher` method on the filter:
+
+====
+.Java
+[source,java,role="primary"]
+----
+filter.setRequestMatcher(new AntPathRequestMatcher("/saml2/metadata/{registrationId}", "GET"));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+filter.setRequestMatcher(AntPathRequestMatcher("/saml2/metadata/{registrationId}", "GET"))
+----
+====
+
+ensuring that the `registrationId` hint is at the end of the path.
+
+Or, if you have registered a custom relying party registration resolver in the constructor, then you can specify a path without a `registrationId` hint, like so:
+
+====
+.Java
+[source,java,role="primary"]
+----
+filter.setRequestMatcher(new AntPathRequestMatcher("/saml2/metadata", "GET"));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+filter.setRequestMatcher(AntPathRequestMatcher("/saml2/metadata", "GET"))
+----
+====
+
+[[servlet-saml2login-logout]]
+=== Performing Single Logout
+
+Spring Security does not yet support single logout.
+
+Generally speaking, though, you can achieve this by creating and registering a custom `LogoutSuccessHandler` and `RequestMatcher`:
+
+====
+.Java
+[source,java,role="primary"]
+----
+http
+    // ...
+    .logout(logout -> logout
+        .logoutSuccessHandler(myCustomSuccessHandler())
+        .logoutRequestMatcher(myRequestMatcher())
+    )
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+http {
+    logout {
+        // ...
+        logoutSuccessHandler = myCustomSuccessHandler()
+        logoutRequestMatcher = myRequestMatcher()
+    }
+}
+----
+====
+
+The success handler will send logout requests to the asserting party.
+
+The request matcher will detect logout requests from the asserting party.
+
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc
similarity index 100%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc
rename to docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc
diff --git a/docs/modules/ROOT/pages/servlet/test/index.adoc b/docs/modules/ROOT/pages/servlet/test/index.adoc
new file mode 100644
index 0000000000..c6597e2aa8
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/test/index.adoc
@@ -0,0 +1,11 @@
+[[test]]
+= Testing
+
+This section describes the testing support provided by Spring Security.
+
+To use the Spring Security test support, you must include `spring-security-test-{spring-security-version}.jar` as a dependency of your project.
+
+At a high level Spring Security's test support provides integration for:
+
+* xref:servlet/test/method.adoc[Method Security] - provides test support for Spring Security's method security.
+* xref:servlet/test/mockmvc.adoc[MockMvc] - Provides test support to integrate with Spring's `MockMvc`.
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/test/method.adoc b/docs/modules/ROOT/pages/servlet/test/method.adoc
similarity index 99%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/test/method.adoc
rename to docs/modules/ROOT/pages/servlet/test/method.adoc
index 82a2f9ceb9..e5e639464e 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/test/method.adoc
+++ b/docs/modules/ROOT/pages/servlet/test/method.adoc
@@ -1,5 +1,5 @@
 [[test-method]]
-== Testing Method Security
+= Testing Method Security
 
 This section demonstrates how to use Spring Security's Test support to test method based security.
 We first introduce a `MessageService` that requires the user to be authenticated in order to access it.
@@ -41,7 +41,7 @@ Hello org.springframework.security.authentication.UsernamePasswordAuthentication
 ----
 
 [[test-method-setup]]
-=== Security Test Setup
+== Security Test Setup
 
 Before we can use Spring Security Test support, we must perform some setup. An example can be seen below:
 
@@ -98,7 +98,7 @@ fun getMessageUnauthenticated() {
 ====
 
 [[test-method-withmockuser]]
-=== @WithMockUser
+== @WithMockUser
 
 The question is "How could we most easily run the test as a specific user?"
 The answer is to use `@WithMockUser`.
@@ -294,7 +294,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut
 
 
 [[test-method-withanonymoususer]]
-=== @WithAnonymousUser
+== @WithAnonymousUser
 
 Using `@WithAnonymousUser` allows running as an anonymous user.
 This is especially convenient when you wish to run most of your tests with a specific user, but want to run a few tests as an anonymous user.
@@ -358,7 +358,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut
 
 
 [[test-method-withuserdetails]]
-=== @WithUserDetails
+== @WithUserDetails
 
 While `@WithMockUser` is a very convenient way to get started, it may not work in all instances.
 For example, it is common for applications to expect that the `Authentication` principal be of a specific type.
@@ -462,7 +462,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut
 
 
 [[test-method-withsecuritycontext]]
-=== @WithSecurityContext
+== @WithSecurityContext
 
 We have seen that `@WithMockUser` is an excellent choice if we are not using a custom `Authentication` principal.
 Next we discovered that `@WithUserDetails` would allow us to use a custom `UserDetailsService` to create our `Authentication` principal but required the user to exist.
@@ -596,7 +596,7 @@ You can change this to happen during the `TestExecutionListener.beforeTestExecut
 
 
 [[test-method-meta-annotations]]
-=== Test Meta Annotations
+== Test Meta Annotations
 
 If you reuse the same user within your tests often, it is not ideal to have to repeatedly specify the attributes.
 For example, if there are many tests related to an administrative user with the username "admin" and the roles `ROLE_USER` and `ROLE_ADMIN` you would have to write:
diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/test/mockmvc.adoc b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc
similarity index 96%
rename from docs/manual/src/docs/asciidoc/_includes/servlet/test/mockmvc.adoc
rename to docs/modules/ROOT/pages/servlet/test/mockmvc.adoc
index f28c866ae0..dd712ec6cf 100644
--- a/docs/manual/src/docs/asciidoc/_includes/servlet/test/mockmvc.adoc
+++ b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc
@@ -1,10 +1,10 @@
 [[test-mockmvc]]
-== Spring MVC Test Integration
+= Spring MVC Test Integration
 
 Spring Security provides comprehensive integration with https://docs.spring.io/spring/docs/current/spring-framework-reference/html/testing.html#spring-mvc-test-framework[Spring MVC Test]
 
 [[test-mockmvc-setup]]
-=== Setting Up MockMvc and Spring Security
+== Setting Up MockMvc and Spring Security
 
 In order to use Spring Security with Spring MVC Test it is necessary to add the Spring Security `FilterChainProxy` as a `Filter`.
 It is also necessary to add Spring Security's `TestSecurityContextHolderPostProcessor` to support <<Running as a User in Spring MVC Test with Annotations,Running as a User in Spring MVC Test with Annotations>>.
@@ -68,7 +68,7 @@ class CsrfShowcaseTests {
 <1> `SecurityMockMvcConfigurers.springSecurity()` will perform all of the initial setup we need to integrate Spring Security with Spring MVC Test
 
 [[test-mockmvc-smmrpp]]
-=== SecurityMockMvcRequestPostProcessors
+== SecurityMockMvcRequestPostProcessors
 
 Spring MVC Test provides a convenient interface called a `RequestPostProcessor` that can be used to modify a request.
 Spring Security provides a number of `RequestPostProcessor` implementations that make testing easier.
@@ -89,7 +89,7 @@ import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequ
 ====
 
 [[test-mockmvc-csrf]]
-==== Testing with CSRF Protection
+=== Testing with CSRF Protection
 
 When testing any non-safe HTTP methods and using Spring Security's CSRF protection, you must be sure to include a valid CSRF Token in the request.
 To specify a valid CSRF token as a request parameter using the following:
@@ -150,7 +150,7 @@ mvc.post("/") {
 ====
 
 [[test-mockmvc-securitycontextholder]]
-==== Running a Test as a User in Spring MVC Test
+=== Running a Test as a User in Spring MVC Test
 
 It is often desirable to run tests as a specific user.
 There are two simple ways of populating the user:
@@ -159,7 +159,7 @@ There are two simple ways of populating the user:
 * <<Running as a User in Spring MVC Test with Annotations,Running as a User in Spring MVC Test with Annotations>>
 
 [[test-mockmvc-securitycontextholder-rpp]]
-==== Running as a User in Spring MVC Test with RequestPostProcessor
+=== Running as a User in Spring MVC Test with RequestPostProcessor
 
 There are a number of options available to associate a user to the current `HttpServletRequest`.
 For example, the following will run as a user (which does not need to exist) with the username "user", the password "password", and the role "ROLE_USER":
@@ -364,7 +364,7 @@ mvc.get("/") {
 ----
 ====
 
-===== Running as a User in Spring MVC Test with Annotations
+==== Running as a User in Spring MVC Test with Annotations
 
 As an alternative to using a `RequestPostProcessor` to create your user, you can use annotations described in <<Testing Method Security>>.
 For example, the following will run the test with the user with username "user", password "password", and role "ROLE_USER":
@@ -423,7 +423,7 @@ fun requestProtectedUrlWithUser() {
 ----
 ====
 
-==== Testing HTTP Basic Authentication
+=== Testing HTTP Basic Authentication
 
 While it has always been possible to authenticate with HTTP Basic, it was a bit tedious to remember the header name, format, and encode the values.
 Now this can be done using Spring Security's `httpBasic` `RequestPostProcessor`.
@@ -454,7 +454,7 @@ Authorization: Basic dXNlcjpwYXNzd29yZA==
 ----
 
 [[testing-oauth2]]
-==== Testing OAuth 2.0
+=== Testing OAuth 2.0
 
 When it comes to OAuth 2.0, the same principles covered earlier still apply: Ultimately, it depends on what your method under test is expecting to be in the `SecurityContextHolder`.
 
@@ -480,7 +480,7 @@ fun foo(user: Principal): String {
 ----
 ====
 
-There's nothing OAuth2-specific about it, so you will likely be able to simply <<test-method-withmockuser,use `@WithMockUser`>> and be fine.
+There's nothing OAuth2-specific about it, so you will likely be able to simply xref:servlet/test/method.adoc#test-method-withmockuser[use `@WithMockUser`] and be fine.
 
 But, in cases where your controllers are bound to some aspect of Spring Security's OAuth 2.0 support, like the following:
 
@@ -507,7 +507,7 @@ fun foo(@AuthenticationPrincipal user: OidcUser): String {
 then Spring Security's test support can come in handy.
 
 [[testing-oidc-login]]
-==== Testing OIDC Login
+=== Testing OIDC Login
 
 Testing the method above with Spring MVC Test would require simulating some kind of grant flow with an authorization server.
 Certainly this would be a daunting task, which is why Spring Security ships with support for removing this boilerplate.
@@ -583,13 +583,13 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"
 ----
 ====
 
-Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+Spring Security does the necessary work to make sure that the `OidcUser` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation].
 
 Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into an mock `OAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>..
 
 [[testing-oidc-login-authorities]]
-===== Configuring Authorities
+==== Configuring Authorities
 
 In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
 
@@ -619,7 +619,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oidc-login-claims]]
-===== Configuring Claims
+==== Configuring Claims
 
 And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
 
@@ -678,7 +678,7 @@ mvc.get("/endpoint") {
 since `OidcUser` collects its claims from `OidcIdToken`.
 
 [[testing-oidc-login-user]]
-===== Additional Configurations
+==== Additional Configurations
 
 There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
 
@@ -724,7 +724,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oauth2-login]]
-==== Testing OAuth 2.0 Login
+=== Testing OAuth 2.0 Login
 
 As with <<testing-oidc-login,testing OIDC login>>, testing OAuth 2.0 Login presents a similar challenge of mocking a grant flow.
 And because of that, Spring Security also has test support for non-OIDC use cases.
@@ -806,13 +806,13 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"
 ----
 ====
 
-Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation].
 
 Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in a mock `OAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>.
 
 [[testing-oauth2-login-authorities]]
-===== Configuring Authorities
+==== Configuring Authorities
 
 In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
 
@@ -842,7 +842,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oauth2-login-claims]]
-===== Configuring Claims
+==== Configuring Claims
 
 And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
 
@@ -897,7 +897,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oauth2-login-user]]
-===== Additional Configurations
+==== Additional Configurations
 
 There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
 
@@ -942,7 +942,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oauth2-client]]
-==== Testing OAuth 2.0 Clients
+=== Testing OAuth 2.0 Clients
 
 Independent of how your user authenticates, you may have other tokens and client registrations that are in play for the request you are testing.
 For example, your controller may be relying on the client credentials grant to get a token that isn't associated with the user at all:
@@ -1054,7 +1054,7 @@ assertThat(authorizedClient.accessToken.scopes).containsExactly("read")
 The client can then be retrieved as normal using `@RegisteredOAuth2AuthorizedClient` in a controller method.
 
 [[testing-oauth2-client-scopes]]
-===== Configuring Scopes
+==== Configuring Scopes
 
 In many circumstances, the OAuth 2.0 access token comes with a set of scopes.
 If your controller inspects these, say like so:
@@ -1121,7 +1121,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-oauth2-client-registration]]
-===== Additional Configurations
+==== Additional Configurations
 
 There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
 
@@ -1167,7 +1167,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-jwt]]
-==== Testing JWT Authentication
+=== Testing JWT Authentication
 
 In order to make an authorized request on a resource server, you need a bearer token.
 
@@ -1177,7 +1177,7 @@ All of this can be quite daunting, especially when this isn't the focus of your
 Fortunately, there are a number of simple ways that you can overcome this difficulty and allow your tests to focus on authorization and not on representing bearer tokens.
 We'll look at two of them now:
 
-===== `jwt() RequestPostProcessor`
+==== `jwt() RequestPostProcessor`
 
 The first way is via a `RequestPostProcessor`.
 The simplest of these would look something like this:
@@ -1357,7 +1357,7 @@ mvc.get("/endpoint") {
 ----
 ====
 
-===== `authentication()` `RequestPostProcessor`
+==== `authentication()` `RequestPostProcessor`
 
 The second way is by using the `authentication()` `RequestPostProcessor`.
 Essentially, you can instantiate your own `JwtAuthenticationToken` and provide it in your test, like so:
@@ -1399,7 +1399,7 @@ mvc.get("/endpoint") {
 Note that as an alternative to these, you can also mock the `JwtDecoder` bean itself with a `@MockBean` annotation.
 
 [[testing-opaque-token]]
-==== Testing Opaque Token Authentication
+=== Testing Opaque Token Authentication
 
 Similar to <<testing-jwt,JWTs>>, opaque tokens require an authorization server in order to verify their validity, which can make testing more difficult.
 To help with that, Spring Security has test support for opaque tokens.
@@ -1484,7 +1484,7 @@ assertThat(token.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read
 Spring Security does the necessary work to make sure that the `BearerTokenAuthentication` instance is available for your controller methods.
 
 [[testing-opaque-token-authorities]]
-===== Configuring Authorities
+==== Configuring Authorities
 
 In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
 
@@ -1514,7 +1514,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-opaque-token-attributes]]
-===== Configuring Claims
+==== Configuring Claims
 
 And while granted authorities are quite common across all of Spring Security, we also have attributes in the case of OAuth 2.0.
 
@@ -1569,7 +1569,7 @@ mvc.get("/endpoint") {
 ====
 
 [[testing-opaque-token-principal]]
-===== Additional Configurations
+==== Additional Configurations
 
 There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects.
 
@@ -1616,7 +1616,7 @@ mvc.get("/endpoint") {
 
 Note that as an alternative to using `opaqueToken()` test support, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation.
 
-=== SecurityMockMvcRequestBuilders
+== SecurityMockMvcRequestBuilders
 
 Spring MVC Test also provides a `RequestBuilder` interface that can be used to create the `MockHttpServletRequest` used in your test.
 Spring Security provides a few `RequestBuilder` implementations that can be used to make testing easier.
@@ -1636,7 +1636,7 @@ import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequ
 ----
 ====
 
-==== Testing Form Based Authentication
+=== Testing Form Based Authentication
 
 You can easily create a request to test a form based authentication using Spring Security's testing support.
 For example, the following will submit a POST to "/login" with the username "user", the password "password", and a valid CSRF token:
@@ -1696,7 +1696,7 @@ mvc
 ====
 
 [[test-logout]]
-==== Testing Logout
+=== Testing Logout
 
 While fairly trivial using standard Spring MVC Test, you can use Spring Security's testing support to make testing log out easier.
 For example, the following will submit a POST to "/logout" with a valid CSRF token:
@@ -1736,7 +1736,7 @@ mvc
 ----
 ====
 
-=== SecurityMockMvcResultMatchers
+== SecurityMockMvcResultMatchers
 
 At times it is desirable to make various security related assertions about a request.
 To accommodate this need, Spring Security Test support implements Spring MVC Test's `ResultMatcher` interface.
@@ -1757,7 +1757,7 @@ import org.springframework.security.test.web.servlet.response.SecurityMockMvcRes
 ----
 ====
 
-==== Unauthenticated Assertion
+=== Unauthenticated Assertion
 
 At times it may be valuable to assert that there is no authenticated user associated with the result of a `MockMvc` invocation.
 For example, you might want to test submitting an invalid username and password and verify that no user is authenticated.
@@ -1781,7 +1781,7 @@ mvc
 ----
 ====
 
-==== Authenticated Assertion
+=== Authenticated Assertion
 
 It is often times that we must assert that an authenticated user exists.
 For example, we may want to verify that we authenticated successfully.
diff --git a/docs/manual/src/docs/asciidoc/_includes/about/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
similarity index 97%
rename from docs/manual/src/docs/asciidoc/_includes/about/whats-new.adoc
rename to docs/modules/ROOT/pages/whats-new.adoc
index 3117f3dad1..1bfb085a41 100644
--- a/docs/manual/src/docs/asciidoc/_includes/about/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -1,5 +1,5 @@
 [[new]]
-== What's New in Spring Security 5.6
+= What's New in Spring Security 5.6
 
 Spring Security 5.6 provides a number of new features.
 Below are the highlights of the release.
diff --git a/docs/spring-security-docs.gradle b/docs/spring-security-docs.gradle
index e69de29bb2..57a95e9145 100644
--- a/docs/spring-security-docs.gradle
+++ b/docs/spring-security-docs.gradle
@@ -0,0 +1,68 @@
+apply plugin: 'io.spring.convention.docs'
+apply plugin: 'java'
+
+tasks.register("generateAntora") {
+	group = "Documentation"
+	description = "Generates the antora.yml for dynamic properties"
+	doLast {
+		def docsTag = snapshotBuild ? 'current' : project.version
+		def ghTag = snapshotBuild ? 'main' : project.version
+		def ghUrl = "https://github.com/spring-projects/spring-security/tree/$ghTag"
+		def ghOldSamplesUrl = "https://github.com/spring-projects/spring-security/tree/5.4.x/samples"
+		def ghSamplesUrl = "https://github.com/spring-projects/spring-security-samples/tree/$samplesBranch"
+		def securityDocsUrl = "https://docs.spring.io/spring-security/site/docs/$docsTag"
+		def securityApiUrl = "$securityDocsUrl/api/"
+		def securityReferenceUrl = "$securityDocsUrl/reference/html5/"
+		def springFrameworkApiUrl = "https://docs.spring.io/spring-framework/docs/$springFrameworkVersion/javadoc-api/"
+		def springFrameworkReferenceUrl = "https://docs.spring.io/spring-framework/docs/$springFrameworkVersion/reference/html/"
+		def versions = resolvedVersions(project.configurations.testRuntimeClasspath)
+		def ymlVersions = ""
+		versions.call().each { name, version ->
+			ymlVersions += """
+    ${name}: ${version}"""
+		}
+		def outputFile = new File("$buildDir/generateAntora/antora.yml")
+		outputFile.getParentFile().mkdirs()
+		outputFile.createNewFile()
+		outputFile.setText("""name: ''
+title: Spring Security
+version: ~
+display_version: 5.6
+start_page: ROOT:index.adoc
+asciidoc:
+  attributes:
+    icondir: icons
+    gh-old-samples-url: $ghOldSamplesUrl
+    gh-samples-url: $ghSamplesUrl
+    gh-url: $ghUrl
+    security-api-url: $securityApiUrl
+    security-reference-url: $securityReferenceUrl
+    spring-framework-api-url: $springFrameworkApiUrl
+    spring-framework-reference-url: $springFrameworkReferenceUrl
+    spring-security-version: ${project.version}
+${ymlVersions}
+""")
+	}
+}
+
+dependencies {
+	testImplementation platform(project(":spring-security-dependencies"))
+	testImplementation "com.unboundid:unboundid-ldapsdk"
+	testImplementation "org.apache.directory.server:apacheds-core"
+	testImplementation "org.springframework:spring-core"
+}
+
+def resolvedVersions(Configuration configuration) {
+	return {
+		configuration.resolvedConfiguration
+				.resolvedArtifacts
+				.collectEntries { [(it.name + "-version"): it.moduleVersion.id.version] }
+	}
+}
+
+repositories {
+	mavenCentral()
+	maven { url "https://repo.spring.io/release" }
+	maven { url "https://repo.spring.io/milestone" }
+	maven { url "https://repo.spring.io/snapshot" }
+}
diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml
new file mode 100644
index 0000000000..061bad7e96
--- /dev/null
+++ b/local-antora-playbook.yml
@@ -0,0 +1,17 @@
+site:
+  title: Spring Security
+  start_page: security::index.adoc
+asciidoc:
+  attributes:
+    page-pagination: true
+content:
+  sources:
+    - url: ./
+      branches: [HEAD]
+      start_path: docs
+    - url: ../../rwinch/spring-security-docs-generated
+      branches: [HEAD]
+ui:
+  bundle:
+    url: https://github.com/rwinch/antora-ui-spring/releases/download/latest/ui-bundle.zip
+    snapshot: true