Further changes based on feedback

Mostly restoring the formatting of admonitions.

Author: Jay Bryant

docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc

@@ -146,15 +146,15 @@ All of the original passwords are `password`.
 ----
 ====
 
-<1> The first password has a `PasswordEncoder` id of `bcrypt` and an encoded password value of `$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG`.
+<1> The first password has a `PasswordEncoder` id of `bcrypt` and an `encodedPassword` value of `$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG`.
 When matching, it would delegate to `BCryptPasswordEncoder`
-<2> The second password has a `PasswordEncoder` id of `noop` and encoded password value of `password`.
+<2> The second password has a `PasswordEncoder` id of `noop` and `encodedPassword` value of `password`.
 When matching, it would delegate to `NoOpPasswordEncoder`
-<3> The third password has a `PasswordEncoder` id of `pbkdf2` and encoded password value of `5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc`.
+<3> The third password has a `PasswordEncoder` id of `pbkdf2` and `encodedPassword` value of `5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc`.
 When matching, it would delegate to `Pbkdf2PasswordEncoder`
-<4> The fourth password has a `PasswordEncoder` id of `scrypt` and encoded password value of `$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc=`
+<4> The fourth password has a `PasswordEncoder` id of `scrypt` and `encodedPassword` value of `$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc=`
 When matching, it would delegate to `SCryptPasswordEncoder`
-<5> The final password has a `PasswordEncoder` id of `sha256` and encoded password value of `97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0`.
+<5> The final password has a `PasswordEncoder` id of `sha256` and `encodedPassword` value of `97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0`.
 When matching, it would delegate to `StandardPasswordEncoder`
 
 [NOTE]
@@ -487,4 +487,8 @@ fun passwordEncoder(): PasswordEncoder {
 ----
 ====
 
-NOTE: XML Configuration requires the `NoOpPasswordEncoder` bean name to be `passwordEncoder`.
+
+[NOTE]
+====
+XML Configuration requires the `NoOpPasswordEncoder` bean name to be `passwordEncoder`.
+====

docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc

@@ -8,8 +8,11 @@ In the following sections, we explore:
 * <<csrf-protection>>
 * <<csrf-considerations>>
 
-NOTE: This portion of the documentation discusses the general topic of CSRF protection.
+[NOTE]
+====
+This portion of the documentation discusses the general topic of CSRF protection.
 See the relevant sections for specific information on CSRF protection for <<servlet-csrf,servlet>>- and <<webflux-csrf,WebFlux>>-based applications.
+====
 
 [[csrf-explained]]
 == What is a CSRF Attack?
@@ -95,7 +98,10 @@ Spring provides two mechanisms to protect against CSRF attacks:
 * The <<Synchronizer Token Pattern>>
 * Specifying the <<SameSite Attribute>> on your session cookie
 
-NOTE: Both protections require that <<csrf-protection-idempotent,Safe Methods be Idempotent>>.
+[NOTE]
+====
+Both protections require that <<csrf-protection-idempotent,Safe Methods be Idempotent>>.
+====
 
 [[csrf-protection-idempotent]]
 === Safe Methods Must be Idempotent
@@ -172,9 +178,12 @@ The evil website cannot provide the correct value for the `_csrf` parameter (whi
 An emerging way to protect against <<csrf,CSRF Attacks>> is to specify the https://tools.ietf.org/html/draft-west-first-party-cookies[SameSite Attribute] on cookies.
 A server can specify the `SameSite` attribute when setting a cookie to indicate that the cookie should not be sent when coming from external sites.
 
-NOTE: Spring Security does not directly control the creation of the session cookie, so it does not provide support for the SameSite attribute.
+[NOTE]
+====
+Spring Security does not directly control the creation of the session cookie, so it does not provide support for the SameSite attribute.
 https://spring.io/projects/spring-session[Spring Session] provides support for the `SameSite` attribute in servlet-based applications.
 Spring Framework's https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/server/session/CookieWebSessionIdResolver.html[`CookieWebSessionIdResolver`] provides support for the `SameSite` attribute in WebFlux-based applications.
+====
 
 An example of an HTTP response header with the `SameSite` attribute might look like:
 
@@ -207,7 +216,10 @@ The user receives an email at https://email.example.org that includes a link to
 If the user clicks on the link, they would rightfully expect to be authenticated to the social media site.
 However, if the `SameSite` attribute is `Strict`, the cookie would not be sent and the user would not be authenticated.
 
-NOTE: We could improve the protection and usability of `SameSite` protection against CSRF attacks by implementing https://github.com/spring-projects/spring-security/issues/7537[gh-7537].
+[NOTE]
+====
+We could improve the protection and usability of `SameSite` protection against CSRF attacks by implementing https://github.com/spring-projects/spring-security/issues/7537[gh-7537].
+====
 
 Another obvious consideration is that, in order for the `SameSite` attribute to protect users, the browser must support the `SameSite` attribute.
 Most modern browsers do https://developer.mozilla.org/en-US/docs/Web/HTTP/headers/Set-Cookie#Browser_compatibility[support the SameSite attribute].
@@ -351,8 +363,11 @@ There are two options to using CSRF protection with multipart/form-data:
 
 Each option has its trade-offs.
 
-NOTE: Before you integrate Spring Security's CSRF protection with multipart file upload, you should first ensure that you can upload without the CSRF protection.
+[NOTE]
+====
+Before you integrate Spring Security's CSRF protection with multipart file upload, you should first ensure that you can upload without the CSRF protection.
 More information about using multipart forms with Spring, see the https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/web.html#mvc-multipart[1.1.11. Multipart Resolver] section of the Spring reference and the https://docs.spring.io/spring/docs/5.2.x/javadoc-api/org/springframework/web/multipart/support/MultipartFilter.html[`MultipartFilter` Javadoc].
+====
 
 [[csrf-considerations-multipart-body]]
 ==== Place CSRF Token in the Body

docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc

@@ -1,8 +1,11 @@
 [[headers]]
 = Security HTTP Response Headers
 
-NOTE: This portion of the documentation discusses the general topic of Security HTTP Response Headers.
+[NOTE]
+====
+This portion of the documentation discusses the general topic of Security HTTP Response Headers.
 See the relevant sections for specific information on Security HTTP Response Headers in <<servlet-headers,servlet>>- and <<webflux-headers,WebFlux>>-based applications.
+====
 
 You can use https://www.owasp.org/index.php/OWASP_Secure_Headers_Project#tab=Headers[HTTP response headers] in many ways to increase the security of web applications.
 This section is dedicated to the various HTTP response headers for which Spring Security provides explicit support.
@@ -11,7 +14,10 @@ If necessary, you can also configure Spring Security to provide <<headers-custom
 [[headers-default]]
 == Default Security Headers
 
-NOTE: See the relevant sections for how to customize the defaults for both <<servlet-headers-default,servlet>>- and <<webflux-headers-default,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections for how to customize the defaults for both <<servlet-headers-default,servlet>>- and <<webflux-headers-default,webflux>>-based applications.
+====
 
 Spring Security provides a default set of security related HTTP response headers to provide secure defaults.
 
@@ -31,7 +37,10 @@ X-XSS-Protection: 1; mode=block
 ----
 ====
 
-NOTE: Strict-Transport-Security is added only on HTTPS requests
+[NOTE]
+====
+Strict-Transport-Security is added only on HTTPS requests
+====
 
 If the defaults do not meet your needs, you can easily remove, modify, or add headers from these defaults.
 For additional details on each of these headers, see the corresponding sections:
@@ -45,7 +54,10 @@ For additional details on each of these headers, see the corresponding sections:
 [[headers-cache-control]]
 == Cache Control
 
-NOTE: See the relevant sections for how to customize the defaults for both <<servlet-headers-cache-control,servlet>>- and <<webflux-headers-cache-control,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections for how to customize the defaults for both <<servlet-headers-cache-control,servlet>>- and <<webflux-headers-cache-control,webflux>>-based applications.
+====
 
 Spring Security's default is to disable caching to protect the user's content.
 
@@ -70,15 +82,21 @@ This allows for applications to ensure that static resources (such as CSS and Ja
 [[headers-content-type-options]]
 == Content Type Options
 
-NOTE: See the relevant sections for how to customize the defaults for both <<servlet-headers-content-type-options,servlet>>- and <<webflux-headers-content-type-options,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections for how to customize the defaults for both <<servlet-headers-content-type-options,servlet>>- and <<webflux-headers-content-type-options,webflux>>-based applications.
+====
 
 Historically, browsers, including Internet Explorer, would try to guess the content type of a request by using https://en.wikipedia.org/wiki/Content_sniffing[content sniffing].
 This let browsers improve the user experience by guessing the content type on resources that had not specified the content type.
 For example, if a browser encountered a JavaScript file that did not have the content type specified, it would be able to guess the content type and then run it.
 
-NOTE: There are many additional things one should do (such as only display the document in a distinct domain, ensure Content-Type header is set, sanitize the document, and others) when allowing content to be uploaded.
+[NOTE]
+====
+There are many additional things one should do (such as only display the document in a distinct domain, ensure Content-Type header is set, sanitize the document, and others) when allowing content to be uploaded.
 However, these measures are out of the scope of what Spring Security provides.
 It is also important to point out that, when disabling content sniffing, you must specify the content type in order for things to work properly.
+====
 
 The problem with content sniffing is that this allowed malicious users to use polyglots (that is, a file that is valid as multiple content types) to perform XSS attacks.
 For example, some sites may allow users to submit a valid postscript document to a website and view it.
@@ -97,7 +115,10 @@ X-Content-Type-Options: nosniff
 [[headers-hsts]]
 == HTTP Strict Transport Security (HSTS)
 
-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.
+[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.
+====
 
 When you type in your bank's website, do you enter `mybank.example.com` or do you enter `https://mybank.example.com`?
 If you omit the `https` protocol, you are potentially vulnerable to https://en.wikipedia.org/wiki/Man-in-the-middle_attack[Man-in-the-Middle attacks].
@@ -107,8 +128,11 @@ Many users omit the `https` protocol, and this is why https://tools.ietf.org/htm
 Once `mybank.example.com` is added as a https://tools.ietf.org/html/rfc6797#section-5.1[HSTS host], a browser can know ahead of time that any request to mybank.example.com should be interpreted as https://mybank.example.com.
 This greatly reduces the possibility of a Man-in-the-Middle attack occurring.
 
-NOTE: In accordance with https://tools.ietf.org/html/rfc6797#section-7.2[RFC6797], the HSTS header is injected only into HTTPS responses.
+[NOTE]
+====
+In accordance with https://tools.ietf.org/html/rfc6797#section-7.2[RFC6797], the HSTS header is injected only into HTTPS responses.
 For the browser to acknowledge the header, the browser must first trust the CA that signed the SSL certificate used to make the connection (not just the SSL certificate).
+====
 
 One way for a site to be marked as a HSTS host is to have the host preloaded into the browser.
 Another way is to add the `Strict-Transport-Security` header to the response.
@@ -131,7 +155,10 @@ For more details on HSTS preload, see https://hstspreload.org.
 [[headers-hpkp]]
 == HTTP Public Key Pinning (HPKP)
 
-NOTE: To remain passive, Spring Security still provides <<servlet-headers-hpkp,support for HPKP in servlet environments>>. However, for the reasons listed earlier, HPKP is no longer recommended by the Spring Security team.
+[NOTE]
+====
+To remain passive, Spring Security still provides <<servlet-headers-hpkp,support for HPKP in servlet environments>>. However, for the reasons listed earlier, HPKP is no longer recommended by the Spring 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 a certain web server to prevent Man-in-the-Middle (MITM) attacks with forged certificates.
 When used correctly, HPKP could add additional layers of protection against compromised certificates.
@@ -143,14 +170,20 @@ For additional details around why HPKP is no longer recommended, read https://bl
 [[headers-frame-options]]
 == X-Frame-Options
 
-NOTE: See 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.
+[NOTE]
+====
+See 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.
+====
 
 Letting your website be added to a frame can be a security issue.
 For example, by using clever CSS styling, users could be tricked into clicking on something that they were not intending.
 For example, a user that is logged into their bank might click a button that grants access to other users.
 This sort of attack is known as https://en.wikipedia.org/wiki/Clickjacking[Clickjacking].
 
-NOTE: Another modern approach to dealing with clickjacking is to use <<headers-csp>>.
+[NOTE]
+====
+Another modern approach to dealing with clickjacking is to use <<headers-csp>>.
+====
 
 There are a number ways to mitigate clickjacking attacks.
 For example, to protect legacy browsers from clickjacking attacks, you can use https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet#Best-for-now_Legacy_Browser_Frame_Breaking_Script[frame breaking code].
@@ -169,7 +202,10 @@ X-Frame-Options: DENY
 [[headers-xss-protection]]
 == X-XSS-Protection
 
-NOTE: See 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.
+[NOTE]
+====
+See 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.
+====
 
 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].
 This is by no means foolproof but does assist in XSS protection.
@@ -190,14 +226,20 @@ X-XSS-Protection: 1; mode=block
 [[headers-csp]]
 == Content Security Policy (CSP)
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-csp,servlet>>- and <<webflux-headers-csp,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-csp,servlet>>- and <<webflux-headers-csp,webflux>>-based applications.
+====
 
 https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] is a mechanism that web applications can use to mitigate content injection vulnerabilities, such as cross-site scripting (XSS).
 CSP is a declarative policy that provides a facility for web application authors to declare and ultimately inform the client (user-agent) about the sources from which the web application expects to load resources.
 
-NOTE: Content Security Policy is not intended to solve all content injection vulnerabilities.
+[NOTE]
+====
+Content Security Policy is not intended to solve all content injection vulnerabilities.
 Instead, you can use CSP to help reduce the harm caused by content injection attacks.
 As a first line of defense, web application authors should validate their input and encode their output.
+====
 
 A web application can use CSP by including one of the following HTTP headers in the response:
 
@@ -260,7 +302,10 @@ https://www.w3.org/TR/CSP2/[W3C Candidate Recommendation]
 [[headers-referrer]]
 == Referrer Policy
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-referrer,servlet>>- and <<webflux-headers-referrer,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-referrer,servlet>>- and <<webflux-headers-referrer,webflux>>-based applications.
+====
 
 https://www.w3.org/TR/referrer-policy[Referrer Policy] is a mechanism that web applications can use to manage the referrer field, which contains the last
 page the user was on.
@@ -280,7 +325,10 @@ The Referrer-Policy response header instructs the browser to let the destination
 [[headers-feature]]
 == Feature Policy
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-feature,servlet>>- and <<webflux-headers-feature,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-feature,servlet>>- and <<webflux-headers-feature,webflux>>-based applications.
+====
 
 https://wicg.github.io/feature-policy/[Feature Policy] is a mechanism that lets web developers selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
 
@@ -299,7 +347,10 @@ These policies restrict what APIs the site can access or modify the browser's de
 [[headers-permissions]]
 == Permissions Policy
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-permissions,servlet>>- and <<webflux-headers-permissions,webflux>>-based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-permissions,servlet>>- and <<webflux-headers-permissions,webflux>>-based applications.
+====
 
 https://w3c.github.io/webappsec-permissions-policy/[Permissions Policy] is a mechanism that lets web developers selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
 
@@ -318,7 +369,10 @@ These policies restrict what APIs the site can access or modify the browser's de
 [[headers-clear-site-data]]
 == Clear Site Data
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-clear-site-data,servlet>> and <<webflux-headers-clear-site-data,webflux>> based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-clear-site-data,servlet>> and <<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:
 
@@ -335,7 +389,10 @@ This is a nice clean-up action to perform on logout.
 [[headers-custom]]
 == Custom Headers
 
-NOTE: See the relevant sections to see how to configure both <<servlet-headers-custom,servlet>> based applications.
+[NOTE]
+====
+See the relevant sections to see how to configure both <<servlet-headers-custom,servlet>> based applications.
+====
 
 Spring Security has mechanisms to make it convenient to add the more common security headers to your application.
 However, it also provides hooks to enable adding custom headers.