mkdir -p build/ids

find -name "*.adoc" |  xargs -I{file} awk -v file={file} '/\[\[/ {  gsub("\[|\]", ""); id=$0; gsub("./docs/modules/ROOT/pages/", "", file); gsub("\[|\]", ""); id=$0;getline;text=$0; sub("^=+ ","", text); print file > "build/ids/"id".id"; print text > "build/ids/"id".text" }' {file}

find docs/modules -name "*.adoc"|while read adoc_file_to_replace; do
  echo "Replacing $adoc_file_to_replace"
  for id_file in build/ids/*.id; do
    id=$(basename $id_file | sed 's/\.id$//')
    xref_page=$(cat $id_file)
    if [[ "$adoc_file_to_replace" -ef "./docs/modules/ROOT/pages/$xref_page" ]]
    then
      echo "  - Skipping same page refid $id "
    else
      sed -i -E "s%<<$id(|,([^,>]+))>>%xref:${xref_page}#${id}[\2]%g" $adoc_file_to_replace
    fi
  done
done

docs/modules/ROOT/pages/overview/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:overview/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
 

docs/modules/ROOT/pages/overview/features/authentication/index.adoc

@@ -10,4 +10,4 @@ Once authentication is performed we know the identity and can perform authorizat
 
 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 <<servlet-authentication,Servlet>> and WebFlux for details on what is supported for each stack.
+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.

docs/modules/ROOT/pages/overview/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]]

docs/modules/ROOT/pages/overview/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.

docs/modules/ROOT/pages/overview/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:overview/features/exploits/headers.adoc#headers-hsts[Strict Transport Security] and enables it by default.
 
 [[http-proxy-server]]
 == Proxy Server Configuration

docs/modules/ROOT/pages/overview/features/index.adoc

@@ -1,6 +1,6 @@
 [[features]]
 = Features
 
-Spring Security provides comprehensive support for <<authentication,authentication>>, authorization, and protection against <<exploits,common exploits>>.
+Spring Security provides comprehensive support for xref:overview/features/authentication/index.adoc#authentication[authentication], authorization, and protection against xref:overview/features/exploits/index.adoc#exploits[common exploits].
 It also provides integration with other libraries to simplify its usage.
 

docs/modules/ROOT/pages/overview/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:overview/community.adoc#community-source[] 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:overview/modules.adoc#modules[].
 
 [[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:overview/modules.adoc#modules[].
 
 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:overview/modules.adoc#modules[].
 
 === 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:overview/modules.adoc#modules[].
 
 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.

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:overview/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:overview/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:overview/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:overview/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:overview/features/exploits/csrf.adoc#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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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].

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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default.
 The following Clear-Site-Data header:
 
 .Clear-Site-Data Example

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:overview/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:overview/features/exploits/http.adoc#http-proxy-server[integrates with proxy servers].

docs/modules/ROOT/pages/reactive/index.adoc

@@ -1,4 +1,4 @@
 = Reactive Applications
 
-Reactive applications work very differently than <<servlet-applications>>.
+Reactive applications work very differently than xref:servlet/index.adoc#servlet-applications[].
 This section discusses how Spring Security works with reactive applications which are typically written using Spring's WebFlux.

docs/modules/ROOT/pages/reactive/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/webflux.adoc#jc-webflux[], the Reactor Context is automatically established by Spring Security according to the authenticated user.
 
 ====
 .Java

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.

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:overview/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.

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`.

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

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/method.adoc#jc-erms[] using the same setup and annotations we did in xref:servlet/test/method.adoc#test-method[].
 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>>.

docs/modules/ROOT/pages/reactive/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.
 ====
 
 

docs/modules/ROOT/pages/reactive/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:
 ====

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]

docs/modules/ROOT/pages/servlet/appendix/namespace.adoc

@@ -1,7 +1,7 @@
 [[appendix-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/namespace/index.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.
@@ -19,15 +19,15 @@ This may include sensitive information, such as request parameters or headers, a
 === <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/namespace/index.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/namespace/index.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/index.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.
@@ -146,7 +146,7 @@ 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.
 
 
@@ -179,7 +179,7 @@ The default value is true.
 [[nsa-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/index.adoc#servlet-exceptiontranslationfilter[ExceptionTranslationFilter].
 
 
 [[nsa-access-denied-handler-parents]]
@@ -227,7 +227,7 @@ Optional attribute that specifies the bean name of a `CorsConfigurationSource` t
 === <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:overview/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.
@@ -674,7 +674,7 @@ if unset, defaults to `anonymousUser`.
 === <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:overview/features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] section of the reference.
 
 
 [[nsa-csrf-parents]]
@@ -710,7 +710,7 @@ Default is any HTTP method except "GET", "TRACE", "HEAD", "OPTIONS".
 === <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/namespace/index.adoc#ns-custom-filters[ namespace chapter].
 
 
 [[nsa-custom-filter-parents]]
@@ -871,7 +871,7 @@ 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.
+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]]
@@ -955,7 +955,7 @@ Reference to the `JwtDecoderFactory` used by `OidcAuthorizationCodeAuthenticatio
 
 [[nsa-oauth2-client]]
 === <oauth2-client>
-Configures <<oauth2client,OAuth 2.0 Client>> support.
+Configures xref:servlet/oauth2/oauth2-client.adoc#oauth2client[OAuth 2.0 Client] support.
 
 
 [[nsa-oauth2-client-parents]]
@@ -990,7 +990,7 @@ Reference to the `OAuth2AuthorizedClientService`.
 
 [[nsa-authorization-code-grant]]
 === <authorization-code-grant>
-Configures <<oauth2Client-auth-grant-support,OAuth 2.0 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]]
@@ -1020,7 +1020,7 @@ 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.
+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]]
@@ -1522,7 +1522,7 @@ Defaults to "username".
 [[nsa-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).
 
@@ -1616,7 +1616,7 @@ By default, an instance of `PortMapperImpl` will be added to the configuration f
 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[].
 
 
 [[nsa-port-mappings-parents]]
@@ -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/index.adoc#servlet-authentication-providermanager[`ProviderManager`].
 
 
 [[nsa-authentication-manager-id]]
@@ -2278,7 +2278,7 @@ 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>>.
+Authentication providers can optionally be configured to use a password encoder as described in the xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[].
 This will result in the bean being injected with the appropriate `PasswordEncoder` instance.
 
 
@@ -2625,7 +2625,7 @@ Defines a reference to a Spring bean Id.
 === 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]]
@@ -2736,7 +2736,7 @@ A method name
 
 [[nsa-ldap]]
 == LDAP Namespace Options
-LDAP is covered in some details in <<servlet-authentication-ldap,its own chapter>>.
+LDAP is covered in some details in xref:servlet/authentication/unpwd/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.
 
@@ -2746,7 +2746,7 @@ The LDAP implementation uses Spring LDAP extensively, so some familiarity with t
 `<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/unpwd/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.
 

docs/modules/ROOT/pages/servlet/architecture/index.adoc

@@ -3,7 +3,7 @@
 :figures: 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.
+We build on this high level understanding within xref:servlet/authentication/index.adoc#servlet-authentication[], xref:servlet/authorization/index.adoc#servlet-authorization[], xref:servlet/exploits/index.adoc#servlet-exploits[] sections of the reference.
 // FIXME: Add links to other sections of architecture
 
 [[servlet-filters-review]]
@@ -128,7 +128,7 @@ For that reason, if you are attempting to troubleshoot Spring Security's Servlet
 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.
+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.
@@ -179,14 +179,14 @@ Below is a comprehensive list of Spring Security Filter ordering:
 * CasAuthenticationFilter
 * OAuth2LoginAuthenticationFilter
 * Saml2WebSsoAuthenticationFilter
-* <<servlet-authentication-usernamepasswordauthenticationfilter,`UsernamePasswordAuthenticationFilter`>>
+* xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-usernamepasswordauthenticationfilter[`UsernamePasswordAuthenticationFilter`]
 * OpenIDAuthenticationFilter
 * DefaultLoginPageGeneratingFilter
 * DefaultLogoutPageGeneratingFilter
 * ConcurrentSessionFilter
-* <<servlet-authentication-digest,`DigestAuthenticationFilter`>>
+* xref:servlet/authentication/unpwd/digest.adoc#servlet-authentication-digest[`DigestAuthenticationFilter`]
 * BearerTokenAuthenticationFilter
-* <<servlet-authentication-basic,`BasicAuthenticationFilter`>>
+* xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[`BasicAuthenticationFilter`]
 * RequestCacheAwareFilter
 * SecurityContextHolderAwareRequestFilter
 * JaasApiIntegrationFilter
@@ -195,7 +195,7 @@ Below is a comprehensive list of Spring Security Filter ordering:
 * OAuth2AuthorizationCodeGrantFilter
 * SessionManagementFilter
 * <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>>
-* <<servlet-authorization-filtersecurityinterceptor,`FilterSecurityInterceptor`>>
+* xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`]
 * SwitchUserFilter
 
 [[servlet-exceptiontranslationfilter]]
@@ -211,7 +211,7 @@ 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 xref:servlet/authentication/architecture/index.adoc#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
@@ -243,6 +243,6 @@ try {
 }
 ----
 <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.
+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__

docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc

@@ -96,7 +96,7 @@ 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`.

docs/modules/ROOT/pages/servlet/authentication/architecture/index.adoc

@@ -2,14 +2,14 @@
 = Servlet Authentication Architecture
 :figures: servlet/authentication/architecture
 
-This discussion expands on <<servlet-architecture>> 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 <<servlet-authentication-mechanisms,Authentication Mechanism>> specific sections.
+This discussion expands on xref:servlet/architecture/index.adoc#servlet-architecture[] 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 <<authentication,authenticated>>.
+* <<servlet-authentication-securitycontextholder>> - The `SecurityContextHolder` is where Spring Security stores the details of who is xref:overview/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  <<authentication,authentication>>.
+* <<servlet-authentication-authenticationmanager>> -  the API that defines how Spring Security's Filters perform  xref:overview/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.)
@@ -26,7 +26,7 @@ It contains the <<servlet-authentication-securitycontext>>.
 
 image::{figures}/securitycontextholder.png[]
 
-The `SecurityContextHolder` is where Spring Security stores the details of who is <<authentication,authenticated>>.
+The `SecurityContextHolder` is where Spring Security stores the details of who is xref:overview/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.
 
@@ -63,7 +63,7 @@ Spring Security does not care what type of `Authentication` implementation is se
 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>>.
+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`.
 
@@ -94,7 +94,7 @@ val authorities = authentication.authorities
 
 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.
+Spring Security's xref:servlet/architecture/index.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.
@@ -125,7 +125,7 @@ The current `Authentication` can be obtained from the <<servlet-authentication-s
 The `Authentication` contains:
 
 * `principal` - identifies the user.
-When authenticating with a username/password this is often an instance of <<servlet-authentication-userdetails,`UserDetails`>>.
+When authenticating with a username/password this is often an instance of xref:servlet/authentication/unpwd/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.
@@ -141,7 +141,7 @@ A `GrantedAuthority` is, not surprisingly, an authority that is granted to the p
 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`>>.
+When using username/password based authentication ``GrantedAuthority``s are usually loaded by the xref:servlet/authentication/unpwd/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.
@@ -151,8 +151,8 @@ Of course, Spring Security is expressly designed to handle this common requireme
 [[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`.
+{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform  xref:overview/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/index.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`>>.
@@ -179,7 +179,7 @@ The parent can be any type of `AuthenticationManager`, but it is often an instan
 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).
+This is somewhat common in scenarios where there are multiple xref:servlet/architecture/index.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[]
 
@@ -199,7 +199,7 @@ See the {security-api-url}org/springframework/security/authentication/ProviderMa
 
 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.
+For example, xref:servlet/authentication/unpwd/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`
@@ -211,7 +211,7 @@ In these cases, Spring Security does not need to provide an HTTP response that r
 
 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.
+The `AuthenticationEntryPoint` implementation might perform a xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-form[redirect to a log in page], respond with an xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[WWW-Authenticate] header, etc.
 
 
 
@@ -230,7 +230,7 @@ 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`.
+For example, xref:servlet/authentication/unpwd/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.
 

docs/modules/ROOT/pages/servlet/authentication/cas.adoc

@@ -92,7 +92,7 @@ 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:overview/samples.adoc#samples[Samples].
 
 
 [[cas-st]]
@@ -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.
 
@@ -337,7 +337,7 @@ An example configuration is shown below.
 [[cas-pt-client-sample]]
 ==== 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:overview/samples.adoc#samples[sample application] contains a working example in the `ProxyTicketSampleServlet`.
 Example code can be found below:
 
 ====

docs/modules/ROOT/pages/servlet/authentication/index.adoc

@@ -1,8 +1,8 @@
 [[servlet-authentication]]
 = Authentication
 
-Spring Security provides comprehensive support for <<authentication>>.
-We start by discussing the overall <<servlet-architecture,Servlet Authentication Architecture>>.
+Spring Security provides comprehensive support for xref:overview/features/authentication/index.adoc#authentication[].
+We start by discussing the overall xref:servlet/architecture/index.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.
@@ -13,12 +13,12 @@ These sections focus on specific ways you may want to authenticate and point bac
 
 // 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
+* xref:servlet/authentication/unpwd/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[] - 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

docs/modules/ROOT/pages/servlet/authentication/jaas.adoc

@@ -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.

docs/modules/ROOT/pages/servlet/authentication/logout.adoc

@@ -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
@@ -108,7 +108,7 @@ 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[] 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.
@@ -140,9 +140,9 @@ If not configured a status code 200 will be returned by default.
 == 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[]
+- 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

docs/modules/ROOT/pages/servlet/authentication/openid.adoc

@@ -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/index.adoc#servlet-authentication-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.

docs/modules/ROOT/pages/servlet/authentication/preauth.adoc

@@ -19,7 +19,7 @@ In some cases, the external mechanism may supply role/authority information for
 == 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.
@@ -86,14 +86,14 @@ 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.
+The xref:servlet/authentication/architecture/index.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>>.
+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.
 
 
@@ -139,7 +139,7 @@ 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/namespace/index.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.
 
 

docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc

@@ -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/namespace/index.adoc#ns-config[namespace configuration], you can enable remember-me authentication just by adding the `<remember-me>` element:
 
 [source,xml]
 ----

docs/modules/ROOT/pages/servlet/authentication/unpwd/basic.adoc

@@ -11,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/index.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/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture/index.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.
@@ -28,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/index.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/index.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/unpwd/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/index.adoc#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
@@ -46,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/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[].
 * `RememberMeServices.loginSuccess` is invoked.
 If remember me is not configured, this is a no-op.
 // FIXME: link to rememberme

docs/modules/ROOT/pages/servlet/authentication/unpwd/dao-authentication-provider.adoc

@@ -2,21 +2,21 @@
 = DaoAuthenticationProvider
 :figures: servlet/authentication/unpwd
 
-{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.
+{security-api-url}org/springframework/security/authentication/dao/DaoAuthenticationProvider.html[`DaoAuthenticationProvider`] is an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`] and xref:servlet/authentication/unpwd/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 <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> in figures from <<servlet-authentication-unpwd-input,Reading the Username & Password>> works.
+The figure explains details of how the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from xref:servlet/authentication/unpwd/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 <<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_1.png[] The authentication `Filter` from xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[Reading the Username & Password] passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture/index.adoc#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_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture/index.adoc#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_4.png[] `DaoAuthenticationProvider` then uses the xref:servlet/authentication/unpwd/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 <<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`.
+image:{icondir}/number_5.png[] When authentication is successful, the xref:servlet/authentication/architecture/index.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/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.

docs/modules/ROOT/pages/servlet/authentication/unpwd/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/unpwd/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:overview/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:overview/features/authentication/password-storage.adoc#authentication-password-storage-configuration[configure] insecure plain text xref:overview/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

docs/modules/ROOT/pages/servlet/authentication/unpwd/form.adoc

@@ -12,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/index.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/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__ and sends a redirect to the log in page with the configured xref:servlet/authentication/architecture/index.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.
@@ -27,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/index.adoc#servlet-authentication-abstractprocessingfilter[], 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/index.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/index.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/unpwd/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/index.adoc#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
@@ -53,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/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-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/index.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.
@@ -183,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

docs/modules/ROOT/pages/servlet/authentication/unpwd/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/unpwd/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/unpwd/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:overview/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:overview/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:overview/features/authentication/password-storage.adoc#authentication-password-storage-dpe-format[no encoding should be used].
 
 .<user-service> `+{noop}+` XML Configuration
 ====

docs/modules/ROOT/pages/servlet/authentication/unpwd/index.adoc

@@ -11,17 +11,17 @@ As such, Spring Security provides comprehensive support for authenticating with
 
 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>>
+* xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-form[Form Login]
+* xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[Basic Authentication]
+* xref:servlet/authentication/unpwd/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 <<servlet-authentication-inmemory>>
-* Relational Databases with <<servlet-authentication-jdbc>>
-* Custom data stores with <<servlet-authentication-userdetailsservice>>
-* LDAP storage with <<servlet-authentication-ldap>>
+* Simple Storage with xref:servlet/authentication/unpwd/in-memory.adoc#servlet-authentication-inmemory[]
+* Relational Databases with xref:servlet/authentication/unpwd/jdbc.adoc#servlet-authentication-jdbc[]
+* Custom data stores with xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[]
+* LDAP storage with xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[]
 

docs/modules/ROOT/pages/servlet/authentication/unpwd/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/unpwd/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/unpwd/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:overview/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:overview/features/authentication/password-storage.adoc#authentication-password-storage[PasswordEncoder] section for more details about how to store passwords.
 
 .JdbcUserDetailsManager
 ====

docs/modules/ROOT/pages/servlet/authentication/unpwd/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/unpwd/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/unpwd/user-details-service.adoc#servlet-authentication-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.

docs/modules/ROOT/pages/servlet/authentication/unpwd/password-encoder.adoc

@@ -1,5 +1,5 @@
 [[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>>.
+Spring Security's servlet support storing passwords securely by integrating with xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[`PasswordEncoder`].
+Customizing the `PasswordEncoder` implementation used by Spring Security can be done by xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-configuration[exposing a `PasswordEncoder` Bean].

docs/modules/ROOT/pages/servlet/authentication/unpwd/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/unpwd/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/unpwd/in-memory.adoc#servlet-authentication-inmemory[in-memory] and xref:servlet/authentication/unpwd/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`:

docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details.adoc

@@ -1,5 +1,5 @@
 [[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`.
+{security-api-url}org/springframework/security/core/userdetails/UserDetails.html[`UserDetails`] is returned by the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`].
+The xref:servlet/authentication/unpwd/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] validates the `UserDetails` and then returns an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`.

docs/modules/ROOT/pages/servlet/authorization/architecture.adoc

@@ -6,7 +6,7 @@
 
 [[authz-authorities]]
 == Authorities
-<<servlet-authentication-authentication,`Authentication`>>, discusses how all `Authentication` implementations store a list of `GrantedAuthority` objects.
+xref:servlet/authentication/architecture/index.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.
 

docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc

@@ -2,22 +2,22 @@
 = Authorize HttpServletRequest with FilterSecurityInterceptor
 :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/index.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/index.adoc#servlet-filterchainproxy[] as one of the xref:servlet/architecture/index.adoc#servlet-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/index.adoc#servlet-authentication-authentication[] from the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-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/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] handles the `AccessDeniedException`.
+** image:{icondir}/number_6.png[] If access is granted, `FilterSecurityInterceptor` continues with the xref:servlet/architecture/index.adoc#servlet-filters-review[FilterChain] which allows the application to process normally.
 
 // configuration (xml/java)
 

docs/modules/ROOT/pages/servlet/authorization/method-security.adoc

@@ -3,7 +3,7 @@
 
 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

docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc

@@ -5,7 +5,7 @@
 [[aop-alliance]]
 == 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/namespace/index.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.
 

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:overview/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:overview/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:overview/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:overview/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:overview/features/exploits/csrf.adoc#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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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.

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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/features/exploits/headers.adoc#headers-hpkp[HTTP Public Key Pinning] but it is xref:overview/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:overview/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:overview/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:overview/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:overview/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:overview/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:overview/features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default.
 The following Clear-Site-Data header:
 
 .Clear-Site-Data Example

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:overview/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:overview/features/exploits/http.adoc#http-proxy-server[integrates with proxy servers].

docs/modules/ROOT/pages/servlet/exploits/index.adoc

@@ -1,7 +1,7 @@
 [[servlet-exploits]]
 = Protection Against Exploits
 
-This section discusses Servlet specific support for <<exploits,Spring Security's protection against common exploits>>.
+This section discusses Servlet specific support for xref:overview/features/exploits/index.adoc#exploits[Spring Security's protection against common exploits].
 
 * xref:servlet/exploits/csrf.adoc[]
 * xref:servlet/exploits/headers.adoc[]

docs/modules/ROOT/pages/servlet/hello/index.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:overview/getting-spring-security.adoc#getting-maven-boot[Maven] or xref:overview/getting-spring-security.adoc#getting-gradle-boot[Gradle].
 
 [[servlet-hello-starting]]
 == Starting Hello Spring Security Boot

docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc

@@ -5,7 +5,7 @@ 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[] and xref:servlet/integrations/mvc.adoc#mvc-async[].
 
 == DelegatingSecurityContextRunnable
 
@@ -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[] 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:
 

docs/modules/ROOT/pages/servlet/integrations/data.adoc

@@ -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.

docs/modules/ROOT/pages/servlet/integrations/jackson.adoc

@@ -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`)
 ====

docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc

@@ -17,7 +17,7 @@ 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
 

docs/modules/ROOT/pages/servlet/integrations/mvc.adoc

@@ -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:servlet/integrations/concurrency.adoc#concurrency[Concurrency Support] to provide transparent integration with Spring Security.
 
 [[mvc-csrf]]
 == Spring MVC and CSRF Integration
 
 === 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]
@@ -544,7 +544,7 @@ Will output HTML that is similar to the following:
 === 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/java-configuration/index.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.

docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc

@@ -270,4 +270,4 @@ The following section describes the Servlet 3.1 methods that Spring Security int
 
 [[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.
+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.

docs/modules/ROOT/pages/servlet/integrations/websocket.adoc

@@ -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]
@@ -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]
@@ -246,7 +246,7 @@ Spring Security adds an additional layer of protection to provide https://en.wik
 [[websocket-sameorigin-csrf]]
 === 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:overview/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]
@@ -357,10 +357,10 @@ When using the fallback options we need to relax a few security constraints to a
 === 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:overview/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]
@@ -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]

docs/modules/ROOT/pages/servlet/java-configuration/index.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/namespace/index.adoc#ns-config[] 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.
 

docs/modules/ROOT/pages/servlet/namespace/index.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[]].].
 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/unpwd/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]]

docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc

@@ -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
 ====
@@ -392,7 +392,7 @@ 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]]
@@ -702,7 +702,7 @@ 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:overview/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

docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc

@@ -40,10 +40,10 @@ 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].
 
-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:overview/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]]
@@ -69,7 +69,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.
@@ -93,7 +93,7 @@ At this point, the OAuth Client retrieves your email address and basic profile i
 [[oauth2login-boot-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
@@ -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
 ====

docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc

@@ -18,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/unpwd/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/index.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/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture/index.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.
@@ -40,21 +40,21 @@ 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/index.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/index.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/index.adoc#servlet-authentication-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/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[].
 * The `BearerTokenAuthenticationFilter` invokes `FilterChain.doFilter(request,response)` to continue with the rest of the application logic.
 
 [[oauth2resourceserver-jwt-minimaldependencies]]
@@ -142,17 +142,17 @@ From here, consider jumping to:
 
 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/index.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/index.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/index.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/index.adoc#servlet-authentication-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`>>.
@@ -160,8 +160,8 @@ 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/index.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/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
 
 [[oauth2resourceserver-jwt-jwkseturi]]
 == Specifying the Authorization Server JWK Set Uri Directly
@@ -1513,22 +1513,22 @@ From here, you may want to jump to:
 
 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/index.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/index.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/index.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/index.adoc#servlet-authentication-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/index.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/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`.
 
 [[oauth2resourceserver-opaque-attributes]]
 == Looking Up Attributes Post-Authentication
@@ -3007,7 +3007,7 @@ 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
@@ -3023,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

docs/modules/ROOT/pages/servlet/saml2/index.adoc

@@ -24,20 +24,20 @@ A working sample for {gh-samples-url}/servlet/spring-boot/java/saml2-login[SAML
 ====
 
 Let's take a look at how SAML 2.0 Relying Party Authentication works within Spring Security.
-First, we see that, like <<oauth2login, OAuth 2.0 Login>>, Spring Security takes the user to a third-party for performing authentication.
+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 <<servlet-securityfilterchain,`SecurityFilterChain`>> and <<servlet-authentication-abstractprocessingfilter, `AbstractAuthenticationProcessingFilter`>> diagrams:
+The figure above builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] and xref:servlet/authentication/architecture/index.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 <<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 lacks authorization, the <<servlet-exceptiontranslationfilter,`ExceptionTranslationFilter`>> initiates __Start Authentication__.
-The configured <<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`.
+image:{icondir}/number_3.png[] Since the user lacks authorization, the xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
+The configured xref:servlet/authentication/architecture/index.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`>>.
@@ -52,23 +52,23 @@ image:{icondir}/number_6.png[] The browser then POSTs the `<saml2:Response>` to
 .Authenticating a `<saml2:Response>`
 image::{figures}/saml2webssoauthenticationfilter.png[]
 
-The figure builds off our <<servlet-securityfilterchain,`SecurityFilterChain`>> diagram.
+The figure builds off our xref:servlet/architecture/index.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 <<servlet-authentication-providermanager,`AuthenticationManager`>>.
+image:{icondir}/number_2.png[] Next, the filter passes the token to its configured xref:servlet/authentication/architecture/index.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 <<servlet-authentication-securitycontextholder, `SecurityContextHolder`>> is cleared out.
-* The <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>> is invoked to restart the authentication process.
+* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`] is cleared out.
+* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is invoked to restart the authentication process.
 
 image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
 
-* The <<servlet-authentication-authentication, `Authentication`>> is set on the <<servlet-authentication-securitycontextholder, `SecurityContextHolder`>>.
+* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[ `Authentication`] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`].
 * The `Saml2WebSsoAuthenticationFilter` invokes `FilterChain#doFilter(request,response)` to continue with the rest of the application logic.
 
 [[servlet-saml2login-minimaldependencies]]
@@ -169,9 +169,9 @@ 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 <<servlet-authentication-providermanager,`AuthenticationManager`>>.
+image:{icondir}/number_1.png[] The `Saml2WebSsoAuthenticationFilter` formulates the `Saml2AuthenticationToken` and invokes the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`AuthenticationManager`].
 
-image:{icondir}/number_2.png[] The <<servlet-authentication-providermanager,`AuthenticationManager`>> invokes the OpenSAML authentication provider.
+image:{icondir}/number_2.png[] The xref:servlet/authentication/architecture/index.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.
@@ -1267,7 +1267,7 @@ open class SecurityConfig : WebSecurityConfigurerAdapter() {
 ----
 ====
 <1> First, call the default converter, which extracts attributes and authorities from the response
-<2> Second, call the <<servlet-authentication-userdetailsservice, `UserDetailsService`>> using the relevant information
+<2> Second, call the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[ `UserDetailsService`] using the relevant information
 <3> Third, return a custom authentication that includes the user details
 
 [NOTE]

docs/modules/ROOT/pages/servlet/test/mockmvc.adoc

@@ -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:
 
@@ -583,7 +583,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 an mock `OAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>..
@@ -806,7 +806,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 `OAuth2AuthorizedClientRepository`.
 This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>.