Password Policy
Enforces password security constraints and expiration policies through a flexible plugin-based architecture.
password_policy
Install
composer require 'drupal/password_policy:^4.0'
composer require 'drupal/password_policy:8.x-3.2'
Overview
Password Policy is a comprehensive security module that allows site administrators to define and enforce password requirements through configurable policies. The module uses a plugin-based architecture where password constraints (such as minimum length, required character types, and blacklisted phrases) are provided by optional submodules.
Policies are role-based, meaning different user roles can have different password requirements. The module also provides password expiration functionality, automatically tracking when passwords need to be reset and forcing users to update expired passwords before they can continue using the site.
Key capabilities include real-time validation feedback during password entry, email notifications for expiring and expired passwords, support for preventing password reuse through history tracking, and integration with the Masquerade module to avoid forced password resets during masquerading sessions. Externally authenticated users (via the externalauth module) are automatically excluded from password validation and expiration checks.
Features
- Create and manage multiple password policies with different constraints and expiration settings
- Role-based policy assignment - apply different policies to different user roles
- Plugin-based constraint system allowing extensible password requirements
- Real-time AJAX password validation with visual pass/fail status table during password entry
- Automatic password expiration with configurable expiration period in days
- Force password reset functionality - administrators can force password reset for specific roles
- Email notifications for password expiration and pending expiration warnings
- Cron-based automatic detection and marking of expired passwords
- Graceful handling of one-time login links to allow users to reset passwords after expiration
- Support for Masquerade module - skips forced password reset during masquerading
- Exclusion of externally authenticated users from password policies
- Migration support from Drupal 7 password_policy module
Use Cases
Enterprise Security Compliance
Organizations requiring compliance with security standards (PCI-DSS, HIPAA, SOC2) can use Password Policy to enforce strong password requirements. Create a policy with minimum length of 12 characters, require 3+ character types, enable password history to prevent reuse of the last 12 passwords, and set password expiration to 90 days with email warnings at 14 and 7 days before expiration.
Tiered Password Requirements
Sites with different user types can create multiple policies. For example, create a strict policy for administrators requiring 16+ characters, all 4 character types, and 30-day expiration, while applying a lighter policy to regular authenticated users with 8+ characters and no expiration.
Emergency Security Response
After a security incident or data breach, administrators can use the Force Password Reset feature to immediately expire all passwords for affected user roles, forcing everyone to create new passwords on their next login.
Prevent Common Password Attacks
Use the Password Blacklist submodule to prevent users from choosing commonly compromised passwords. Import lists of known breached passwords and enable substring matching to also block variations.
Prevent Rapid Password Cycling
Enable both Password History and Password Delay constraints together. History prevents reuse of recent passwords while Delay prevents users from rapidly changing passwords multiple times to work around the history check.
Tips
- Enable the 'Show policy table' option on policies to give users immediate visual feedback as they type their password, showing which constraints pass or fail in real-time.
- Use comma-separated values in the 'Send pending email days before' field to send multiple reminder emails (e.g., '7,3,1' sends reminders 7, 3, and 1 days before expiration).
- The password expiration check only runs on GET requests and excludes AJAX requests, JSON API calls, and several system routes to avoid interfering with normal site operation.
- When testing password policies, remember that the validation runs against the roles selected in the form, not just the user's current roles. Adding a role with a policy will trigger validation.
- Password history hashes are stored in a separate database table (password_policy_history) and can grow large on sites with many users. Consider periodic cleanup for very old entries.
Technical Details
Admin Pages 4
/admin/config/security/password-policy
Lists all configured password policies. From this page, administrators can view, edit, and delete existing policies, as well as create new ones. Each policy shows its machine name and provides operations links for editing and deletion.
/admin/config/security/password-policy/add
Form for creating a new password policy. Define the policy name, expiration settings, and email notification preferences.
/admin/config/security/password-policy/{password_policy}
Form for editing an existing password policy. Modify policy settings, add or remove constraints, and configure which roles the policy applies to.
/admin/config/security/password-policy/reset
Administrative form to immediately force password expiration for users with specific roles. Useful for security incidents or when enforcing new password policies.
Permissions 2
Hooks 2
hook_password_policy_show_policy_alter
Allows modules to alter whether the password policy status table is shown on a form.
hook_password_policy_constraints_table_rows_alter
Allows modules to alter the constraint table rows displayed during password validation.
Troubleshooting 5
The module adds fields to user entities on installation. If cron has run before users have logged in, their passwords may be marked as expired. Either run cron again after users log in, or use the Force Password Reset feature to reset the expiration flag, or users can use the one-time login link.
Ensure you have enabled at least one constraint submodule (e.g., password_policy_length). The base module only provides the policy framework; constraints come from submodules.
Verify the externalauth module is properly installed and configured. Password Policy automatically detects externally authenticated users and excludes them from validation.
Check that the 'Send email upon password expiring' checkbox is enabled on the policy. Also verify that your site's mail system is properly configured and that cron is running regularly.
Reduce the cron_threshold setting in password_policy.settings.yml. The default is 250 users per policy per cron run. Lower this value for sites with memory constraints.
Security Notes 5
- Password Policy stores password hashes in the password_policy_history table when the History constraint is enabled. These are properly hashed using Drupal's password service, but the table should be protected like any sensitive data.
- The module excludes externally authenticated users from validation, trusting that the external authentication provider enforces its own password policies.
- Administrators with the 'manage password reset' permission can modify password expiration dates for any user, effectively bypassing expiration requirements.
- The password blacklist is stored in configuration, which may be exported to version control. Avoid storing sensitive information in the blacklist that shouldn't be in your repository.
- Email notifications about password expiration include links to the login page but do not include one-time login links for security reasons.