Antora

mkdir -p docs/modules/ROOT/ mkdir -p docs/modules/ROOT/pages/ git checkout antora-2.x docs/antora.yml git checkout antora-2.x docs/modules/ROOT/nav.adoc mv docs/manual/src/docs/asciidoc/images docs/modules/ROOT/ mv docs/manual/src/docs/asciidoc/_includes/* docs/modules/ROOT/pages/ cp ~/code/rwinch/spring-reference/*antora* ~/code/spring-projects/spring-security/ mv docs/modules/ROOT/pages/about docs/modules/ROOT/pages/overview
2026-05-22 21:33:16 +00:00 · 2021-07-26 15:48:55 -05:00
parent 7b73b94198
commit f01a13aa52
218 changed files with 119 additions and 1441 deletions
@@ -0,0 +1,72 @@
+* Overview
+** xref:overview/prerequisites.adoc[Prerequisites]
+** xref:overview/community.adoc[Community]
+** xref:overview/whats-new.adoc[What's New]
+** xref:overview/getting-spring-security.adoc[Getting Spring Security]
+** xref:overview/features/index.adoc[Features]
+*** xref:overview/features/authentication/index.adoc[Authentication]
+*** xref:overview/features/exploits/index.adoc[Protection Against Exploits]
+** xref:overview/modules.adoc[Project Modules & Dependencies]
+** xref:overview/samples.adoc[Samples]
+* Servlet Applications
+** xref:servlet/hello/index.adoc[Hello Spring Security]
+** xref:servlet/architecture/index.adoc[The Big Picture]
+** Authentication
+*** xref:servlet/authentication/architecture/index.adoc[Authentication Architecture]
+*** xref:servlet/authentication/unpwd/index.adoc[Username/Password]
+**** Reading Username/Password
+***** xref:servlet/authentication/unpwd/form.adoc[Form]
+***** xref:servlet/authentication/unpwd/basic.adoc[Basic]
+***** xref:servlet/authentication/unpwd/digest.adoc[Digest]
+**** Password Storage
+***** xref:servlet/authentication/unpwd/in-memory.adoc[In Memory]
+***** xref:servlet/authentication/unpwd/jdbc.adoc[JDBC]
+***** xref:servlet/authentication/unpwd/user-details.adoc[UserDetails]
+***** xref:servlet/authentication/unpwd/user-details-service.adoc[UserDetailsService]
+***** xref:servlet/authentication/unpwd/password-encoder.adoc[PasswordEncoder]
+***** xref:servlet/authentication/unpwd/dao-authentication-provider.adoc[DaoAuthenticationProvider]
+***** xref:servlet/authentication/unpwd/ldap.adoc[LDAP]
+*** xref:servlet/authentication/session-management.adoc[Session Management]
+*** xref:servlet/authentication/rememberme.adoc[Remember Me]
+*** xref:servlet/authentication/openid.adoc[OpenID]
+*** xref:servlet/authentication/anonymous.adoc[Anonymous]
+*** xref:servlet/authentication/preauth.adoc[Pre-Authentication]
+*** xref:servlet/authentication/jaas.adoc[JAAS]
+*** xref:servlet/authentication/cas.adoc[CAS]
+*** xref:servlet/authentication/x509.adoc[X509]
+*** xref:servlet/authentication/runas.adoc[Run-As]
+*** xref:servlet/authentication/logout.adoc[Logout]
+*** xref:servlet/authentication/events.adoc[Authentication Events]
+** Authorization
+*** xref:servlet/authorization/architecture.adoc[Authorization Architecture]
+*** xref:servlet/authorization/authorize-requests.adoc[Authorize HTTP Requests]
+*** xref:servlet/authorization/expression-based.adoc[Expression-Based Access Control]
+*** xref:servlet/authorization/secure-objects.adoc[Secure Object Implementations]
+*** xref:servlet/authorization/method-security.adoc[Method Security]
+*** xref:servlet/authorization/acls.adoc[Domain Object Security ACLs]
+** OAuth2
+*** xref:servlet/oauth2/oauth2-login.adoc[OAuth2 Log In]
+*** xref:servlet/oauth2/oauth2-client.adoc[OAuth2 Client]
+*** xref:servlet/oauth2/oauth2-resourceserver.adoc[OAuth2 Resource Server]
+** xref:servlet/saml2/index.adoc[SAML2]
+** xref:servlet/exploits/index.adoc[Protection Against Exploits]
+** xref:servlet/integrations/index.adoc[Integrations]
+** Configuration
+*** xref:servlet/java-configuration/index.adoc[Java Configuration]
+*** xref:servlet/kotlin-configuration/index.adoc[Kotlin Configuration]
+*** xref:servlet/namespace/index.adoc[Namespace Configuration]
+** xref:servlet/test/index.adoc[Testing]
+** xref:servlet/crypto/index.adoc[Cryptography]
+** xref:servlet/appendix/index.adoc[Appendix]
+* Reactive Applications
+** xref:reactive/webflux.adoc[WebFlux Security]
+** xref:reactive/exploits/index.adoc[Protection Against Exploits]
+** xref:reactive/oauth2/index.adoc[OAuth2]
+** xref:reactive/registered-oauth2-authorized-client.adoc[@RegisteredOAuth2AuthorizedClient]
+** xref:reactive/x509.adoc[X.509 Authentication]
+** xref:reactive/logout.adoc[Logout]
+** xref:reactive/webclient.adoc[WebClient]
+** xref:reactive/method.adoc[EnableReactiveMethodSecurity]
+** xref:reactive/cors.adoc[CORS]
+** xref:reactive/test.adoc[Testing]
+** xref:reactive/rsocket.adoc[RSocket]
@@ -0,0 +1,37 @@
+[[community]]
+= Spring Security Community
+
+Welcome to the Spring Security Community!
+This section discusses how you can make the most of our vast community.
+
+
+[[community-help]]
+== Getting Help
+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>>.
+* 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
+
+[[community-becoming-involved]]
+== Becoming Involved
+We welcome your involvement in the Spring Security project.
+There are many ways to contribute, including answering questions on Stack Overflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
+For more information, see our https://github.com/spring-projects/spring-security/blob/main/CONTRIBUTING.adoc[Contributing] documentation.
+
+[[community-source]]
+== Source Code
+
+You can find Spring Security's source code on GitHub at https://github.com/spring-projects/spring-security/
+
+[[community-license]]
+== Apache 2 License
+
+Spring Security is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
+
+== Social Media
+
+You can follow https://twitter.com/SpringSecurity[@SpringSecurity] and the https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
+You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.
@@ -0,0 +1,12 @@
+[[authentication]]
+= Authentication
+
+Spring Security provides comprehensive support for https://en.wikipedia.org/wiki/Authentication[authentication].
+Authentication is how we verify the identity of who is trying to access a particular resource.
+A common way to authenticate users is by requiring the user to enter a username and password.
+Once authentication is performed we know the identity and can perform authorization.
+// FIXME: Link authorization to authorization
+
+include::supported.adoc[leveloffset=+1]
+
+include::password-storage.adoc[leveloffset=+1]
@@ -0,0 +1,559 @@
+[[authentication-password-storage]]
+= Password Storage
+
+Spring Security's `PasswordEncoder` interface is used to perform a one way transformation of a password to allow the password to be stored securely.
+Given `PasswordEncoder` is a one way transformation, it is not intended when the password transformation needs to be two way (i.e. storing credentials used to authenticate to a database).
+Typically `PasswordEncoder` is used for storing a password that needs to be compared to a user provided password at the time of authentication.
+
+[[authentication-password-storage-history]]
+== Password Storage History
+
+Throughout the years the standard mechanism for storing passwords has evolved.
+In the beginning passwords were stored in plain text.
+The passwords were assumed to be safe because the data store the passwords were saved in required credentials to access it.
+However, malicious users were able to find ways to get large "data dumps" of usernames and passwords using attacks like SQL Injection.
+As more and more user credentials became public security experts realized we needed to do more to protect users' passwords.
+
+Developers were then encouraged to store passwords after running them through a one way hash such as SHA-256.
+When a user tried to authenticate, the hashed password would be compared to the hash of the password that they typed.
+This meant that the system only needed to store the one way hash of the password.
+If a breach occurred, then only the one way hashes of the passwords were exposed.
+Since the hashes were one way and it was computationally difficult to guess the passwords given the hash, it would not be worth the effort to figure out each password in the system.
+To defeat this new system malicious users decided to create lookup tables known as https://en.wikipedia.org/wiki/Rainbow_table[Rainbow Tables].
+Rather than doing the work of guessing each password every time, they computed the password once and stored it in a lookup table.
+
+To mitigate the effectiveness of Rainbow Tables, developers were encouraged to use salted passwords.
+Instead of using just the password as input to the hash function, random bytes (known as salt) would be generated for every users' password.
+The salt and the user's password would be ran through the hash function which produced a unique hash.
+The salt would be stored alongside the user's password in clear text.
+Then when a user tried to authenticate, the hashed password would be compared to the hash of the stored salt and the password that they typed.
+The unique salt meant that Rainbow Tables were no longer effective because the hash was different for every salt and password combination.
+
+In modern times we realize that cryptographic hashes (like SHA-256) are no longer secure.
+The reason is that with modern hardware we can perform billions of hash calculations a second.
+This means that we can crack each password individually with ease.
+
+Developers are now encouraged to leverage adaptive one-way functions to store a password.
+Validation of passwords with adaptive one-way functions are intentionally resource (i.e. CPU, memory, etc) intensive.
+An adaptive one-way function allows configuring a "work factor" which can grow as hardware gets better.
+It is recommended that the "work factor" be tuned to take about 1 second to verify a password on your system.
+This trade off is to make it difficult for attackers to crack the password, but not so costly it puts excessive burden on your own system.
+Spring Security has attempted to provide a good starting point for the "work factor", but users are encouraged to customize the "work factor" for their own system since the performance will vary drastically from system to system.
+Examples of adaptive one-way functions that should be used include <<authentication-password-storage-bcrypt,bcrypt>>, <<authentication-password-storage-pbkdf2,PBKDF2>>, <<authentication-password-storage-scrypt,scrypt>>, and <<authentication-password-storage-argon2,argon2>>.
+
+Because adaptive one-way functions are intentionally resource intensive, validating a username and password for every request will degrade performance of an application significantly.
+There is nothing Spring Security (or any other library) can do to speed up the validation of the password since security is gained by making the validation resource intensive.
+Users are encouraged to exchange the long term credentials (i.e. username and password) for a short term credential (i.e. session, OAuth Token, etc).
+The short term credential can be validated quickly without any loss in security.
+
+
+[[authentication-password-storage-dpe]]
+== DelegatingPasswordEncoder
+
+Prior to Spring Security 5.0 the default `PasswordEncoder` was `NoOpPasswordEncoder` which required plain text passwords.
+Based upon the <<authentication-password-storage-history,Password History>> section you might expect that the default `PasswordEncoder` is now something like `BCryptPasswordEncoder`.
+However, this ignores three real world problems:
+
+- There are many applications using old password encodings that cannot easily migrate
+- The best practice for password storage will change again
+- As a framework Spring Security cannot make breaking changes frequently
+
+Instead Spring Security introduces `DelegatingPasswordEncoder` which solves all of the problems by:
+
+- Ensuring that passwords are encoded using the current password storage recommendations
+- Allowing for validating passwords in modern and legacy formats
+- Allowing for upgrading the encoding in the future
+
+You can easily construct an instance of `DelegatingPasswordEncoder`  using `PasswordEncoderFactories`.
+
+.Create Default DelegatingPasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+PasswordEncoder passwordEncoder =
+    PasswordEncoderFactories.createDelegatingPasswordEncoder();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val passwordEncoder: PasswordEncoder = PasswordEncoderFactories.createDelegatingPasswordEncoder()
+----
+====
+
+Alternatively, you may create your own custom instance. For example:
+
+.Create Custom DelegatingPasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+String idForEncode = "bcrypt";
+Map encoders = new HashMap<>();
+encoders.put(idForEncode, new BCryptPasswordEncoder());
+encoders.put("noop", NoOpPasswordEncoder.getInstance());
+encoders.put("pbkdf2", new Pbkdf2PasswordEncoder());
+encoders.put("scrypt", new SCryptPasswordEncoder());
+encoders.put("sha256", new StandardPasswordEncoder());
+
+PasswordEncoder passwordEncoder =
+    new DelegatingPasswordEncoder(idForEncode, encoders);
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val idForEncode = "bcrypt"
+val encoders: MutableMap<String, PasswordEncoder> = mutableMapOf()
+encoders[idForEncode] = BCryptPasswordEncoder()
+encoders["noop"] = NoOpPasswordEncoder.getInstance()
+encoders["pbkdf2"] = Pbkdf2PasswordEncoder()
+encoders["scrypt"] = SCryptPasswordEncoder()
+encoders["sha256"] = StandardPasswordEncoder()
+
+val passwordEncoder: PasswordEncoder = DelegatingPasswordEncoder(idForEncode, encoders)
+----
+====
+
+[[authentication-password-storage-dpe-format]]
+=== Password Storage Format
+
+The general format for a password is:
+
+.DelegatingPasswordEncoder Storage Format
+====
+[source,text,attrs="-attributes"]
+----
+{id}encodedPassword
+----
+====
+
+Such that `id` is an identifier used to look up which `PasswordEncoder` should be used and `encodedPassword` is the original encoded password for the selected `PasswordEncoder`.
+The `id` must be at the beginning of the password, start with `{` and end with `}`.
+If the `id` cannot be found, the `id` will be null.
+For example, the following might be a list of passwords encoded using different `id`.
+All of the original passwords are "password".
+
+.DelegatingPasswordEncoder Encoded Passwords Example
+====
+[source,text,attrs="-attributes"]
+----
+{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG // <1>
+{noop}password // <2>
+{pbkdf2}5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc // <3>
+{scrypt}$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc=  // <4>
+{sha256}97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0 // <5>
+----
+====
+
+<1> The first password would have a `PasswordEncoder` id of `bcrypt` and encodedPassword of `$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG`.
+When matching it would delegate to `BCryptPasswordEncoder`
+<2> The second password would have a `PasswordEncoder` id of `noop` and encodedPassword of `password`.
+When matching it would delegate to `NoOpPasswordEncoder`
+<3> The third password would have a `PasswordEncoder` id of `pbkdf2` and encodedPassword of `5d923b44a6d129f3ddf3e3c8d29412723dcbde72445e8ef6bf3b508fbf17fa4ed4d6b99ca763d8dc`.
+When matching it would delegate to `Pbkdf2PasswordEncoder`
+<4> The fourth password would have a `PasswordEncoder` id of `scrypt` and encodedPassword of `$e0801$8bWJaSu2IKSn9Z9kM+TPXfOc/9bdYSrN1oD9qfVThWEwdRTnO7re7Ei+fUZRJ68k9lTyuTeUp4of4g24hHnazw==$OAOec05+bXxvuu/1qZ6NUR+xQYvYv7BeL1QxwRpY5Pc=`
+When matching it would delegate to `SCryptPasswordEncoder`
+<5> The final password would have a `PasswordEncoder` id of `sha256` and encodedPassword of `97cde38028ad898ebc02e690819fa220e88c62e0699403e94fff291cfffaf8410849f27605abcbc0`.
+When matching it would delegate to `StandardPasswordEncoder`
+
+[NOTE]
+====
+Some users might be concerned that the storage format is provided for a potential hacker.
+This is not a concern because the storage of the password does not rely on the algorithm being a secret.
+Additionally, most formats are easy for an attacker to figure out without the prefix.
+For example, BCrypt passwords often start with `$2a$`.
+====
+
+[[authentication-password-storage-dpe-encoding]]
+=== Password Encoding
+
+The `idForEncode` passed into the constructor determines which `PasswordEncoder` will be used for encoding passwords.
+In the `DelegatingPasswordEncoder` we constructed above, that means that the result of encoding `password` would be delegated to `BCryptPasswordEncoder` and be prefixed with `+{bcrypt}+`.
+The end result would look like:
+
+.DelegatingPasswordEncoder Encode Example
+====
+[source,text,attrs="-attributes"]
+----
+{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
+----
+====
+
+[[authentication-password-storage-dpe-matching]]
+=== Password Matching
+
+Matching is done based upon the `+{id}+` and the mapping of the `id` to the `PasswordEncoder` provided in the constructor.
+Our example in <<authentication-password-storage-dpe-format,Password Storage Format>> provides a working example of how this is done.
+By default, the result of invoking `matches(CharSequence, String)` with a password and an `id` that is not mapped (including a null id) will result in an `IllegalArgumentException`.
+This behavior can be customized using `DelegatingPasswordEncoder.setDefaultPasswordEncoderForMatches(PasswordEncoder)`.
+
+By using the `id` we can match on any password encoding, but encode passwords using the most modern password encoding.
+This is important, because unlike encryption, password hashes are designed so that there is no simple way to recover the plaintext.
+Since there is no way to recover the plaintext, it makes it difficult to migrate the passwords.
+While it is simple for users to migrate `NoOpPasswordEncoder`, we chose to include it by default to make it simple for the getting started experience.
+
+[[authentication-password-storage-dep-getting-started]]
+=== Getting Started Experience
+
+If you are putting together a demo or a sample, it is a bit cumbersome to take time to hash the passwords of your users.
+There are convenience mechanisms to make this easier, but this is still not intended for production.
+
+.withDefaultPasswordEncoder Example
+====
+.Java
+[source,java,role="primary",attrs="-attributes"]
+----
+User user = User.withDefaultPasswordEncoder()
+  .username("user")
+  .password("password")
+  .roles("user")
+  .build();
+System.out.println(user.getPassword());
+// {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
+----
+
+.Kotlin
+[source,kotlin,role="secondary",attrs="-attributes"]
+----
+val user = User.withDefaultPasswordEncoder()
+    .username("user")
+    .password("password")
+    .roles("user")
+    .build()
+println(user.password)
+// {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
+----
+====
+
+If you are creating multiple users, you can also reuse the builder.
+
+.withDefaultPasswordEncoder Reusing the Builder
+====
+.Java
+[source,java,role="primary"]
+----
+UserBuilder users = User.withDefaultPasswordEncoder();
+User user = users
+  .username("user")
+  .password("password")
+  .roles("USER")
+  .build();
+User admin = users
+  .username("admin")
+  .password("password")
+  .roles("USER","ADMIN")
+  .build();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val users = User.withDefaultPasswordEncoder()
+val user = users
+    .username("user")
+    .password("password")
+    .roles("USER")
+    .build()
+val admin = users
+    .username("admin")
+    .password("password")
+    .roles("USER", "ADMIN")
+    .build()
+----
+====
+
+This does hash the password that is stored, but the passwords are still exposed in memory and in the compiled source code.
+Therefore, it is still not considered secure for a production environment.
+For production, you should <<authentication-password-storage-boot-cli,hash your passwords externally>>.
+
+[[authentication-password-storage-boot-cli]]
+=== Encode with Spring Boot CLI
+
+The easiest way to properly encode your password is to use the https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-cli.html[Spring Boot CLI].
+
+For example, the following will encode the password of `password` for use with <<authentication-password-storage-dpe>>:
+
+.Spring Boot CLI encodepassword Example
+====
+[source,attrs="-attributes"]
+----
+spring encodepassword password
+{bcrypt}$2a$10$X5wFBtLrL/kHcmrOGGTrGufsBX8CJ0WpQpF3pgeuxBB/H73BK1DW6
+----
+====
+
+[[authentication-password-storage-dpe-troubleshoot]]
+=== Troubleshooting
+
+The following error occurs when one of the passwords that are stored has no id as described in <<authentication-password-storage-dpe-format>>.
+
+----
+java.lang.IllegalArgumentException: There is no PasswordEncoder mapped for the id "null"
+	at org.springframework.security.crypto.password.DelegatingPasswordEncoder$UnmappedIdPasswordEncoder.matches(DelegatingPasswordEncoder.java:233)
+	at org.springframework.security.crypto.password.DelegatingPasswordEncoder.matches(DelegatingPasswordEncoder.java:196)
+----
+
+The easiest way to resolve the error is to switch to explicitly providing the `PasswordEncoder` that your passwords are encoded with.
+The easiest way to resolve it is to figure out how your passwords are currently being stored and explicitly provide the correct `PasswordEncoder`.
+
+If you are migrating from Spring Security 4.2.x you can revert to the previous behavior by <<authentication-password-storage-configuration,exposing a `NoOpPasswordEncoder` bean>>.
+
+Alternatively, you can prefix all of your passwords with the correct id and continue to use `DelegatingPasswordEncoder`.
+For example, if you are using BCrypt, you would migrate your password from something like:
+
+----
+$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
+----
+
+to
+
+
+[source,attrs="-attributes"]
+----
+{bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG
+----
+
+For a complete listing of the mappings refer to the Javadoc on
+https://docs.spring.io/spring-security/site/docs/5.0.x/api/org/springframework/security/crypto/factory/PasswordEncoderFactories.html[PasswordEncoderFactories].
+
+[[authentication-password-storage-bcrypt]]
+== BCryptPasswordEncoder
+
+The `BCryptPasswordEncoder` implementation uses the widely supported https://en.wikipedia.org/wiki/Bcrypt[bcrypt] algorithm to hash the passwords.
+In order to make it more resistent to password cracking, bcrypt is deliberately slow.
+Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
+The default implementation of `BCryptPasswordEncoder` uses strength 10 as mentioned in the Javadoc of https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/crypto/bcrypt/BCryptPasswordEncoder.html[BCryptPasswordEncoder]. You are encouraged to
+tune and test the strength parameter on your own system so that it takes roughly 1 second to verify a password.
+
+.BCryptPasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+// Create an encoder with strength 16
+BCryptPasswordEncoder encoder = new BCryptPasswordEncoder(16);
+String result = encoder.encode("myPassword");
+assertTrue(encoder.matches("myPassword", result));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+// Create an encoder with strength 16
+val encoder = BCryptPasswordEncoder(16)
+val result: String = encoder.encode("myPassword")
+assertTrue(encoder.matches("myPassword", result))
+----
+====
+
+[[authentication-password-storage-argon2]]
+== Argon2PasswordEncoder
+
+The `Argon2PasswordEncoder` implementation uses the https://en.wikipedia.org/wiki/Argon2[Argon2] algorithm to hash the passwords.
+Argon2 is the winner of the https://en.wikipedia.org/wiki/Password_Hashing_Competition[Password Hashing Competition].
+In order to defeat password cracking on custom hardware, Argon2 is a deliberately slow algorithm that requires large amounts of memory.
+Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
+The current implementation of the `Argon2PasswordEncoder` requires BouncyCastle.
+
+.Argon2PasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+// Create an encoder with all the defaults
+Argon2PasswordEncoder encoder = new Argon2PasswordEncoder();
+String result = encoder.encode("myPassword");
+assertTrue(encoder.matches("myPassword", result));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+// Create an encoder with all the defaults
+val encoder = Argon2PasswordEncoder()
+val result: String = encoder.encode("myPassword")
+assertTrue(encoder.matches("myPassword", result))
+----
+====
+
+[[authentication-password-storage-pbkdf2]]
+== Pbkdf2PasswordEncoder
+
+The `Pbkdf2PasswordEncoder` implementation uses the https://en.wikipedia.org/wiki/PBKDF2[PBKDF2] algorithm to hash the passwords.
+In order to defeat password cracking PBKDF2 is a deliberately slow algorithm.
+Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
+This algorithm is a good choice when FIPS certification is required.
+
+.Pbkdf2PasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+// Create an encoder with all the defaults
+Pbkdf2PasswordEncoder encoder = new Pbkdf2PasswordEncoder();
+String result = encoder.encode("myPassword");
+assertTrue(encoder.matches("myPassword", result));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+// Create an encoder with all the defaults
+val encoder = Pbkdf2PasswordEncoder()
+val result: String = encoder.encode("myPassword")
+assertTrue(encoder.matches("myPassword", result))
+----
+====
+
+[[authentication-password-storage-scrypt]]
+== SCryptPasswordEncoder
+
+The `SCryptPasswordEncoder` implementation uses https://en.wikipedia.org/wiki/Scrypt[scrypt] algorithm to hash the passwords.
+In order to defeat password cracking on custom hardware scrypt is a deliberately slow algorithm that requires large amounts of memory.
+Like other adaptive one-way functions, it should be tuned to take about 1 second to verify a password on your system.
+
+.SCryptPasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+// Create an encoder with all the defaults
+SCryptPasswordEncoder encoder = new SCryptPasswordEncoder();
+String result = encoder.encode("myPassword");
+assertTrue(encoder.matches("myPassword", result));
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+// Create an encoder with all the defaults
+val encoder = SCryptPasswordEncoder()
+val result: String = encoder.encode("myPassword")
+assertTrue(encoder.matches("myPassword", result))
+----
+====
+
+[[authentication-password-storage-other]]
+== Other PasswordEncoders
+
+There are a significant number of other `PasswordEncoder` implementations that exist entirely for backward compatibility.
+They are all deprecated to indicate that they are no longer considered secure.
+However, there are no plans to remove them since it is difficult to migrate existing legacy systems.
+
+[[authentication-password-storage-configuration]]
+== Password Storage Configuration
+
+Spring Security uses <<authentication-password-storage-dpe>> by default.
+However, this can be customized by exposing a `PasswordEncoder` as a Spring bean.
+
+
+If you are migrating from Spring Security 4.2.x you can revert to the previous behavior by exposing a `NoOpPasswordEncoder` bean.
+
+[WARNING]
+====
+Reverting to `NoOpPasswordEncoder` is not considered to be secure.
+You should instead migrate to using `DelegatingPasswordEncoder` to support secure password encoding.
+====
+
+.NoOpPasswordEncoder
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public static NoOpPasswordEncoder passwordEncoder() {
+    return NoOpPasswordEncoder.getInstance();
+}
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<b:bean id="passwordEncoder"
+        class="org.springframework.security.crypto.password.NoOpPasswordEncoder" factory-method="getInstance"/>
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun passwordEncoder(): PasswordEncoder {
+    return NoOpPasswordEncoder.getInstance();
+}
+----
+====
+
+[NOTE]
+====
+XML Configuration requires the `NoOpPasswordEncoder` bean name to be `passwordEncoder`.
+====
+
+[[authentication-change-password-configuration]]
+== Change Password Configuration
+
+Most applications that allow a user to specify a password also require a feature for updating that password.
+
+https://w3c.github.io/webappsec-change-password-url/[A Well-Know URL for Changing Passwords] indicates a mechanism by which password managers can discover the password update endpoint for a given application.
+
+You can configure Spring Security to provide this discovery endpoint.
+For example, if the change password endpoint in your application is `/change-password`, then you can configure Spring Security like so:
+
+.Default Change Password Endpoint
+====
+.Java
+[source,java,role="primary"]
+----
+http
+    .passwordManagement(Customizer.withDefaults())
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<sec:password-management/>
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+http {
+    passwordManagement { }
+}
+----
+====
+
+Then, when a password manager navigates to `/.well-known/change-password` then Spring Security will redirect your endpoint, `/change-password`.
+
+Or, if your endpoint is something other than `/change-password`, you can also specify that like so:
+
+.Change Password Endpoint
+====
+.Java
+[source,java,role="primary"]
+----
+http
+    .passwordManagement((management) -> management
+        .changePasswordPage("/update-password")
+    )
+----
+
+.XML
+[source,xml,role="secondary"]
+----
+<sec:password-management change-password-page="/update-password"/>
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+http {
+    passwordManagement {
+        changePasswordPage = "/update-password"
+    }
+}
+----
+====
+
+With the above configuration, when a password manager navigates to `/.well-known/change-password`, then Spring Security will redirect to `/update-password`.
@@ -0,0 +1,5 @@
+[[authentication-support]]
+= Authentication Support
+
+Spring Security provides built in support for authenticating users.
+Refer to the sections on authentication for <<servlet-authentication,Servlet>> and WebFlux for details on what is supported for each stack.
@@ -0,0 +1,413 @@
+// FIXME: Add links to Servlet and WebFlux support
+
+[[csrf]]
+= Cross Site Request Forgery (CSRF)
+
+Spring provides comprehensive support for protecting against https://en.wikipedia.org/wiki/Cross-site_request_forgery[Cross Site Request Forgery (CSRF)] attacks.
+In the following sections we will explore:
+
+* <<csrf-explained>>
+* <<csrf-protection>>
+* <<csrf-considerations>>
+
+// FIXME: Add WebFlux csrf documentation (the link below is broken)
+[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.
+====
+
+[[csrf-explained]]
+== What is a CSRF Attack?
+The best way to understand a CSRF attack is by taking a look at a concrete example.
+
+Assume that your bank's website provides a form that allows transferring money from the currently logged in user to another bank account.
+For example, the transfer form might look like:
+
+.Transfer form
+====
+[source,html]
+----
+<form method="post"
+	action="/transfer">
+<input type="text"
+	name="amount"/>
+<input type="text"
+	name="routingNumber"/>
+<input type="text"
+	name="account"/>
+<input type="submit"
+	value="Transfer"/>
+</form>
+----
+====
+
+The corresponding HTTP request might look like:
+
+.Transfer HTTP request
+====
+[source]
+----
+POST /transfer HTTP/1.1
+Host: bank.example.com
+Cookie: JSESSIONID=randomid
+Content-Type: application/x-www-form-urlencoded
+
+amount=100.00&routingNumber=1234&account=9876
+----
+====
+
+Now pretend you authenticate to your bank's website and then, without logging out, visit an evil website.
+The evil website contains an HTML page with the following form:
+
+.Evil transfer form
+====
+[source,html]
+----
+<form method="post"
+	action="https://bank.example.com/transfer">
+<input type="hidden"
+	name="amount"
+	value="100.00"/>
+<input type="hidden"
+	name="routingNumber"
+	value="evilsRoutingNumber"/>
+<input type="hidden"
+	name="account"
+	value="evilsAccountNumber"/>
+<input type="submit"
+	value="Win Money!"/>
+</form>
+----
+====
+
+You like to win money, so you click on the submit button.
+In the process, you have unintentionally transferred $100 to a malicious user.
+This happens because, while the evil website cannot see your cookies, the cookies associated with your bank are still sent along with the request.
+
+Worst yet, this whole process could have been automated using JavaScript.
+This means you didn't even need to click on the button.
+Furthermore, it could just as easily happen when visiting an honest site that is a victim of a https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)[XSS attack].
+So how do we protect our users from such attacks?
+
+[[csrf-protection]]
+== Protecting Against CSRF Attacks
+The reason that a CSRF attack is possible is that the HTTP request from the victim's website and the request from the attacker's website are exactly the same.
+This means there is no way to reject requests coming from the evil website and allow requests coming from the bank's website.
+To protect against CSRF attacks we need to ensure there is something in the request that the evil site is unable to provide so we can differentiate the two requests.
+
+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 <<Safe Methods Must be Idempotent>>
+====
+
+[[csrf-protection-idempotent]]
+=== Safe Methods Must be Idempotent
+
+In order for <<csrf-protection,either protection>> against CSRF to work, the application must ensure that https://tools.ietf.org/html/rfc7231#section-4.2.1["safe" HTTP methods are idempotent].
+This means that requests with the HTTP method `GET`, `HEAD`, `OPTIONS`, and `TRACE` should not change the state of the application.
+
+[[csrf-protection-stp]]
+=== Synchronizer Token Pattern
+The predominant and most comprehensive way to protect against CSRF attacks is to use the https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#synchronizer-token-pattern[Synchronizer Token Pattern].
+This solution is to ensure that each HTTP request requires, in addition to our session cookie, a secure random generated value called a CSRF token must be present in the HTTP request.
+
+When an HTTP request is submitted, the server must look up the expected CSRF token and compare it against the actual CSRF token in the HTTP request.
+If the values do not match, the HTTP request should be rejected.
+
+The key to this working is that the actual CSRF token should be in a part of the HTTP request that is not automatically included by the browser.
+For example, requiring the actual CSRF token in an HTTP parameter or an HTTP header will protect against CSRF attacks.
+Requiring the actual CSRF token in a cookie does not work because cookies are automatically included in the HTTP request by the browser.
+
+We can relax the expectations to only require the actual CSRF token for each HTTP request that updates state of the application.
+For that to work, our application must ensure that <<csrf-protection-idempotent,safe HTTP methods are idempotent>>.
+This improves usability since we want to allow linking to our website using links from external sites.
+Additionally, we do not want to include the random token in HTTP GET as this can cause the tokens to be leaked.
+
+Let's take a look at how <<csrf-explained,our example>> would change when using the Synchronizer Token Pattern.
+Assume the actual CSRF token is required to be in an HTTP parameter named `_csrf`.
+Our application's transfer form would look like:
+
+.Synchronizer Token Form
+====
+[source,html]
+----
+<form method="post"
+	action="/transfer">
+<input type="hidden"
+	name="_csrf"
+	value="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
+<input type="text"
+	name="amount"/>
+<input type="text"
+	name="routingNumber"/>
+<input type="hidden"
+	name="account"/>
+<input type="submit"
+	value="Transfer"/>
+</form>
+----
+====
+
+The form now contains a hidden input with the value of the CSRF token.
+External sites cannot read the CSRF token since the same origin policy ensures the evil site cannot read the response.
+
+The corresponding HTTP request to transfer money would look like this:
+
+.Synchronizer Token request
+====
+[source]
+----
+POST /transfer HTTP/1.1
+Host: bank.example.com
+Cookie: JSESSIONID=randomid
+Content-Type: application/x-www-form-urlencoded
+
+amount=100.00&routingNumber=1234&account=9876&_csrf=4bfd1575-3ad1-4d21-96c7-4ef2d9f86721
+----
+====
+
+
+You will notice that the HTTP request now contains the `_csrf` parameter with a secure random value.
+The evil website will not be able to provide the correct value for the `_csrf` parameter (which must be explicitly provided on the evil website) and the transfer will fail when the server compares the actual CSRF token to the expected CSRF token.
+
+[[csrf-protection-ssa]]
+=== SameSite Attribute
+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.
+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 out of the box support for the `SameSite` attribute in WebFlux based applications.
+====
+
+An example, HTTP response header with the `SameSite` attribute might look like:
+
+.SameSite HTTP response
+====
+[source]
+----
+Set-Cookie: JSESSIONID=randomid; Domain=bank.example.com; Secure; HttpOnly; SameSite=Lax
+----
+====
+
+Valid values for the `SameSite` attribute are:
+
+* `Strict` - when specified any request coming from the https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-2.1[same-site] will include the cookie.
+Otherwise, the cookie will not be included in the HTTP request.
+* `Lax` - when specified cookies will be sent when coming from the https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-2.1[same-site] or when the request comes from top-level navigations and the <<Safe Methods Must be Idempotent,method is idempotent>>.
+Otherwise, the cookie will not be included in the HTTP request.
+
+Let's take a look at how <<csrf-explained,our example>> could be protected using the `SameSite` attribute.
+The bank application can protect against CSRF by specifying the `SameSite` attribute on the session cookie.
+
+With the `SameSite` attribute set on our session cookie, the browser will continue to send the `JSESSIONID` cookie with requests coming from the banking website.
+However, the browser will no longer send the `JSESSIONID` cookie with a transfer request coming from the evil website.
+Since the session is no longer present in the transfer request coming from the evil website, the application is protected from the CSRF attack.
+
+There are some important https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-5[considerations] that one should be aware about when using `SameSite` attribute to protect against CSRF attacks.
+
+Setting the `SameSite` attribute to `Strict` provides a stronger defense but can confuse users.
+Consider a user that stays logged into a social media site hosted at https://social.example.com.
+The user receives an email at https://email.example.org that includes a link to the social media site.
+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 so 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].
+====
+
+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].
+However, older browsers that are still in use may not.
+
+For this reason, it is generally recommended to use the `SameSite` attribute as a defense in depth rather than the sole protection against CSRF attacks.
+
+[[csrf-when]]
+== When to use CSRF protection
+When should you use CSRF protection?
+Our recommendation is to use CSRF protection for any request that could be processed by a browser by normal users.
+If you are only creating a service that is used by non-browser clients, you will likely want to disable CSRF protection.
+
+[[csrf-when-json]]
+=== CSRF protection and JSON
+A common question is "do I need to protect JSON requests made by javascript?"
+The short answer is, it depends.
+However, you must be very careful as there are CSRF exploits that can impact JSON requests.
+For example, a malicious user can create a http://blog.opensecurityresearch.com/2012/02/json-csrf-with-parameter-padding.html[CSRF with JSON using the following form]:
+
+.CSRF with JSON form
+====
+[source,html]
+----
+<form action="https://bank.example.com/transfer" method="post" enctype="text/plain">
+	<input name='{"amount":100,"routingNumber":"evilsRoutingNumber","account":"evilsAccountNumber", "ignore_me":"' value='test"}' type='hidden'>
+	<input type="submit"
+		value="Win Money!"/>
+</form>
+----
+====
+
+
+This will produce the following JSON structure
+
+.CSRF with JSON request
+====
+[source,javascript]
+----
+{ "amount": 100,
+"routingNumber": "evilsRoutingNumber",
+"account": "evilsAccountNumber",
+"ignore_me": "=test"
+}
+----
+====
+
+If an application were not validating the Content-Type, then it would be exposed to this exploit.
+Depending on the setup, a Spring MVC application that validates the Content-Type could still be exploited by updating the URL suffix to end with `.json` as shown below:
+
+.CSRF with JSON Spring MVC form
+====
+[source,html]
+----
+<form action="https://bank.example.com/transfer.json" method="post" enctype="text/plain">
+	<input name='{"amount":100,"routingNumber":"evilsRoutingNumber","account":"evilsAccountNumber", "ignore_me":"' value='test"}' type='hidden'>
+	<input type="submit"
+		value="Win Money!"/>
+</form>
+----
+====
+
+[[csrf-when-stateless]]
+=== CSRF and Stateless Browser Applications
+What if my application is stateless?
+That doesn't necessarily mean you are protected.
+In fact, if a user does not need to perform any actions in the web browser for a given request, they are likely still vulnerable to CSRF attacks.
+
+For example, consider an application that uses a custom cookie that contains all the state within it for authentication instead of the JSESSIONID.
+When the CSRF attack is made the custom cookie will be sent with the request in the same manner that the JSESSIONID cookie was sent in our previous example.
+This application will be vulnerable to CSRF attacks.
+
+Applications that use basic authentication are also vulnerable to CSRF attacks.
+The application is vulnerable since the browser will automatically include the username and password in any requests in the same manner that the JSESSIONID cookie was sent in our previous example.
+
+[[csrf-considerations]]
+== CSRF Considerations
+There are a few special considerations to consider when implementing protection against CSRF attacks.
+
+// FIXME: Document rotating the CSRF token at log in to avoid a fixation attack
+
+[[csrf-considerations-login]]
+=== Logging In
+
+In order to protect against https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests[forging log in requests] the log in HTTP request should be protected against CSRF attacks.
+Protecting against forging log in requests is necessary so that a malicious user cannot read a victim's sensitive information.
+The attack is performed as follows:
+
+* A malicious user performs a CSRF log in using the malicious user's credentials.
+The victim is now authenticated as the malicious user.
+* The malicious user then tricks the victim to visit the compromised website and enter sensitive information
+* The information is associated to the malicious user's account so the malicious user can log in with their own credentials and view the vicitim's sensitive information
+
+A possible complication to ensuring log in HTTP requests are protected against CSRF attacks is that the user might experience a session timeout that causes the request to be rejected.
+A session timeout is surprising to users who do not expect to need to have a session in order to log in.
+For more information refer to <<csrf-considerations-timeouts>>.
+
+[[csrf-considerations-logout]]
+=== Logging Out
+
+In order to protect against forging log out requests, the log out HTTP request should be protected against CSRF attacks.
+Protecting against forging log out requests is necessary so a malicious user cannot read a victim's sensitive information.
+For details on the attack refer to https://labs.detectify.com/2017/03/15/loginlogout-csrf-time-to-reconsider/[this blog post].
+
+A possible complication to ensuring log out HTTP requests are protected against CSRF attacks is that the user might experience a session timeout that causes the request to be rejected.
+A session timeout is surprising to users who do not expect to need to have a session in order to log out.
+For more information refer to <<csrf-considerations-timeouts>>.
+
+[[csrf-considerations-timeouts]]
+=== CSRF and Session Timeouts
+More often than not, the expected CSRF token is stored in the session.
+This means that as soon as the session expires the server will not find an expected CSRF token and reject the HTTP request.
+There are a number of options to solve timeouts each of which come with trade offs.
+
+* The best way to mitigate the timeout is by using JavaScript to request a CSRF token on form submission.
+The form is then updated with the CSRF token and submitted.
+* Another option is to have some JavaScript that lets the user know their session is about to expire.
+The user can click a button to continue and refresh the session.
+* Finally, the expected CSRF token could be stored in a cookie.
+This allows the expected CSRF token to outlive the session.
+
+One might ask why the expected CSRF token isn't stored in a cookie by default.
+This is because there are known exploits in which headers (for example, to specify the cookies) can be set by another domain.
+This is the same reason Ruby on Rails https://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails/[no longer skips CSRF checks when the header X-Requested-With is present].
+See https://web.archive.org/web/20210221120355/https://lists.webappsec.org/pipermail/websecurity_lists.webappsec.org/2011-February/007533.html[this webappsec.org thread] for details on how to perform the exploit.
+Another disadvantage is that by removing the state (that is, the timeout), you lose the ability to forcibly invalidate the token if it is compromised.
+
+// FIXME: Document timeout with lengthy form expire. We do not want to automatically replay that request because it can lead to exploit
+
+[[csrf-considerations-multipart]]
+=== Multipart (file upload)
+
+Protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem.
+In order to prevent a CSRF attack from occurring, the body of the HTTP request must be read to obtain actual CSRF token.
+However, reading the body means that the file will be uploaded which means an external site can upload a file.
+
+There are two options to using CSRF protection with multipart/form-data.
+Each option has its trade-offs.
+
+* <<csrf-considerations-multipart-body,Place CSRF Token in the Body>>
+* <<csrf-considerations-multipart-url,Place CSRF Token in the URL>>
+
+[NOTE]
+====
+Before you integrate Spring Security's CSRF protection with multipart file upload, ensure that you can upload without the CSRF protection first.
+More information about using multipart forms with Spring can be found within 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
+The first option is to include the actual CSRF token in the body of the request.
+By placing the CSRF token in the body, the body will be read before authorization is performed.
+This means that anyone can place temporary files on your server.
+However, only authorized users will be able to submit a file that is processed by your application.
+In general, this is the recommended approach because the temporary file upload should have a negligible impact on most servers.
+
+[[csrf-considerations-multipart-url]]
+==== Include CSRF Token in URL
+If allowing unauthorized users to upload temporary files is not acceptable, an alternative is to include the expected CSRF token as a query parameter in the action attribute of the form.
+The disadvantage to this approach is that query parameters can be leaked.
+More generally, it is considered best practice to place sensitive data within the body or headers to ensure it is not leaked.
+Additional information can be found in https://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15.1.3[RFC 2616 Section 15.1.3 Encoding Sensitive Information in URI's].
+
+[[csrf-considerations-override-method]]
+==== HiddenHttpMethodFilter
+In some applications a form parameter can be used to override the HTTP method.
+For example, the form below could be used to treat the HTTP method as a `delete` rather than a `post`.
+
+.CSRF Hidden HTTP Method Form
+====
+[source,html]
+----
+<form action="/process"
+	method="post">
+	<!-- ... -->
+	<input type="hidden"
+		name="_method"
+		value="delete"/>
+</form>
+----
+====
+
+
+Overriding the HTTP method occurs in a filter.
+That filter must be placed before Spring Security's support.
+Note that overriding only happens on a `post`, so this is actually unlikely to cause any real problems.
+However, it is still best practice to ensure it is placed before Spring Security's filters.
@@ -0,0 +1,391 @@
+[[headers]]
+= Security HTTP Response Headers
+
+[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.
+====
+
+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.
+This section is dedicated to the various HTTP response headers that Spring Security provides explicit support for.
+If necessary, Spring Security can also be configured to provide <<headers-custom,custom headers>>.
+
+[[headers-default]]
+== Default Security Headers
+
+[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.
+====
+
+Spring Security provides a default set of security related HTTP response headers to provide secure defaults.
+
+The default for Spring Security is to include the following headers:
+
+.Default Security HTTP Response Headers
+====
+[source,http]
+----
+Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+Pragma: no-cache
+Expires: 0
+X-Content-Type-Options: nosniff
+Strict-Transport-Security: max-age=31536000 ; includeSubDomains
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+----
+====
+
+NOTE: Strict-Transport-Security is only added 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, refer to the corresponding sections:
+
+* <<headers-cache-control,Cache Control>>
+* <<headers-content-type-options,Content Type Options>>
+* <<headers-hsts,HTTP Strict Transport Security>>
+* <<headers-frame-options,X-Frame-Options>>
+* <<headers-xss-protection,X-XSS-Protection>>
+
+[[headers-cache-control]]
+== Cache Control
+
+[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.
+====
+
+Spring Security's default is to disable caching to protect user's content.
+
+If a user authenticates to view sensitive information and then logs out, we don't want a malicious user to be able to click the back button to view the sensitive information.
+The cache control headers that are sent by default are:
+
+.Default Cache Control HTTP Response Headers
+====
+[source]
+----
+Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+Pragma: no-cache
+Expires: 0
+----
+====
+
+In order to be secure by default, Spring Security adds these headers by default.
+However, if your application provides its own cache control headers Spring Security will back out of the way.
+This allows for applications to ensure that static resources like CSS and JavaScript can be cached.
+
+
+[[headers-content-type-options]]
+== Content Type Options
+
+[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.
+====
+
+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].
+This allowed browsers to 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 (i.e. only display the document in a distinct domain, ensure Content-Type header is set, sanitize the document, etc) 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 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 (i.e. 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.
+A malicious user might create a http://webblaze.cs.berkeley.edu/papers/barth-caballero-song.pdf[postscript document that is also a valid JavaScript file] and perform a XSS attack with it.
+
+Spring Security disables content sniffing by default by adding the following header to HTTP responses:
+
+.nosniff HTTP Response Header
+====
+[source,http]
+----
+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.
+====
+
+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].
+Even if the website performs a redirect to https://mybank.example.com a malicious user could intercept the initial HTTP request and manipulate the response (e.g. redirect to https://mibank.example.com and steal their credentials).
+
+Many users omit the https protocol and this is why https://tools.ietf.org/html/rfc6797[HTTP Strict Transport Security (HSTS)] was created.
+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 only injected into HTTPS responses.
+In order 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 is to add the `Strict-Transport-Security` header to the response.
+For example, Spring Security's default behavior is to add the following header which instructs the browser to treat the domain as an HSTS host for a year (there are approximately 31536000 seconds in a year):
+
+
+.Strict Transport Security HTTP Response Header
+====
+[source]
+----
+Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
+----
+====
+
+The optional `includeSubDomains` directive instructs the browser that subdomains (e.g. secure.mybank.example.com) should also be treated as an HSTS domain.
+
+The optional `preload` directive instructs the browser that domain should be preloaded in browser as HSTS domain.
+For more details on HSTS preload please see https://hstspreload.org.
+
+[[headers-hpkp]]
+== HTTP Public Key Pinning (HPKP)
+
+[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.
+====
+
+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.
+When used correctly, HPKP could add additional layers of protection against compromised certificates.
+However, due to the complexity of HPKP many experts no longer recommend using it and https://www.chromestatus.com/feature/5903385005916160[Chrome has even removed support] for it.
+
+[[headers-hpkp-deprecated]]
+For additional details around why HPKP is no longer recommended read https://blog.qualys.com/ssllabs/2016/09/06/is-http-public-key-pinning-dead[
+Is HTTP Public Key Pinning Dead?] and https://scotthelme.co.uk/im-giving-up-on-hpkp/[I'm giving up on HPKP].
+
+[[headers-frame-options]]
+== X-Frame-Options
+
+[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.
+====
+
+Allowing your website to be added to a frame can be a security issue.
+For example, 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>>.
+====
+
+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].
+While not perfect, the frame breaking code is the best you can do for the legacy browsers.
+
+A more modern approach to address clickjacking is to use https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options[X-Frame-Options] header.
+By default Spring Security disables rendering pages within an iframe using with the following header:
+
+[source]
+----
+X-Frame-Options: DENY
+----
+
+[[headers-xss-protection]]
+== X-XSS-Protection
+
+[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.
+====
+
+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.
+
+The filtering is typically enabled by default, so adding the header typically just ensures it is enabled and instructs the browser what to do when a XSS attack is detected.
+For example, the filter might try to change the content in the least invasive way to still render everything.
+At times, this type of replacement can become a https://hackademix.net/2009/11/21/ies-xss-filter-creates-xss-vulnerabilities/[XSS vulnerability in itself].
+Instead, it is best to block the content rather than attempt to fix it.
+By default Spring Security blocks the content using the following header:
+
+[source]
+----
+X-XSS-Protection: 1; mode=block
+----
+
+
+[[headers-csp]]
+== Content Security Policy (CSP)
+
+[NOTE]
+====
+Refer to 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 leverage 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.
+Instead, CSP can be leveraged 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 may employ the use of CSP by including one of the following HTTP headers in the response:
+
+* `Content-Security-Policy`
+* `Content-Security-Policy-Report-Only`
+
+Each of these headers are used as a mechanism to deliver a security policy to the client.
+A security policy contains a set of security policy directives, each responsible for declaring the restrictions for a particular resource representation.
+
+For example, a web application can declare that it expects to load scripts from specific, trusted sources, by including the following header in the response:
+
+.Content Security Policy Example
+====
+[source]
+----
+Content-Security-Policy: script-src https://trustedscripts.example.com
+----
+====
+
+An attempt to load a script from another source other than what is declared in the `script-src` directive will be blocked by the user-agent.
+Additionally, if the https://www.w3.org/TR/CSP2/#directive-report-uri[report-uri] directive is declared in the security policy, then the violation will be reported by the user-agent to the declared URL.
+
+For example, if a web application violates the declared security policy, the following response header will instruct the user-agent to send violation reports to the URL specified in the policy's `report-uri` directive.
+
+.Content Security Policy with report-uri
+====
+[source]
+----
+Content-Security-Policy: script-src https://trustedscripts.example.com; report-uri /csp-report-endpoint/
+----
+====
+
+https://www.w3.org/TR/CSP2/#violation-reports[Violation reports] are standard JSON structures that can be captured either by the web application's own API or by a publicly hosted CSP violation reporting service, such as, https://report-uri.com/.
+
+The `Content-Security-Policy-Report-Only` header provides the capability for web application authors and administrators to monitor security policies, rather than enforce them.
+This header is typically used when experimenting and/or developing security policies for a site.
+When a policy is deemed effective, it can be enforced by using the `Content-Security-Policy` header field instead.
+
+Given the following response header, the policy declares that scripts may be loaded from one of two possible sources.
+
+.Content Security Policy Report Only
+====
+[source]
+----
+Content-Security-Policy-Report-Only: script-src 'self' https://trustedscripts.example.com; report-uri /csp-report-endpoint/
+----
+====
+
+If the site violates this policy, by attempting to load a script from _evil.com_, the user-agent will send a violation report to the declared URL specified by the _report-uri_ directive, but still allow the violating resource to load nevertheless.
+
+Applying Content Security Policy to a web application is often a non-trivial undertaking.
+The following resources may provide further assistance in developing effective security policies for your site.
+
+https://www.html5rocks.com/en/tutorials/security/content-security-policy/[An Introduction to Content Security Policy]
+
+https://developer.mozilla.org/en-US/docs/Web/Security/CSP[CSP Guide - Mozilla Developer Network]
+
+https://www.w3.org/TR/CSP2/[W3C Candidate Recommendation]
+
+[[headers-referrer]]
+== Referrer Policy
+
+[NOTE]
+====
+Refer to 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 leverage to manage the referrer field, which contains the last
+page the user was on.
+
+Spring Security's approach is to use https://www.w3.org/TR/referrer-policy/[Referrer Policy] header, which provides different https://www.w3.org/TR/referrer-policy/#referrer-policies[policies]:
+
+.Referrer Policy Example
+====
+[source]
+----
+Referrer-Policy: same-origin
+----
+====
+
+The Referrer-Policy response header instructs the browser to let the destination knows the source where the user was previously.
+
+[[headers-feature]]
+== Feature Policy
+
+[NOTE]
+====
+Refer to 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 allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
+
+.Feature Policy Example
+====
+[source]
+----
+Feature-Policy: geolocation 'self'
+----
+====
+
+With Feature Policy, developers can opt-in to a set of "policies" for the browser to enforce on specific features used throughout your site.
+These policies restrict what APIs the site can access or modify the browser's default behavior for certain features.
+
+
+[[headers-permissions]]
+== Permissions Policy
+
+[NOTE]
+====
+Refer to 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 allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
+
+.Permissions Policy Example
+====
+[source]
+----
+Permissions-Policy: geolocation=(self)
+----
+====
+
+With Permissions Policy, developers can opt-in to a set of "policies" for the browser to enforce on specific features used throughout your site.
+These policies restrict what APIs the site can access or modify the browser's default behavior for certain features.
+
+
+[[headers-clear-site-data]]
+== Clear Site Data
+
+[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.
+====
+
+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:
+
+[source]
+----
+Clear-Site-Data: "cache", "cookies", "storage", "executionContexts"
+----
+
+This is a nice clean-up action to perform on logout.
+
+
+[[headers-custom]]
+== Custom Headers
+
+[NOTE]
+====
+Refer to the relevant section to see how to configure <<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.
@@ -0,0 +1,32 @@
+[[http]]
+= HTTP
+
+All HTTP based communication, including https://www.troyhunt.com/heres-why-your-static-website-needs-https/[static resources], should be protected https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html[using TLS].
+
+As a framework, Spring Security does not handle HTTP connections and thus does not provide support for HTTPS directly.
+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.
+
+[[http-hsts]]
+== Strict Transport Security
+
+Spring Security provides support for <<headers-hsts,Strict Transport Security>> and enables it by default.
+
+[[http-proxy-server]]
+== Proxy Server Configuration
+
+When using a proxy server it is important to ensure that you have configured your application properly.
+For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080.
+Without proper configuration, the application server will not know that the load balancer exists and treat the request as though https://192.168.1:8080 was requested by the client.
+
+To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used.
+To make the application aware of this, you need to either configure your application server aware of the X-Forwarded headers.
+For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
+Alternatively, Spring users can leverage https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[ForwardedHeaderFilter].
+
+Spring Boot users may use the `server.use-forward-headers` property to configure the application.
+See the https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-use-tomcat-behind-a-proxy-server[Spring Boot documentation] for further details.
@@ -0,0 +1,12 @@
+[[exploits]]
+= Protection Against Exploits
+
+Spring Security provides protection against common exploits.
+Whenever possible, the protection is enabled by default.
+Below you will find high level description of the various exploits that Spring Security protects against.
+
+include::csrf.adoc[leveloffset=+1]
+
+include::headers.adoc[leveloffset=+1]
+
+include::http.adoc[leveloffset=+1]
@@ -0,0 +1,6 @@
+[[features]]
+= Features
+
+Spring Security provides comprehensive support for <<authentication,authentication>>, authorization, and protection against <<exploits,common exploits>>.
+It also provides integration with other libraries to simplify its usage.
+
@@ -0,0 +1,339 @@
+[[getting]]
+= 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.
+
+== Release Numbering
+
+Spring Security versions are formatted as MAJOR.MINOR.PATCH such that:
+
+* MAJOR versions may contain breaking changes.
+Typically, these are done to provide improved security to match modern security practices.
+* MINOR versions contain enhancements but are considered passive updates
+* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
+
+
+[[maven]]
+== Usage with Maven
+
+As most open source projects, Spring Security deploys its dependencies as Maven artifacts.
+The topics in this section provide detail on how to consume Spring Security when using Maven.
+
+[[getting-maven-boot]]
+=== Spring Boot with Maven
+
+Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies together.
+The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
+
+Alternatively, you can manually add the starter, as the following example shows:
+
+
+.pom.xml
+====
+[source,xml,subs="verbatim,attributes"]
+----
+<dependencies>
+	<!-- ... other dependency elements ... -->
+	<dependency>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starter-security</artifactId>
+	</dependency>
+</dependencies>
+----
+====
+
+Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
+If you wish to override the Spring Security version, you may do so by providing a Maven property, as the following example shows:
+
+.pom.xml
+====
+[source,xml,subs="verbatim,attributes"]
+----
+<properties>
+	<!-- ... -->
+	<spring-security.version>{spring-security-version}</spring-security.version>
+</dependencies>
+----
+====
+
+Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
+However, at times, you may need to update the version of Spring Framework as well.
+You can do so by adding a Maven property, as the following example shows:
+
+.pom.xml
+====
+[source,xml,subs="verbatim,attributes"]
+----
+<properties>
+	<!-- ... -->
+	<spring.version>{spring-core-version}</spring.version>
+</dependencies>
+----
+====
+
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+
+[[getting-maven-no-boot]]
+=== Maven Without Spring Boot
+
+When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so:
+
+.pom.xml
+====
+[source,xml,ubs="verbatim,attributes"]
+----
+<dependencyManagement>
+	<dependencies>
+		<!-- ... other dependency elements ... -->
+		<dependency>
+			<groupId>org.springframework.security</groupId>
+			<artifactId>spring-security-bom</artifactId>
+			<version>{spring-security-version}</version>
+			<type>pom</type>
+			<scope>import</scope>
+		</dependency>
+	</dependencies>
+</dependencyManagement>
+----
+====
+
+A minimal Spring Security Maven set of dependencies typically looks like the following:
+
+.pom.xml
+====
+[source,xml,subs="verbatim,attributes"]
+----
+<dependencies>
+	<!-- ... other dependency elements ... -->
+	<dependency>
+		<groupId>org.springframework.security</groupId>
+		<artifactId>spring-security-web</artifactId>
+	</dependency>
+	<dependency>
+		<groupId>org.springframework.security</groupId>
+		<artifactId>spring-security-config</artifactId>
+	</dependency>
+</dependencies>
+----
+====
+
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<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.
+The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml` as the following example shows:
+
+.pom.xml
+====
+[source,xml,subs="verbatim,attributes"]
+----
+<dependencyManagement>
+	<dependencies>
+		<!-- ... other dependency elements ... -->
+		<dependency>
+			<groupId>org.springframework</groupId>
+			<artifactId>spring-framework-bom</artifactId>
+			<version>{spring-core-version}</version>
+			<type>pom</type>
+			<scope>import</scope>
+		</dependency>
+	</dependencies>
+</dependencyManagement>
+----
+====
+
+The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules.
+
+NOTE: This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
+For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
+
+[[maven-repositories]]
+=== Maven Repositories
+All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
+
+If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined, as the following example shows:
+
+.pom.xml
+====
+[source,xml]
+----
+<repositories>
+	<!-- ... possibly other repository elements ... -->
+	<repository>
+		<id>spring-snapshot</id>
+		<name>Spring Snapshot Repository</name>
+		<url>https://repo.spring.io/snapshot</url>
+	</repository>
+</repositories>
+----
+====
+
+If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
+
+.pom.xml
+====
+[source,xml]
+----
+<repositories>
+	<!-- ... possibly other repository elements ... -->
+	<repository>
+		<id>spring-milestone</id>
+		<name>Spring Milestone Repository</name>
+		<url>https://repo.spring.io/milestone</url>
+	</repository>
+</repositories>
+----
+====
+
+[[getting-gradle]]
+== Gradle
+
+As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for first-class Gradle support.
+The following topics provide detail on how to consume Spring Security when using Gradle.
+
+[[getting-gradle-boot]]
+=== Spring Boot with Gradle
+
+Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies together.
+The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
+
+Alternatively, you can manually add the starter, as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+dependencies {
+	compile "org.springframework.boot:spring-boot-starter-security"
+}
+----
+====
+
+Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version.
+If you wish to override the Spring Security version, you may do so by providing a Gradle property, as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+ext['spring-security.version']='{spring-security-version}'
+----
+====
+
+Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
+However, at times, you may need to update the version of Spring Framework as well.
+You can do so by adding a Gradle property, as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+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>>.
+
+=== Gradle Without Spring Boot
+
+When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
+You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+plugins {
+	id "io.spring.dependency-management" version "1.0.6.RELEASE"
+}
+
+dependencyManagement {
+	imports {
+		mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
+	}
+}
+----
+====
+
+A minimal Spring Security Maven set of dependencies typically looks like the following:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+dependencies {
+	compile "org.springframework.security:spring-security-web"
+	compile "org.springframework.security:spring-security-config"
+}
+----
+====
+
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<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.
+The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml`.
+You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+plugins {
+	id "io.spring.dependency-management" version "1.0.6.RELEASE"
+}
+
+dependencyManagement {
+	imports {
+		mavenBom 'org.springframework:spring-framework-bom:{spring-core-version}'
+	}
+}
+----
+====
+
+The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules.
+
+[[gradle-repositories]]
+=== Gradle Repositories
+All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases. The following example shows how to do so:
+
+.build.gradle
+====
+[source,groovy]
+----
+repositories {
+	mavenCentral()
+}
+----
+====
+
+If you use a SNAPSHOT version, you need to ensure you have the Spring Snapshot repository defined, as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+----
+repositories {
+	maven { url 'https://repo.spring.io/snapshot' }
+}
+----
+====
+
+If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
+
+.build.gradle
+====
+[source,groovy]
+----
+repositories {
+	maven { url 'https://repo.spring.io/milestone' }
+}
+----
+====
@@ -0,0 +1,5 @@
+= Overview
+
+Spring Security is a framework that provides authentication, authorization, and protection against common attacks.
+With first class support for both imperative and reactive applications, it is the de-facto standard for securing Spring-based applications.
+
@@ -0,0 +1,342 @@
+// FIXME: This might make sense in Getting Spring Security along with the artifact information
+
+[[modules]]
+= Project Modules and Dependencies
+In Spring Security 3.0, the codebase was sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
+If you use Maven to build your project, these are the modules you should add to your `pom.xml`.
+Even if you do not use Maven, we recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
+Another good idea is to examine the libraries that are included in the sample applications.
+
+This section provides a reference of the modules in Spring Security and the additional dependencies that they require in order to function in a running application.
+We don't include dependencies that are only used when building or testing Spring Security itself.
+Nor do we include transitive dependencies which are required by external dependencies.
+
+The version of Spring required is listed on the project website, so the specific versions are omitted for Spring dependencies below.
+Note that some of the dependencies listed as "optional" below may still be required for other non-security functionality in a Spring application.
+Also dependencies listed as "optional" may not actually be marked as such in the project's Maven POM files if they are used in most applications.
+They are "optional" only in the sense that you don't need them unless you are using the specified functionality.
+
+Where a module depends on another Spring Security module, the non-optional dependencies of the module it depends on are also assumed to be required and are not listed separately.
+
+
+[[spring-security-core]]
+== Core -- `spring-security-core.jar`
+This module contains core authentication and access-contol classes and interfaces, remoting support, and basic provisioning APIs.
+It is required by any application that uses Spring Security.
+It supports standalone applications, remote clients, method (service layer) security, and JDBC user provisioning.
+It contains the following top-level packages:
+
+* `org.springframework.security.core`
+* `org.springframework.security.access`
+* `org.springframework.security.authentication`
+* `org.springframework.security.provisioning`
+
+.Core Dependencies
+|===
+| Dependency | Version | Description
+
+| ehcache
+| 1.6.2
+| Required if the Ehcache-based user cache implementation is used (optional).
+
+| spring-aop
+|
+| Method security is based on Spring AOP
+
+| spring-beans
+|
+| Required for Spring configuration
+
+| spring-expression
+|
+| Required for expression-based method security (optional)
+
+| spring-jdbc
+|
+| Required if using a database to store user data (optional).
+
+| spring-tx
+|
+| Required if using a database to store user data (optional).
+
+| aspectjrt
+| 1.6.10
+| Required if using AspectJ support (optional).
+
+| jsr250-api
+| 1.0
+| Required if you are using JSR-250 method-security annotations (optional).
+|===
+
+
+[[spring-security-remoting]]
+== Remoting -- `spring-security-remoting.jar`
+This module provides integration with Spring Remoting.
+You do not need this unless you are writing a remote client that uses Spring Remoting.
+The main package is `org.springframework.security.remoting`.
+
+.Remoting Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-web
+|
+| Required for clients which use HTTP remoting support.
+|===
+
+[[spring-security-web]]
+== Web -- `spring-security-web.jar`
+This module contains filters and related web-security infrastructure code.
+It contains anything with a servlet API dependency.
+You need it if you require Spring Security web authentication services and URL-based access-control.
+The main package is `org.springframework.security.web`.
+
+.Web Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-web
+|
+| Spring web support classes are used extensively.
+
+| spring-jdbc
+|
+| Required for JDBC-based persistent remember-me token repository (optional).
+
+| spring-tx
+|
+| Required by remember-me persistent token repository implementations (optional).
+|===
+
+[[spring-security-config]]
+== Config -- `spring-security-config.jar`
+This module contains the security namespace parsing code and Java configuration code.
+You need it if you use the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
+The main package is `org.springframework.security.config`.
+None of the classes are intended for direct use in an application.
+
+.Config Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-security-web
+|
+| Required if you are using any web-related namespace configuration (optional).
+
+| spring-security-ldap
+|
+| Required if you are using the LDAP namespace options (optional).
+
+| spring-security-openid
+|
+| Required if you are using OpenID authentication (optional).
+
+| aspectjweaver
+| 1.6.10
+| Required if using the protect-pointcut namespace syntax (optional).
+|===
+
+[[spring-security-ldap]]
+== LDAP -- `spring-security-ldap.jar`
+This module provides LDAP authentication and provisioning code.
+It is required if you need to use LDAP authentication or manage LDAP user entries.
+The top-level package is `org.springframework.security.ldap`.
+
+.LDAP Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-ldap-core
+| 1.3.0
+| LDAP support is based on Spring LDAP.
+
+| spring-tx
+|
+| Data exception classes are required.
+
+| apache-ds footnote:[The modules `apacheds-core`, `apacheds-core-entry`, `apacheds-protocol-shared`, `apacheds-protocol-ldap` and `apacheds-server-jndi` are required.
+]
+| 1.5.5
+| Required if you are using an embedded LDAP server (optional).
+
+| shared-ldap
+| 0.9.15
+| Required if you are using an embedded LDAP server (optional).
+
+| ldapsdk
+| 4.1
+| Mozilla LdapSDK.
+Used for decoding LDAP password policy controls if you are using password-policy functionality with OpenLDAP, for example.
+|===
+
+[[spring-security-oauth2-core]]
+== OAuth 2.0 Core -- `spring-security-oauth2-core.jar`
+`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the OAuth 2.0 Authorization Framework and for OpenID Connect Core 1.0.
+It is required by applications that use OAuth 2.0 or OpenID Connect Core 1.0, such as client, resource server, and authorization server.
+The top-level package is `org.springframework.security.oauth2.core`.
+
+
+[[spring-security-oauth2-client]]
+== OAuth 2.0 Client -- `spring-security-oauth2-client.jar`
+`spring-security-oauth2-client.jar` contains Spring Security's client support for OAuth 2.0 Authorization Framework and OpenID Connect Core 1.0.
+It is required by applications that use OAuth 2.0 Login or OAuth Client support.
+The top-level package is `org.springframework.security.oauth2.client`.
+
+
+[[spring-security-oauth2-jose]]
+== OAuth 2.0 JOSE -- `spring-security-oauth2-jose.jar`
+`spring-security-oauth2-jose.jar` contains Spring Security's support for the JOSE (Javascript Object Signing and Encryption) framework.
+The JOSE framework is intended to provide a method to securely transfer claims between parties.
+It is built from a collection of specifications:
+
+* JSON Web Token (JWT)
+* JSON Web Signature (JWS)
+* JSON Web Encryption (JWE)
+* JSON Web Key (JWK)
+
+It contains the following top-level packages:
+
+* `org.springframework.security.oauth2.jwt`
+* `org.springframework.security.oauth2.jose`
+
+[[spring-security-oauth2-resource-server]]
+== OAuth 2.0 Resource Server -- `spring-security-oauth2-resource-server.jar`
+`spring-security-oauth2-resource-server.jar` contains Spring Security's support for OAuth 2.0 Resource Servers.
+It is used to protect APIs via OAuth 2.0 Bearer Tokens.
+The top-level package is `org.springframework.security.oauth2.server.resource`.
+
+[[spring-security-acl]]
+== ACL -- `spring-security-acl.jar`
+This module contains a specialized domain object ACL implementation.
+It is used to apply security to specific domain object instances within your application.
+The top-level package is `org.springframework.security.acls`.
+
+.ACL Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| ehcache
+| 1.6.2
+| Required if the Ehcache-based ACL cache implementation is used (optional if you are using your own implementation).
+
+| spring-jdbc
+|
+| Required if you are using the default JDBC-based AclService (optional if you implement your own).
+
+| spring-tx
+|
+| Required if you are using the default JDBC-based AclService (optional if you implement your own).
+|===
+
+[[spring-security-cas]]
+== CAS -- `spring-security-cas.jar`
+This module contains Spring Security's CAS client integration.
+You should use it if you want to use Spring Security web authentication with a CAS single sign-on server.
+The top-level package is `org.springframework.security.cas`.
+
+.CAS Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-security-web
+|
+|
+
+| cas-client-core
+| 3.1.12
+| The JA-SIG CAS Client.
+This is the basis of the Spring Security integration.
+
+| ehcache
+| 1.6.2
+| Required if you are using the Ehcache-based ticket cache (optional).
+|===
+
+[[spring-security-openid]]
+== OpenID -- `spring-security-openid.jar`
+[NOTE]
+The OpenID 1.0 and 2.0 protocols have been deprecated and users are encouraged to migrate to OpenID Connect, which is supported by spring-security-oauth2.
+
+This module contains OpenID web authentication support.
+It is used to authenticate users against an external OpenID server.
+The top-level package is `org.springframework.security.openid`.
+It requires OpenID4Java.
+
+.OpenID Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-security-web
+|
+|
+
+| openid4java-nodeps
+| 0.9.6
+| Spring Security's OpenID integration uses OpenID4Java.
+
+| httpclient
+| 4.1.1
+| openid4java-nodeps depends on HttpClient 4.
+
+| guice
+| 2.0
+| openid4java-nodeps depends on Guice 2.
+|===
+
+
+[[spring-security-test]]
+== Test -- `spring-security-test.jar`
+This module contains support for testing with Spring Security.
+
+[[spring-security-taglibs]]
+== Taglibs -- `spring-secuity-taglibs.jar`
+Provides Spring Security's JSP tag implementations.
+
+.Taglib Dependencies
+|===
+| Dependency | Version | Description
+
+| spring-security-core
+|
+|
+
+| spring-security-web
+|
+|
+
+| spring-security-acl
+|
+| Required if you are using the `accesscontrollist` tag or `hasPermission()` expressions with ACLs (optional).
+
+| spring-expression
+|
+| Required if you are using SPEL expressions in your tag access constraints.
+|===
@@ -0,0 +1,12 @@
+[[prerequisites]]
+= Prerequisites
+
+Spring Security requires a Java 8 or higher Runtime Environment.
+
+As Spring Security aims to operate in a self-contained manner, you do not need to place any special configuration files in your Java Runtime Environment.
+In particular, you need not configure a special Java Authentication and Authorization Service (JAAS) policy file or place Spring Security into common classpath locations.
+
+Similarly, if you use an EJB Container or Servlet Container, you need not put any special configuration files anywhere nor include Spring Security in a server classloader.
+All the required files are contained within your application.
+
+This design offers maximum deployment time flexibility, as you can copy your target artifact (be it a JAR, WAR, or EAR) from one system to another and it immediately works.
@@ -0,0 +1,10 @@
+[[samples]]
+= Samples
+
+Spring Security includes many {gh-samples-url}[samples] applications.
+
+[NOTE]
+====
+These samples are being migrated to a separate project, however, you can still find
+the not migrated samples in an older branch of the {gh-old-samples-url}[Spring Security repository].
+====
@@ -0,0 +1,43 @@
+[[new]]
+== What's New in Spring Security 5.6
+
+Spring Security 5.6 provides a number of new features.
+Below are the highlights of the release.
+
+[[whats-new-servlet]]
+=== Servlet
+* Core
+
+** Introduced https://github.com/spring-projects/spring-security/issues/10226[`SecurityContextChangedListener`]
+
+* Configuration
+
+** Introduced https://github.com/spring-projects/spring-security/pull/9630[`AuthorizationManager`] for method security
+
+* SAML 2.0 Service Provider
+
+** Added https://github.com/spring-projects/spring-security/pull/9483[SAML 2.0 Single Logout Support]
+** Added https://github.com/spring-projects/spring-security/pull/10060[Saml2AuthenticationRequestRepository]
+** Added https://github.com/spring-projects/spring-security/issues/9486[`RelyingPartyRegistrationResolver`]
+** Improved ``Saml2LoginConfigurer``'s handling of https://github.com/spring-projects/spring-security/issues/10268[`Saml2AuthenticationTokenConverter`]
+
+
+* OAuth 2.0 Login
+
+** Added https://github.com/spring-projects/spring-security/pull/10041[`Converter` for `Authentication` result]
+
+* OAuth 2.0 Client
+
+** Improved https://github.com/spring-projects/spring-security/pull/9791[client credentials] encoding
+** Improved https://github.com/spring-projects/spring-security/pull/9779[access token response] parsing
+** Added https://github.com/spring-projects/spring-security/pull/10155[custom grant types support] for authorization requests
+
+* Testing
+
+** Added support to https://github.com/spring-projects/spring-security/pull/9737[propagate the TestSecurityContextHolder to SecurityContextHolder]
+
+[[whats-new-webflux]]
+=== WebFlux
+
+** Improved https://github.com/spring-projects/spring-security/pull/9791[client credentials] encoding
+** Added https://github.com/spring-projects/spring-security/pull/10131[custom headers support] for access token requests
@@ -0,0 +1,71 @@
+
+[[webflux-cors]]
+= CORS
+
+Spring Framework provides https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#webflux-cors-intro[first class support for CORS].
+CORS must be processed before Spring Security because the pre-flight request will not contain any cookies (i.e. the `JSESSIONID`).
+If the request does not contain any cookies and Spring Security is first, the request will determine the user is not authenticated (since there are no cookies in the request) and reject it.
+
+The easiest way to ensure that CORS is handled first is to use the `CorsWebFilter`.
+Users can integrate the `CorsWebFilter` with Spring Security by providing a `CorsConfigurationSource`.
+For example, the following will integrate CORS support within Spring Security:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+CorsConfigurationSource corsConfigurationSource() {
+	CorsConfiguration configuration = new CorsConfiguration();
+	configuration.setAllowedOrigins(Arrays.asList("https://example.com"));
+	configuration.setAllowedMethods(Arrays.asList("GET","POST"));
+	UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+	source.registerCorsConfiguration("/**", configuration);
+	return source;
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun corsConfigurationSource(): CorsConfigurationSource {
+    val configuration = CorsConfiguration()
+    configuration.allowedOrigins = listOf("https://example.com")
+    configuration.allowedMethods = listOf("GET", "POST")
+    val source = UrlBasedCorsConfigurationSource()
+    source.registerCorsConfiguration("/**", configuration)
+    return source
+}
+----
+====
+
+The following will disable the CORS integration within Spring Security:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.cors(cors -> cors.disable());
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        cors {
+            disable()
+        }
+    }
+}
+----
+====
@@ -0,0 +1,412 @@
+[[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.
+
+[[webflux-csrf-using]]
+== Using Spring Security CSRF Protection
+The steps to using Spring Security's CSRF protection are outlined below:
+
+* <<webflux-csrf-idempotent,Use proper HTTP verbs>>
+* <<webflux-csrf-configure,Configure CSRF Protection>>
+* <<webflux-csrf-include,Include the CSRF Token>>
+
+[[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>>.
+
+[[webflux-csrf-configure]]
+=== Configure CSRF Protection
+The next step is to configure Spring Security's CSRF protection within your application.
+Spring Security's CSRF protection is enabled by default, but you may need to customize the configuration.
+Below are a few common customizations.
+
+[[webflux-csrf-configure-custom-repository]]
+==== Custom CsrfTokenRepository
+
+By default Spring Security stores the expected CSRF token in the `WebSession` using `WebSessionServerCsrfTokenRepository`.
+There can be cases where users will want to configure a custom `ServerCsrfTokenRepository`.
+For example, it might be desirable to persist the `CsrfToken` in a cookie to <<webflux-csrf-include-ajax-auto,support a JavaScript based application>>.
+
+By default the `CookieServerCsrfTokenRepository` will write to a cookie named `XSRF-TOKEN` and read it from a header named `X-XSRF-TOKEN` or the HTTP parameter `_csrf`.
+These defaults come from https://docs.angularjs.org/api/ng/service/$http#cross-site-request-forgery-xsrf-protection[AngularJS]
+
+You can configure `CookieServerCsrfTokenRepository` in Java Configuration using:
+
+.Store CSRF Token in a Cookie
+====
+.Java
+[source,java,role="primary"]
+-----
+@Bean
+public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.csrf(csrf -> csrf.csrfTokenRepository(CookieServerCsrfTokenRepository.withHttpOnlyFalse()))
+	return http.build();
+}
+-----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+-----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        csrf {
+            csrfTokenRepository = CookieServerCsrfTokenRepository.withHttpOnlyFalse()
+        }
+    }
+}
+-----
+====
+
+[NOTE]
+====
+The sample explicitly sets `cookieHttpOnly=false`.
+This is necessary to allow JavaScript (i.e. AngularJS) to read it.
+If you do not need the ability to read the cookie with JavaScript directly, it is recommended to omit `cookieHttpOnly=false` (by using `new CookieServerCsrfTokenRepository()` instead) to improve security.
+====
+
+[[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>>.
+
+The Java configuration below will disable CSRF protection.
+
+.Disable CSRF Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.csrf(csrf -> csrf.disable()))
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+-----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        csrf {
+            disable()
+        }
+    }
+}
+-----
+====
+
+[[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.
+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`.
+This means that any view technology can access the `Mono<CsrfToken>` to expose the expected token as either a <<webflux-csrf-include-form-attr,form>> or <<webflux-csrf-include-ajax-meta,meta tag>>.
+
+[[webflux-csrf-include-subscribe]]
+If your view technology does not provide a simple way to subscribe to the `Mono<CsrfToken>`, a common pattern is to use Spring's `@ControllerAdvice` to expose the `CsrfToken` directly.
+For example, the following code will place the `CsrfToken` on the default attribute name (`_csrf`) used by Spring Security's <<webflux-csrf-include-form-auto,CsrfRequestDataValueProcessor>> to automatically include the CSRF token as a hidden input.
+
+.`CsrfToken` as `@ModelAttribute`
+====
+.Java
+[source,java,role="primary"]
+----
+@ControllerAdvice
+public class SecurityControllerAdvice {
+	@ModelAttribute
+	Mono<CsrfToken> csrfToken(ServerWebExchange exchange) {
+		Mono<CsrfToken> csrfToken = exchange.getAttribute(CsrfToken.class.getName());
+		return csrfToken.doOnSuccess(token -> exchange.getAttributes()
+				.put(CsrfRequestDataValueProcessor.DEFAULT_CSRF_ATTR_NAME, token));
+	}
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@ControllerAdvice
+class SecurityControllerAdvice {
+    @ModelAttribute
+    fun csrfToken(exchange: ServerWebExchange): Mono<CsrfToken> {
+        val csrfToken: Mono<CsrfToken>? = exchange.getAttribute(CsrfToken::class.java.name)
+        return csrfToken!!.doOnSuccess { token ->
+            exchange.attributes[CsrfRequestDataValueProcessor.DEFAULT_CSRF_ATTR_NAME] = token
+        }
+    }
+}
+----
+====
+
+Fortunately, Thymeleaf provides <<webflux-csrf-include-form-auto,integration>> that works without any additional work.
+
+[[webflux-csrf-include-form]]
+==== Form URL Encoded
+In order to post an HTML form the CSRF token must be included in the form as a hidden input.
+For example, the rendered HTML might look like:
+
+.CSRF Token HTML
+====
+[source,html]
+----
+<input type="hidden"
+	name="_csrf"
+	value="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
+----
+====
+
+Next we will discuss various ways of including the CSRF token in a form as a hidden input.
+
+[[webflux-csrf-include-form-auto]]
+===== Automatic CSRF Token Inclusion
+
+Spring Security's CSRF support provides integration with Spring's https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/result/view/RequestDataValueProcessor.html[RequestDataValueProcessor] via its https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/reactive/result/view/CsrfRequestDataValueProcessor.html[CsrfRequestDataValueProcessor].
+In order for `CsrfRequestDataValueProcessor` to work, the `Mono<CsrfToken>` must be subscribed to and the `CsrfToken` must be <<webflux-csrf-include-subscribe,exposed as an attribute>> that matches https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/reactive/result/view/CsrfRequestDataValueProcessor.html#DEFAULT_CSRF_ATTR_NAME[DEFAULT_CSRF_ATTR_NAME].
+
+Fortunately, Thymeleaf https://www.thymeleaf.org/doc/tutorials/2.1/thymeleafspring.html#integration-with-requestdatavalueprocessor[provides support] to take care of all the boilerplate for you by integrating with `RequestDataValueProcessor` to ensure that forms that have an unsafe HTTP method (i.e. post) will automatically include the actual CSRF token.
+
+[[webflux-csrf-include-form-attr]]
+===== CsrfToken Request Attribute
+
+If the <<webflux-csrf-include,other options>> for including the actual CSRF token in the request do not work, you can take advantage of the fact that the `Mono<CsrfToken>` <<webflux-csrf-include,is exposed>> as a `ServerWebExchange` attribute named `org.springframework.security.web.server.csrf.CsrfToken`.
+
+The Thymeleaf sample below assumes that you <<webflux-csrf-include-subscribe,expose>> the `CsrfToken` on an attribute named `_csrf`.
+
+.CSRF Token in Form with Request Attribute
+====
+[source,html]
+----
+<form th:action="@{/logout}"
+	method="post">
+<input type="submit"
+	value="Log out" />
+<input type="hidden"
+	th:name="${_csrf.parameterName}"
+	th:value="${_csrf.token}"/>
+</form>
+----
+====
+
+[[webflux-csrf-include-ajax]]
+==== Ajax and JSON Requests
+If you are using JSON, then it is not possible to submit the CSRF token within an HTTP parameter.
+Instead you can submit the token within a HTTP header.
+
+In the following sections we will discuss various ways of including the CSRF token as an HTTP request header in JavaScript based applications.
+
+[[webflux-csrf-include-ajax-auto]]
+===== Automatic Inclusion
+
+Spring Security can easily be <<webflux-csrf-configure-custom-repository,configured>> to store the expected CSRF token in a cookie.
+By storing the expected CSRF in a cookie, JavaScript frameworks like https://docs.angularjs.org/api/ng/service/$http#cross-site-request-forgery-xsrf-protection[AngularJS] will automatically include the actual CSRF token in the HTTP request headers.
+
+[[webflux-csrf-include-ajax-meta]]
+===== Meta tags
+
+An alternative pattern to <<webflux-csrf-include-form-auto,exposing the CSRF in a cookie>> is to include the CSRF token within your `meta` tags.
+The HTML might look something like this:
+
+.CSRF meta tag HTML
+====
+[source,html]
+----
+<html>
+<head>
+	<meta name="_csrf" content="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
+	<meta name="_csrf_header" content="X-CSRF-TOKEN"/>
+	<!-- ... -->
+</head>
+<!-- ... -->
+----
+====
+
+Once the meta tags contained the CSRF token, the JavaScript code would read the meta tags and include the CSRF token as a header.
+If you were using jQuery, this could be done with the following:
+
+.AJAX send CSRF Token
+====
+[source,javascript]
+----
+$(function () {
+	var token = $("meta[name='_csrf']").attr("content");
+	var header = $("meta[name='_csrf_header']").attr("content");
+	$(document).ajaxSend(function(e, xhr, options) {
+		xhr.setRequestHeader(header, token);
+	});
+});
+----
+====
+
+The sample below assumes that you <<webflux-csrf-include-subscribe,expose>> the `CsrfToken` on an attribute named `_csrf`.
+An example of doing this with Thymeleaf is shown below:
+
+.CSRF meta tag JSP
+====
+[source,html]
+----
+<html>
+<head>
+	<meta name="_csrf" th:content="${_csrf.token}"/>
+	<!-- default header name is X-CSRF-TOKEN -->
+	<meta name="_csrf_header" th:content="${_csrf.headerName}"/>
+	<!-- ... -->
+</head>
+<!-- ... -->
+----
+====
+
+[[webflux-csrf-considerations]]
+== 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.
+
+
+[[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.
+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.
+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.
+
+The easiest approach is to use a form to log out.
+If you really want a link, you can use JavaScript to have the link perform a POST (i.e. maybe on a hidden form).
+For browsers with JavaScript that is disabled, you can optionally have the link take the user to a log out confirmation page that will perform the POST.
+
+If you really want to use HTTP GET with logout you can do so, but remember this is generally not recommended.
+For example, the following Java Configuration will perform logout with the URL `/logout` is requested with any HTTP method:
+
+// FIXME: This should be a link to log out documentation
+
+.Log out with HTTP GET
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.logout(logout -> logout.requiresLogout(new PathPatternParserServerWebExchangeMatcher("/logout")))
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        logout {
+            requiresLogout = PathPatternParserServerWebExchangeMatcher("/logout")
+        }
+    }
+}
+----
+====
+
+
+[[webflux-considerations-csrf-timeouts]]
+=== CSRF and Session Timeouts
+
+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.
+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.
+For details, refer to the <<webflux-csrf-configure-custom-repository>> section.
+
+// FIXME: We should add a custom AccessDeniedHandler section in the reference and update the links above
+
+// 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.
+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]
+====
+More information about using multipart forms with Spring can be found within the https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/web-reactive.html#webflux-multipart[Multipart Data] section of the Spring reference.
+====
+
+[[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.
+
+In a WebFlux application, this can be configured with the following configuration:
+
+.Enable obtaining CSRF token from multipart/form-data
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.csrf(csrf -> csrf.tokenFromMultipartDataEnabled(true))
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+		// ...
+        csrf {
+            tokenFromMultipartDataEnabled = true
+        }
+    }
+}
+----
+====
+
+[[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.
+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:
+
+.CSRF Token in Action
+====
+[source,html]
+----
+<form method="post"
+	th:action="@{/upload(${_csrf.parameterName}=${_csrf.token})}"
+	enctype="multipart/form-data">
+----
+====
+
+[[webflux-csrf-considerations-override-method]]
+=== HiddenHttpMethodFilter
+We have <<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].
@@ -0,0 +1,580 @@
+[[webflux-headers]]
+= Security HTTP Response Headers
+
+<<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.
+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>>.
+
+You can easily do this with the following Configuration:
+
+.Customize Default Security Headers
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.frameOptions(frameOptions -> frameOptions
+				.mode(Mode.SAMEORIGIN)
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            frameOptions {
+                mode = Mode.SAMEORIGIN
+            }
+        }
+    }
+}
+----
+====
+
+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:
+
+.Disable HTTP Security Response Headers
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers.disable());
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            disable()
+        }
+    }
+}
+----
+====
+
+[[webflux-headers-cache-control]]
+== Cache Control
+
+Spring Security includes <<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.
+
+When using Spring WebFlux, this is typically done within your configuration.
+Details on how to do this can be found in the https://docs.spring.io/spring/docs/5.0.0.RELEASE/spring-framework-reference/web-reactive.html#webflux-config-static-resources[Static Resources] portion of the Spring Reference documentation
+
+If necessary, you can also disable Spring Security's cache control HTTP response headers.
+
+.Cache Control Disabled
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.cache(cache -> cache.disable())
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            cache {
+                disable()
+            }
+        }
+    }
+}
+----
+====
+
+
+[[webflux-headers-content-type-options]]
+== Content Type Options
+Spring Security includes <<headers-content-type-options,Content-Type>> headers by default.
+However, you can disable it with:
+
+.Content Type Options Disabled
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.contentTypeOptions(contentTypeOptions -> contentTypeOptions.disable())
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            contentTypeOptions {
+                disable()
+            }
+        }
+    }
+}
+----
+====
+
+[[webflux-headers-hsts]]
+== HTTP Strict Transport Security (HSTS)
+Spring Security provides the <<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:
+
+.Strict Transport Security
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.hsts(hsts -> hsts
+				.includeSubdomains(true)
+				.preload(true)
+				.maxAge(Duration.ofDays(365))
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            hsts {
+                includeSubdomains = true
+                preload = true
+                maxAge = Duration.ofDays(365)
+            }
+        }
+    }
+}
+----
+====
+
+[[webflux-headers-frame-options]]
+== X-Frame-Options
+By default, Spring Security disables rendering within an iframe using <<headers-frame-options,X-Frame-Options>>.
+
+You can customize frame options to use the same origin using the following:
+
+.X-Frame-Options: SAMEORIGIN
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.frameOptions(frameOptions -> frameOptions
+				.mode(SAMEORIGIN)
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            frameOptions {
+                mode = SAMEORIGIN
+            }
+        }
+    }
+}
+----
+====
+
+[[webflux-headers-xss-protection]]
+== X-XSS-Protection
+By default, Spring Security instructs browsers to block reflected XSS attacks using the <<headers-xss-protection,X-XSS-Protection header>.
+You can disable `X-XSS-Protection` with the following Configuration:
+
+.X-XSS-Protection Customization
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.xssProtection(xssProtection -> xssProtection.disable())
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            xssProtection {
+                disable()
+            }
+        }
+    }
+}
+----
+====
+
+[[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.
+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:
+
+.Content Security Policy Example
+====
+[source,http]
+----
+Content-Security-Policy: script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/
+----
+====
+
+You can enable the CSP header as shown below:
+
+.Content Security Policy
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.contentSecurityPolicy(policy -> policy
+				.policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            contentSecurityPolicy {
+                policyDirectives = "script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/"
+            }
+        }
+    }
+}
+----
+====
+
+To enable the CSP `report-only` header, provide the following configuration:
+
+.Content Security Policy Report Only
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.contentSecurityPolicy(policy -> policy
+				.policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
+				.reportOnly()
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            contentSecurityPolicy {
+                policyDirectives = "script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/"
+                reportOnly = true
+            }
+        }
+    }
+}
+----
+====
+
+[[webflux-headers-referrer]]
+== Referrer Policy
+
+Spring Security does not add <<headers-referrer,Referrer Policy>> headers by default.
+You can enable the Referrer Policy header using configuration as shown below:
+
+.Referrer Policy Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.referrerPolicy(referrer -> referrer
+				.policy(ReferrerPolicy.SAME_ORIGIN)
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            referrerPolicy {
+                policy = ReferrerPolicy.SAME_ORIGIN
+            }
+        }
+    }
+}
+----
+====
+
+
+[[webflux-headers-feature]]
+== Feature Policy
+
+Spring Security does not add <<headers-feature,Feature Policy>> headers by default.
+The following `Feature-Policy` header:
+
+.Feature-Policy Example
+====
+[source]
+----
+Feature-Policy: geolocation 'self'
+----
+====
+
+You can enable the Feature Policy header as shown below:
+
+.Feature-Policy Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.featurePolicy("geolocation 'self'")
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            featurePolicy("geolocation 'self'")
+        }
+    }
+}
+----
+====
+
+
+[[webflux-headers-permissions]]
+== Permissions Policy
+
+Spring Security does not add <<headers-permissions,Permissions Policy>> headers by default.
+The following `Permissions-Policy` header:
+
+.Permissions-Policy Example
+====
+[source]
+----
+Permissions-Policy: geolocation=(self)
+----
+====
+
+You can enable the Permissions Policy header as shown below:
+
+.Permissions-Policy Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.headers(headers -> headers
+			.permissionsPolicy(permissions -> permissions
+				.policy("geolocation=(self)")
+			)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        headers {
+            permissionsPolicy {
+                policy = "geolocation=(self)"
+            }
+        }
+    }
+}
+----
+====
+
+
+[[webflux-headers-clear-site-data]]
+== Clear Site Data
+
+Spring Security does not add <<headers-clear-site-data,Clear-Site-Data>> headers by default.
+The following Clear-Site-Data header:
+
+.Clear-Site-Data Example
+====
+----
+Clear-Site-Data: "cache", "cookies"
+----
+====
+
+can be sent on log out with the following configuration:
+
+.Clear-Site-Data Configuration
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	ServerLogoutHandler securityContext = new SecurityContextServerLogoutHandler();
+	ClearSiteDataServerHttpHeadersWriter writer = new ClearSiteDataServerHttpHeadersWriter(CACHE, COOKIES);
+	ServerLogoutHandler clearSiteData = new HeaderWriterServerLogoutHandler(writer);
+	DelegatingServerLogoutHandler logoutHandler = new DelegatingServerLogoutHandler(securityContext, clearSiteData);
+
+	http
+		// ...
+		.logout()
+			.logoutHandler(logoutHandler);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    val securityContext: ServerLogoutHandler = SecurityContextServerLogoutHandler()
+    val writer = ClearSiteDataServerHttpHeadersWriter(CACHE, COOKIES)
+    val clearSiteData: ServerLogoutHandler = HeaderWriterServerLogoutHandler(writer)
+    val customLogoutHandler = DelegatingServerLogoutHandler(securityContext, clearSiteData)
+
+    return http {
+        // ...
+        logout {
+            logoutHandler = customLogoutHandler
+        }
+    }
+}
+----
+====
@@ -0,0 +1,87 @@
+[[webflux-http]]
+= HTTP
+
+All HTTP based communication should be protected <<http,using TLS>>.
+
+Below you can find details around WebFlux specific features that assist with HTTPS usage.
+
+[[webflux-http-redirect]]
+== Redirect to HTTPS
+
+If a client makes a request using HTTP rather than HTTPS, Spring Security can be configured to redirect to HTTPS.
+
+For example, the following Java configuration will redirect any HTTP requests to HTTPS:
+
+.Redirect to HTTPS
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.redirectToHttps(withDefaults());
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        redirectToHttps { }
+    }
+}
+----
+====
+
+The configuration can easily be wrapped around an if statement to only be turned on in production.
+Alternatively, it can be enabled by looking for a property about the request that only happens in production.
+For example, if the production environment adds a header named `X-Forwarded-Proto` the following Java Configuration could be used:
+
+.Redirect to HTTPS when X-Forwarded
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.redirectToHttps(redirect -> redirect
+			.httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto"))
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        redirectToHttps {
+            httpsRedirectWhen {
+                it.request.headers.containsKey("X-Forwarded-Proto")
+            }
+        }
+    }
+}
+----
+====
+
+[[webflux-hsts]]
+== Strict Transport Security
+
+Spring Security provides support for <<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>>.
@@ -0,0 +1,7 @@
+= Protection Against Exploits
+
+include::csrf.adoc[leveloffset=+1]
+
+include::headers.adoc[leveloffset=+1]
+
+include::http.adoc[leveloffset=+1]
@@ -0,0 +1,23 @@
+= Reactive Applications
+
+include::webflux.adoc[leveloffset=+1]
+
+include::exploits/index.adoc[leveloffset=+1]
+
+include::oauth2/index.adoc[leveloffset=+1]
+
+include::registered-oauth2-authorized-client.adoc[leveloffset=+1]
+
+include::x509.adoc[leveloffset=+1]
+
+include::logout.adoc[leveloffset=+1]
+
+include::webclient.adoc[leveloffset=+1]
+
+include::method.adoc[leveloffset=+1]
+
+include::cors.adoc[leveloffset=+1]
+
+include::test.adoc[leveloffset=+1]
+
+include::rsocket.adoc[leveloffset=+1]
@@ -0,0 +1,28 @@
+[[reactive-logout]]
+= Logout
+
+Spring Security provides a logout endpoint by default.
+Once logged in, you can `GET /logout` to see a default logout confirmation page, or you can `POST /logout` to initiate logout.
+This will:
+
+- clear the `ServerCsrfTokenRepository`, `ServerSecurityContextRepository`, and
+- redirect back to the login page
+
+Often, you will want to also invalidate the session on logout.
+To achieve this, you can add the `WebSessionServerLogoutHandler` to your logout configuration, like so:
+
+[source,java]
+----
+@Bean
+SecurityWebFilterChain http(ServerHttpSecurity http) throws Exception {
+    DelegatingServerLogoutHandler logoutHandler = new DelegatingServerLogoutHandler(
+            new WebSessionServerLogoutHandler(), new SecurityContextServerLogoutHandler()
+    );
+
+    http
+        .authorizeExchange((exchange) -> exchange.anyExchange().authenticated())
+        .logout((logout) -> logout.logoutHandler(logoutHandler));
+
+    return http.build();
+}
+----
@@ -0,0 +1,237 @@
+[[jc-erms]]
+= EnableReactiveMethodSecurity
+
+Spring Security supports method security using https://projectreactor.io/docs/core/release/reference/#context[Reactor's Context] which is setup using `ReactiveSecurityContextHolder`.
+For example, this demonstrates how to retrieve the currently logged in user's message.
+
+[NOTE]
+====
+For this to work the return type of the method must be a `org.reactivestreams.Publisher` (i.e. `Mono`/`Flux`) or the function must be a Kotlin coroutine function.
+This is necessary to integrate with Reactor's `Context`.
+====
+
+====
+.Java
+[source,java,role="primary"]
+----
+Authentication authentication = new TestingAuthenticationToken("user", "password", "ROLE_USER");
+
+Mono<String> messageByUsername = ReactiveSecurityContextHolder.getContext()
+	.map(SecurityContext::getAuthentication)
+	.map(Authentication::getName)
+	.flatMap(this::findMessageByUsername)
+	// In a WebFlux application the `subscriberContext` is automatically setup using `ReactorContextWebFilter`
+	.subscriberContext(ReactiveSecurityContextHolder.withAuthentication(authentication));
+
+StepVerifier.create(messageByUsername)
+	.expectNext("Hi user")
+	.verifyComplete();
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+val authentication: Authentication = TestingAuthenticationToken("user", "password", "ROLE_USER")
+
+val messageByUsername: Mono<String> = ReactiveSecurityContextHolder.getContext()
+	.map(SecurityContext::getAuthentication)
+	.map(Authentication::getName)
+	.flatMap(this::findMessageByUsername) // In a WebFlux application the `subscriberContext` is automatically setup using `ReactorContextWebFilter`
+	.subscriberContext(ReactiveSecurityContextHolder.withAuthentication(authentication))
+
+StepVerifier.create(messageByUsername)
+	.expectNext("Hi user")
+	.verifyComplete()
+----
+====
+
+with `this::findMessageByUsername` defined as:
+
+====
+.Java
+[source,java,role="primary"]
+----
+Mono<String> findMessageByUsername(String username) {
+	return Mono.just("Hi " + username);
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+fun findMessageByUsername(username: String): Mono<String> {
+	return Mono.just("Hi $username")
+}
+----
+====
+
+Below is a minimal method security configuration when using method security in reactive applications.
+
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableReactiveMethodSecurity
+public class SecurityConfig {
+	@Bean
+	public MapReactiveUserDetailsService userDetailsService() {
+		User.UserBuilder userBuilder = User.withDefaultPasswordEncoder();
+		UserDetails rob = userBuilder.username("rob")
+			.password("rob")
+			.roles("USER")
+			.build();
+		UserDetails admin = userBuilder.username("admin")
+			.password("admin")
+			.roles("USER","ADMIN")
+			.build();
+		return new MapReactiveUserDetailsService(rob, admin);
+	}
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableReactiveMethodSecurity
+class SecurityConfig {
+	@Bean
+	fun userDetailsService(): MapReactiveUserDetailsService {
+		val userBuilder: User.UserBuilder = User.withDefaultPasswordEncoder()
+		val rob = userBuilder.username("rob")
+			.password("rob")
+			.roles("USER")
+			.build()
+		val admin = userBuilder.username("admin")
+			.password("admin")
+			.roles("USER", "ADMIN")
+			.build()
+		return MapReactiveUserDetailsService(rob, admin)
+	}
+}
+----
+====
+
+Consider the following class:
+
+====
+.Java
+[source,java,role="primary"]
+----
+@Component
+public class HelloWorldMessageService {
+	@PreAuthorize("hasRole('ADMIN')")
+	public Mono<String> findMessage() {
+		return Mono.just("Hello World!");
+	}
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Component
+class HelloWorldMessageService {
+	@PreAuthorize("hasRole('ADMIN')")
+	fun findMessage(): Mono<String> {
+		return Mono.just("Hello World!")
+	}
+}
+----
+====
+
+Or, the following class using Kotlin coroutines:
+
+====
+.Kotlin
+[source,kotlin,role="primary"]
+----
+@Component
+class HelloWorldMessageService {
+    @PreAuthorize("hasRole('ADMIN')")
+    suspend fun findMessage(): String {
+        delay(10)
+        return "Hello World!"
+    }
+}
+----
+====
+
+
+Combined with our configuration above, `@PreAuthorize("hasRole('ADMIN')")` will ensure that `findByMessage` is only invoked by a user with the role `ADMIN`.
+It is important to note that any of the expressions in standard method security work for `@EnableReactiveMethodSecurity`.
+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.
+
+====
+.Java
+[source,java,role="primary"]
+----
+@EnableWebFluxSecurity
+@EnableReactiveMethodSecurity
+public class SecurityConfig {
+
+	@Bean
+	SecurityWebFilterChain springWebFilterChain(ServerHttpSecurity http) throws Exception {
+		return http
+			// Demonstrate that method security works
+			// Best practice to use both for defense in depth
+			.authorizeExchange(exchanges -> exchanges
+				.anyExchange().permitAll()
+			)
+			.httpBasic(withDefaults())
+			.build();
+	}
+
+	@Bean
+	MapReactiveUserDetailsService userDetailsService() {
+		User.UserBuilder userBuilder = User.withDefaultPasswordEncoder();
+		UserDetails rob = userBuilder.username("rob")
+			.password("rob")
+			.roles("USER")
+			.build();
+		UserDetails admin = userBuilder.username("admin")
+			.password("admin")
+			.roles("USER","ADMIN")
+			.build();
+		return new MapReactiveUserDetailsService(rob, admin);
+	}
+}
+
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@EnableWebFluxSecurity
+@EnableReactiveMethodSecurity
+class SecurityConfig {
+	@Bean
+	open fun springWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+		return http {
+			authorizeExchange {
+				authorize(anyExchange, permitAll)
+			}
+			httpBasic { }
+		}
+	}
+
+	@Bean
+	fun userDetailsService(): MapReactiveUserDetailsService {
+		val userBuilder: User.UserBuilder = User.withDefaultPasswordEncoder()
+		val rob = userBuilder.username("rob")
+			.password("rob")
+			.roles("USER")
+			.build()
+		val admin = userBuilder.username("admin")
+			.password("admin")
+			.roles("USER", "ADMIN")
+			.build()
+		return MapReactiveUserDetailsService(rob, admin)
+	}
+}
+----
+====
+
+You can find a complete sample in {gh-samples-url}/reactive/webflux/java/method[hellowebflux-method]
@@ -0,0 +1,52 @@
+[[webflux-oauth2-client]]
+= OAuth2 Client
+
+Spring Security's OAuth Support allows obtaining an access token without authenticating.
+A basic configuration with Spring Boot can be seen below:
+
+[source,yml]
+----
+spring:
+  security:
+    oauth2:
+      client:
+        registration:
+          github:
+            client-id: replace-with-client-id
+            client-secret: replace-with-client-secret
+            scope: read:user,public_repo
+----
+
+You will need to replace the `client-id` and `client-secret` with values registered with GitHub.
+
+The next step is to instruct Spring Security that you wish to act as an OAuth2 Client so that you can obtain an access token.
+
+.OAuth2 Client
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain configure(ServerHttpSecurity http) throws Exception {
+	http
+		// ...
+		.oauth2Client(withDefaults());
+	return http.build();
+}
+----
+
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        // ...
+        oauth2Client { }
+    }
+}
+----
+====
+
+You can now leverage Spring Security's <<webclient>> or <<webflux-roac,@RegisteredOAuth2AuthorizedClient>> support to obtain and use the access token.
@@ -0,0 +1,10 @@
+[[webflux-oauth2]]
+= OAuth2 WebFlux
+
+Spring Security provides OAuth2 and WebFlux integration for reactive applications.
+
+include::login.adoc[leveloffset=+1]
+
+include::access-token.adoc[leveloffset=+1]
+
+include::resource-server.adoc[leveloffset=+1]
@@ -0,0 +1,245 @@
+[[webflux-oauth2-login]]
+= OAuth 2.0 Login
+
+The OAuth 2.0 Login feature provides an application with the capability to have users log in to the application by using their existing account at an OAuth 2.0 Provider (e.g.
+GitHub) or OpenID Connect 1.0 Provider (such as Google).
+OAuth 2.0 Login implements the use cases: "Login with Google" or "Login with GitHub".
+
+NOTE: OAuth 2.0 Login is implemented by using the *Authorization Code Grant*, as specified in the https://tools.ietf.org/html/rfc6749#section-4.1[OAuth 2.0 Authorization Framework] and https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[OpenID Connect Core 1.0].
+
+[[webflux-oauth2-login-sample]]
+== Spring Boot 2.0 Sample
+
+Spring Boot 2.0 brings full auto-configuration capabilities for OAuth 2.0 Login.
+
+This section shows how to configure the {gh-samples-url}/reactive/webflux/java/oauth2/login[*OAuth 2.0 Login WebFlux sample*] using _Google_ as the _Authentication Provider_ and covers the following topics:
+
+* <<webflux-oauth2-login-sample-setup,Initial setup>>
+* <<webflux-oauth2-login-sample-redirect,Setting the redirect URI>>
+* <<webflux-oauth2-login-sample-config,Configure `application.yml`>>
+* <<webflux-oauth2-login-sample-start,Boot up the application>>
+
+
+[[webflux-oauth2-login-sample-setup]]
+=== Initial setup
+
+To use Google's OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.
+
+NOTE: https://developers.google.com/identity/protocols/OpenIDConnect[Google's OAuth 2.0 implementation] for authentication conforms to the  https://openid.net/connect/[OpenID Connect 1.0] specification and is https://openid.net/certification/[OpenID Certified].
+
+Follow the instructions on the https://developers.google.com/identity/protocols/OpenIDConnect[OpenID Connect] page, starting in the section, "Setting up OAuth 2.0".
+
+After completing the "Obtain OAuth 2.0 credentials" instructions, you should have a new OAuth Client with credentials consisting of a Client ID and a Client Secret.
+
+[[webflux-oauth2-login-sample-redirect]]
+=== Setting the redirect URI
+
+The redirect URI is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with Google and have granted access to the OAuth Client _(<<webflux-oauth2-login-sample-setup,created in the previous step>>)_ on the Consent page.
+
+In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`.
+
+TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`.
+The *_registrationId_* is a unique identifier for the <<oauth2Client-client-registration,ClientRegistration>>.
+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`.
+
+[[webflux-oauth2-login-sample-config]]
+=== Configure `application.yml`
+
+Now that you have a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_.
+To do so:
+
+. Go to `application.yml` and set the following configuration:
+
+[source,yaml]
+----
+spring:
+  security:
+    oauth2:
+      client:
+        registration:	<1>
+          google:	<2>
+            client-id: google-client-id
+            client-secret: google-client-secret
+----
+
+.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.
+====
+
+. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
+
+
+[[webflux-oauth2-login-sample-start]]
+=== Boot up the application
+
+Launch the Spring Boot 2.0 sample and go to `http://localhost:8080`.
+You are then redirected to the default _auto-generated_ login page, which displays a link for Google.
+
+Click on the Google link, and you are then redirected to Google for authentication.
+
+After authenticating with your Google account credentials, the next page presented to you is the Consent screen.
+The Consent screen asks you to either allow or deny access to the OAuth Client you created earlier.
+Click *Allow* to authorize the OAuth Client to access your email address and basic profile information.
+
+At this point, the OAuth Client retrieves your email address and basic profile information from the https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] and establishes an authenticated session.
+
+[[webflux-oauth2-login-openid-provider-configuration]]
+== Using OpenID Provider Configuration
+
+For well known providers, Spring Security provides the necessary defaults for the OAuth Authorization Provider's configuration.
+If you are working with your own Authorization Provider that supports https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[OpenID Provider Configuration] or https://tools.ietf.org/html/rfc8414#section-3[Authorization Server Metadata], the https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse[OpenID Provider Configuration Response]'s `issuer-uri` can be used to configure the application.
+
+[source,yml]
+----
+spring:
+  security:
+    oauth2:
+      client:
+        provider:
+          keycloak:
+            issuer-uri: https://idp.example.com/auth/realms/demo
+        registration:
+          keycloak:
+            client-id: spring-security
+            client-secret: 6cea952f-10d0-4d00-ac79-cc865820dc2c
+----
+
+The `issuer-uri` instructs Spring Security to query in series the endpoints `https://idp.example.com/auth/realms/demo/.well-known/openid-configuration`, `https://idp.example.com/.well-known/openid-configuration/auth/realms/demo`, or `https://idp.example.com/.well-known/oauth-authorization-server/auth/realms/demo` to discover the configuration.
+
+[NOTE]
+Spring Security will query the endpoints one at a time, stopping at the first that gives a 200 response.
+
+The `client-id` and `client-secret` are linked to the provider because `keycloak` is used for both the provider and the registration.
+
+
+[[webflux-oauth2-login-explicit]]
+== Explicit OAuth2 Login Configuration
+
+A minimal OAuth2 Login configuration is shown below:
+
+.Minimal OAuth2 Login
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+ReactiveClientRegistrationRepository clientRegistrations() {
+	ClientRegistration clientRegistration = ClientRegistrations
+			.fromIssuerLocation("https://idp.example.com/auth/realms/demo")
+			.clientId("spring-security")
+			.clientSecret("6cea952f-10d0-4d00-ac79-cc865820dc2c")
+			.build();
+	return new InMemoryReactiveClientRegistrationRepository(clientRegistration);
+}
+
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.oauth2Login(withDefaults());
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun clientRegistrations(): ReactiveClientRegistrationRepository {
+    val clientRegistration: ClientRegistration = ClientRegistrations
+            .fromIssuerLocation("https://idp.example.com/auth/realms/demo")
+            .clientId("spring-security")
+            .clientSecret("6cea952f-10d0-4d00-ac79-cc865820dc2c")
+            .build()
+    return InMemoryReactiveClientRegistrationRepository(clientRegistration)
+}
+
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        oauth2Login { }
+    }
+}
+----
+====
+
+Additional configuration options can be seen below:
+
+.Advanced OAuth2 Login
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.oauth2Login(oauth2 -> oauth2
+			.authenticationConverter(converter)
+			.authenticationManager(manager)
+			.authorizedClientRepository(authorizedClients)
+			.clientRegistrationRepository(clientRegistrations)
+		);
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        oauth2Login {
+            authenticationConverter = converter
+            authenticationManager = manager
+            authorizedClientRepository = authorizedClients
+            clientRegistrationRepository = clientRegistration
+        }
+    }
+}
+----
+====
+
+You may register a `GrantedAuthoritiesMapper` `@Bean` to have it automatically applied to the default configuration, as shown in the following example:
+
+.GrantedAuthoritiesMapper Bean
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+public GrantedAuthoritiesMapper userAuthoritiesMapper() {
+    ...
+}
+
+@Bean
+SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
+	http
+		// ...
+		.oauth2Login(withDefaults());
+	return http.build();
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun userAuthoritiesMapper(): GrantedAuthoritiesMapper {
+   // ...
+}
+
+@Bean
+fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
+    return http {
+        oauth2Login { }
+    }
+}
+----
+====
--- a/Show More
+++ b/Show More