Implement password policy with hook by JolienTrog · Pull Request #5419 · Icinga/icingaweb2

JolienTrog · 2025-08-26T09:22:14Z

Add password policy support for database-backed user accounts. Administrators can select a policy under Configuration > Application > General. It is then enforced on every form that sets or resets a password. The account change-password form, the admin user create and edit form, and the setup wizard admin account page.

Two built-in policies ship with this change. None (the default) accepts any password without validation. Common enforces a baseline: minimum 12 characters, at least one digit, one special character, one lowercase letter, and one uppercase letter. The active policy's requirements are shown as an info callout below the password field so users know what to enter before submitting. A configuration error falls back to an error callout rather than breaking the form.

Third-party modules can provide additional policies by implementing PasswordPolicyHook. The new section in doc/05-Authentication.md covers the configuration UI and a worked example of a custom policy module.

resolve #4401

Al2Klimov

During setup, the wizard prompts me for a username and password "to configure your first administrative account". This should enforce the chosen password policy.

Al2Klimov · 2026-02-16T15:11:21Z

+    public static function register(): void
+    {
+        Hook::register(self::HOOK_NAME, static::class, static::class);
+    }


Wait until Introduce HookEssentials #5474 is merged

Use that trait

lippserd · 2026-03-20T09:15:39Z

+
+class PasswordPolicy extends PasswordPolicyHook
+{
+    use Translation;


You use the Translation trait only but never call $this->translate() on any of the strings.

lippserd · 2026-03-20T09:51:47Z

+        return $passwordPolicy;
+    }
+
+    public static function addPasswordPolicyDescription(Form $form, PasswordPolicy $passwordPolicy): void


PHPDoc missing.

TheSyscall · 2026-03-31T13:11:35Z

+    const DEFAULT_PASSWORD_POLICY = AnyPasswordPolicy::class;
+
+    /** @var string INI configuration section for password policy */
+    const CONFIG_SECTION = 'global';


Consider moving password policy to the security section.

Yeah, you also made a separate permission for the CSP stuff, didn't you?

I was mostly talking about the [security] section of the config.ini file here.

But yes, I added 'config/security' in #5477 for all security related configuration.
The only thing that is currently in this section is CSP, but it seems password policy would fit well there.

TheSyscall · 2026-03-31T13:15:24Z

+ *
+ * This form is not used directly but as subform for the {@link GeneralConfigForm}.
+ */
+class PasswordPolicyConfigForm extends Form


There already was some discussion with @lippserd to move this form into a new Security section in IW2.
We should consider converting this form into an ipl-web based form instead during this process.

jrauh01 · 2026-06-30T08:09:45Z

Since we now have the new callouts (Icinga/ipl-web#358) consider using them in the PasswordPolicyHelper instead of the custom callout.

TheSyscall · 2026-07-03T05:46:46Z

Changed class loading to ask the hook by a canonical name instead of storing the class path and instantiating a class from that.

Since we now have the new callouts (Icinga/ipl-web#358) consider using them in the PasswordPolicyHelper instead of the custom callout.

Used callouts

`PasswordPolicy` defines the contract every implementation must fulfill. A display name, an optional description shown to users, and a `validate()` method that returns a list of violation strings. `PasswordPolicyHook` implements the interface and adds `loadConfigured()`, a static factory that reads the selected policy name from application configuration and returns the matching hook implementation, falling back to `AnyPasswordPolicy` when none is configured. `PasswordPolicyValidator` wraps a `PasswordPolicy` in a Zend form validator so it can be attached to a password element without additional glue. `PasswordPolicyHelper` handles form-level plumbing: attaching the validator, rendering an info callout with the policy description, and falling back to an error callout when loading the configured policy fails. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

`AnyPasswordPolicy` is the permissive default. It accepts every password without validation. It exists so the policy dropdown always has a valid selection when no enforcement is wanted. `CommonPasswordPolicy` enforces a baseline. A minimum of 12 characters, at least one digit, one special character, one uppercase letter, and one lowercase letter. Its `getDescription()` return value is rendered in an info callout before the password field so users know the requirements before submitting. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

Registers `CommonPasswordPolicy` and `AnyPasswordPolicy` so they are available when `PasswordPolicyHook::loadConfigured()` resolves the active policy at runtime. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

Adds a policy selector to Configuration > Application > General. The dropdown lists all registered `PasswordPolicyHook` implementations by their display name. The selected value is persisted under `[authentication]` in `config.ini` and read back by `PasswordPolicyHook::loadConfigured()` at runtime. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

`PasswordPolicyHelper::apply()` is wired into every form that sets or resets a database-backed password. The user account change-password form, the admin user create and edit form, and the setup wizard admin account page. `UserForm` previously shared element creation between insert and update by having `createUpdateElements` call `createInsertElements`. That gave the update path a password element identical to insert's, making it impossible for each path to attach the validator with the correct `$oldPasswordElementName` argument. Extracting the shared fields into `createCommonElements` gives each path independent control over its own password element. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

Adds a new section to the authentication chapter covering the built-in policies and their configuration under Configuration > Application > General, and a worked example of a custom policy module with the full hook implementation, `module.info`, and `run.php` registration. Co-authored-by: Johannes Rauh <johannes.rauh@icinga.com> Co-authored-by: Alexander Rieß <alexander.riess@icinga.com>

JolienTrog requested a review from Al2Klimov August 26, 2025 09:22

cla-bot Bot added the cla/signed label Aug 26, 2025

This comment was marked as resolved.

Sign in to view

JolienTrog requested a review from Al2Klimov August 26, 2025 15:21

Al2Klimov reviewed Aug 26, 2025

View reviewed changes

JolienTrog requested a review from Al2Klimov August 27, 2025 07:53

Al2Klimov reviewed Aug 27, 2025

View reviewed changes

Comment thread library/Icinga/Authentication/PasswordValidator.php Outdated

Comment thread application/forms/Account/ChangePasswordForm.php Outdated

Comment thread application/forms/Config/GeneralConfigForm.php Outdated

Comment thread application/forms/Account/ChangePasswordForm.php Outdated

Al2Klimov reviewed Aug 27, 2025

View reviewed changes

Comment thread library/Icinga/Authentication/PasswordValidator.php Outdated

Comment thread library/Icinga/Application/ProvidedHook/DefaultPasswordPolicy.php Outdated

Comment thread library/Icinga/Authentication/PasswordValidator.php Outdated

Al2Klimov reviewed Aug 27, 2025

View reviewed changes

Comment thread library/Icinga/Authentication/PasswordValidator.php Outdated

Comment thread application/forms/Account/ChangePasswordForm.php Outdated

JolienTrog requested a review from Al2Klimov August 28, 2025 08:35