bbs-lab/wordpress-password-policy

WordPress plugin: configurable password complexity and mandatory rotation for privileged accounts.

1.1.0 2026-08-06 10:18 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• Big Boss Studio

• security
• wordpress
• password
• Policy
• rotation
• bbs-lab

Published on Packagist.org on 2026-08-06 10:18 UTC

README

Enforce configurable password complexity and mandatory password rotation for WordPress privileged accounts (administrators by default). Light, self-contained, and ready for compliance use-cases such as CNSR: 15+ characters, 3 of 4 character classes, 90-day rotation.

Built by Big Boss Studio.

Features

• Forces strong passwords: minimum length + N of 4 character classes (upper / lower / digit / special)
• Blocks WordPress “Confirm use of weak password” bypass on create / edit for targeted roles
• Mandatory rotation every N days, with admin redirect until the password is renewed
• Pre-expiry warning notice in wp-admin
• Role-scoped enforcement (default: administrator only) and optional user-ID exclusions
• Validates profile, user-new, user-edit, password reset, and REST user create/update
• English source strings + French translations (fr_FR)
• Settings UI under Settings → Password Policy (manage_options)
• Clean uninstall (options + user meta, filterable)

Requirements

• PHP >= 7.4
• WordPress >= 6.0

Installation

From GitHub

cd wp-content/plugins
git clone https://github.com/BBS-Lab/wordpress-password-policy.git bbs-password-policy

Or download a release ZIP, then Plugins → Add New → Upload Plugin.

Activate

1. Activate BBS Password Policy
2. Open Settings → Password Policy
3. Adjust roles / complexity / rotation if needed (CNSR defaults are already set)

On activation, existing users in target roles receive a fresh “last changed” timestamp so they are not locked out immediately.

Quick start (defaults)

Setting	Default
Enabled	true
Target roles	administrator
Minimum length	15
Character classes	upper, lower, digit, special
Required classes	3 of 4
Rotation	enabled
Rotation period	90 days
Warning window	14 days
Force change in admin	true

Length and complexity are independent checks: a password must satisfy both the minimum length and the N-of-4 rule.

On Add New User, the form defaults to subscriber. The policy only applies when the selected role is in Target roles (e.g. Administrator).

Configuration

All options live in the bbs_pp_settings option and are edited in Settings → Password Policy.

Key	Default	Description
enabled	true	Master switch
target_roles	['administrator']	Roles that must comply
min_length	15	Minimum password length (sanitized ≥ 8)
require_uppercase	true	Count uppercase toward complexity
require_lowercase	true	Count lowercase toward complexity
require_digit	true	Count digits toward complexity
require_special	true	Count special characters toward complexity
min_character_classes	3	How many enabled classes are required (1–4)
rotation_enabled	true	Require periodic renewal
rotation_days	90	Password lifetime in days
warning_days	14	Admin notice window before expiry
force_change_on_login	true	Redirect expired users to their profile in wp-admin
exclude_user_ids	[]	User IDs that bypass the policy

Usage

Complexity

When a targeted user sets or resets a password (profile, user-new, user-edit, reset form, REST), the plugin validates length and character classes. Invalid passwords are rejected server-side; the admin UI also keeps Add / Update disabled until the policy passes and hides the weak-password confirmation checkbox.

Rotation

Each successful password change stores a Unix timestamp in user meta bbs_pp_password_last_changed.

When the password is older than rotation_days:

1. The user can still sign in (if force-change is on)
2. wp-admin requests redirect to Profile
3. An error notice asks for a new password
4. After a successful change, the timestamp resets and access is restored

Profile panel

Targeted users (and admins editing them) see policy summary, last change date, and days remaining on the profile screen.

Developer API

Filters

add_filter( 'bbs_pp_validate_password', function ( WP_Error $errors, string $password ) {
    return $errors;
}, 10, 2 );

// Keep user meta on uninstall (default: purge).
add_filter( 'bbs_pp_uninstall_purge_user_meta', '__return_false' );

Helpers

$plugin = bbs_password_policy();

$plugin->settings()->applies_to_user( $user );
$plugin->validator()->validate( 'SomePassword123!' );
$plugin->rotation()->is_expired( $user );
$plugin->rotation()->days_until_expiry( $user );

Storage

Key	Type	Purpose
bbs_pp_settings	option	Plugin settings array
bbs_pp_password_last_changed	user meta	Last password change (Unix timestamp)
bbs_pp_must_change_password	user meta	Force-renewal flag

Directory structure

bbs-password-policy/
├── bbs-password-policy.php
├── uninstall.php
├── composer.json
├── README.md
├── CHANGELOG.md
├── LICENSE.md
├── SECURITY.md
├── readme.txt
├── includes/
├── admin/
│   ├── class-admin-page.php
│   ├── views/
│   └── assets/
│       ├── css/
│       └── js/
└── languages/

Security

Passwords are never stored by this plugin — WordPress hashing only. Settings require manage_options. If you discover a security vulnerability, please email [e-mail] instead of using the public issue tracker.

See SECURITY for details.

Changelog

Please see CHANGELOG for what has changed recently.

Credits

• Big Boss Studio

License

GPL-2.0-or-later. Please see License File for more information.