Using the password validator¶
-
class
pwned_passwords_django.validators.
PwnedPasswordsValidator
¶ Django’s auth system (located in
django.contrib.auth
) includes a configurable password-validation framework with several built-in validators; pwned-passwords-django provides an additional validator which checks the Pwned Passwords database. To enable it, set yourAUTH_PASSWORD_VALIDATORS
setting to includepwned_passwords_django.validators.PwnedPasswordsValidator
, like so:AUTH_PASSWORD_VALIDATORS = [ { 'NAME': 'pwned_passwords_django.validators.PwnedPasswordsValidator', }, ]
This will cause most high-level password-setting operations to check the Pwned Passwords database, and reject any password found there. Specifically, password validators are applied:
- Whenever a user changes or resets their password with Django’s built-in auth views.
- Whenever a new user is created via Django’s built-in
UserCreationForm
. - Whenever the
createsuperuser
orchangepassword
management commands are used. - Whenever an instance of the built-in
User
model is saved after the instance’sset_password()
method has been called.
Keep in mind that validation is not run when code sets or changes a user’s password in other ways. If you manipulate user passwords through means other than the high-level APIs listed above, you’ll need to manually check passwords.
Warning
API failures
pwned-passwords-django needs to communicate with the Pwned Passwords API in order to check passwords. If Pwned Passwords is down or timing out (the default connection timeout is 1 second), this validator will fall back to using Django’s CommonPasswordValidator, which uses a smaller, locally-stored list of common passwords. Whenever this happens, a message of level
logging.WARNING
will appear in your logs, indicating what type of failure was encountered in talking to the Pwned Passwords API.
Customizing the validator’s messages¶
To change the error or help messages shown to the user, you can pass
OPTIONS
when adding the validator to your settings:
AUTH_PASSWORD_VALIDATORS = [
{
'NAME': 'pwned_passwords_django.validators.PwnedPasswordsValidator',
'OPTIONS': {
'error_message': 'That password was pwned',
'help_message': 'Your password can\'t be a commonly used password.',
}
},
]
The number of times the password has appeared in a breach can also be included in the error message, including a plural form:
AUTH_PASSWORD_VALIDATORS = [
{
'NAME': 'pwned_passwords_django.validators.PwnedPasswordsValidator',
'OPTIONS': {
'error_message': (
'Pwned %(amount)d time',
'Pwned %(amount)d times',
)
}
},
]