website/docs: Password Uniqueness Policy (#13686)

* First draft docs for policies/unique_password

* simplify documentation

* fix styling

* Add clarification about when this policy takes effect

* change wording in how it works

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Marcelo Elizeche Landó <marce@melizeche.com>

* Take the user by the hand and tell them where to go

* Improve wording in Configuration options

* add suggestion from PR

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Marcelo Elizeche Landó <marce@melizeche.com>

* Update website/docs/customize/policies/unique_password.md

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Apply suggestions from code review

Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Signed-off-by: Marcelo Elizeche Landó <marce@melizeche.com>

* fix linting and wording

* Add instructions for binding

* Remove conf options section, add to sidebar

* Update website/docs/customize/policies/unique_password.md

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

---------

Signed-off-by: Marcelo Elizeche Landó <marce@melizeche.com>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Dominic R <dominic@sdko.org>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>

website/docs/customize/policies/index.md

@@ -66,6 +66,10 @@ Starting with authentik 2022.11.0, the following checks can also be done with th
 - Check the password hash against the database of [Have I Been Pwned](https://haveibeenpwned.com/). Only the first 5 characters of the hashed password are transmitted, the rest is compared in authentik
 - Check the password against the password complexity checker [zxcvbn](https://github.com/dropbox/zxcvbn), which detects weak password on various metrics.
 
+### Password Uniqueness Policy
+
+This policy prevents users from reusing their previous passwords when setting a new password. For detailed information, see [Password Uniqueness Policy](./unique_password.md).
+
 ### Reputation Policy
 
 authentik keeps track of failed login attempts by source IP and attempted username. These values are saved as scores. Each failed login decreases the score for the client IP as well as the targeted username by 1 (one).

website/docs/customize/policies/unique_password.md

@@ -0,0 +1,46 @@
+---
+title: Password Uniqueness Policy
+sidebar_label: Password Uniqueness Policy
+support_level: authentik
+tags:
+    - policy
+    - password
+    - security
+    - enterprise
+authentik_version: "2025.4.0"
+authentik_enterprise: true
+---
+
+The Password Uniqueness policy prevents users from reusing their previous passwords when setting a new password. To use this feature, you will need to create a Password Uniqueness policy, using the instructions below.
+
+## How it works
+
+This policy maintains a record of previously used passwords for each user. When a new password is created, it is compared against this historical log. If a match is found with any previous password, the policy is not met, and the user is required to choose a different password.
+
+The password history is maintained automatically when this policy is in use. Old password hashes are stored securely in authentik's database.
+
+:::info
+This policy takes effect after the first password change following policy activation. Before that first change, there's no password history data to compare against.
+:::
+
+## Integration with other policies
+
+For comprehensive password security, consider using this policy alongside:
+
+- [Password Policy](./index.md#password-policy) - To enforce password complexity rules
+- [Password-Expiry Policy](./index.md#password-expiry-policy) - To enforce regular password rotation
+
+## Implement a Password Uniqueness policy
+
+To implement a policy that prevents users from reusing their previous passwords, follow these steps:
+
+1. In the Admin interface, navigate to **Customization** > **Policies**.
+2. Click **Create** to define a new Password Uniqueness Policy.
+    - **Name**: provide a descriptive name for the policy.
+    - **Password field**: enter the name of the input field to check for the new password. By default, if no custom flows are used, the field name is `password`. This field name must match the field name used in your Prompt stage.
+    - **Number of previous passwords to check**: enter the number of past passwords that you want to set as the number of previous passwords that are checked and stored for each user, with a default of 1. For instance, if set to 3, users will not be able to reuse any of their last 3 passwords.
+3. Bind the policy to your **password prompt stage**: For example, if you're using the `default-password-change` flow, edit the `default-password-change-prompt` stage and add the policy in the **Validation Policies** section.
+
+:::info
+Password history records are stored securely and cannot be used to reconstruct original passwords.
+:::

website/sidebars.js

@@ -396,6 +396,7 @@ export default {
                                 "customize/policies/expression/managing_flow_context_keys",
                             ],
                         },
+                        "customize/policies/unique_password",
                     ],
                 },
                 {