website/docs: document the Password Uniqueness Policy #11000
Conversation
✅ Deploy Preview for authentik-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Deploy Preview for authentik-storybook ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
tanberry
changed the title
website/docs/policies/index.md
Outdated
| @@ -46,6 +46,21 @@ 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 | |||
|
|
|||
| Prevents users from reusing old passwords when changing their own password. The policy offers an option to limit the number many previous passwords to consider during evaluation. | |||
There was a problem hiding this comment.
I think this reads awkwardly. Suggestion: "This policy allows admins to specify how many previous password hashes should be kept to prevent re-use. By default, the password history depth is zero, permitting users to re-use any previous password."
There was a problem hiding this comment.
(Correct me if the default is wrong. I took that number from https://github.com/goauthentik/authentik/pull/10631/files#diff-cbb45e894de9c1957d2289a8301eaecdcef3ecd580a35d4fefba93f50441b398R30)
There was a problem hiding this comment.
I like that rephrasing a lot more and I'll get that changed!
The UI displays 1 as the default, which I can change to be 0 (I figured if you're setting up a the policy you want it to actually do something 😅 ). Is there a preference?
There was a problem hiding this comment.
Agree about defaulting to 1, from a usability perspective. Also zeros can be unnerving, lol.
website/docs/policies/index.md
Outdated
| When this policy is bound and enabled to at least one [User write stage](../flow/stages/user_write.md): | ||
|
|
||
| 1. authentik compares the hashes of the new password and the old password for a match. The policy check fails and exits if the hashes match. | ||
| 2. authentik copies the hashed form of the user's old password for future comparison |
There was a problem hiding this comment.
Suggestion: "When the policy succeeds, the user's current password hash is copied into the password history. Passwords hashes are removed, oldest first, from the user's password history if it has more entries than the current depth setting."
There was a problem hiding this comment.
👍 Much cleaner
We could note if more than one Password Uniqueness Policy is bound & active anywhere in authentik, then the system maintains a history depth equal to the greatest configured depth of all Password Uniqueness Policies.
e.g. I create 2 copies of a Password Uniqueness Policy. I configure one policy with a depth of 1, and another with a depth of 10. authentik will maintain 10 old password hashes.
It's a minor detail and probably only important for someone wanting to fully understand how many old hashes are stored. I'll leave it up to you & @tanberry whether we include that.
There was a problem hiding this comment.
Ah, I remember you telling me about this. Yes I think we should indeed include this info in the docs. I predict it will avoid a few GitHub Issues in the future, where people ask what-the-heck.
I think that will also help people understand that there can be multiple instances on a policy.
There was a problem hiding this comment.
Thanks @verkaufer for the docs! I agree with Ken's rewordings ( I almost always like them more than my own), and then I caught one typo, but looks great otherwise!
I'm pre-approving just so that I am not the blocker when you/we are ready to merge this.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #11000 +/- ##
==========================================
+ Coverage 92.69% 92.76% +0.07%
==========================================
Files 736 736
Lines 36360 36360
==========================================
+ Hits 33703 33729 +26
+ Misses 2657 2631 -26
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Relates to #10631
Details
Introduces public documentation for the Unique Password Policy feature added by #10631
Documentation changes were move into a separate PR to keep feedback conversations focused on the specific changes.
👉 This PR should not be merged before #10631.
Checklist
ak test authentik/)make lint-fix)If an API change has been made
make gen-build)If changes to the frontend have been made
make web)If applicable
make website)