Document PasswordManagementConfigurer

Issue gh-8657

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

@@ -489,3 +489,71 @@ fun passwordEncoder(): PasswordEncoder {
 ====
 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`.