Implement password policy with hook

application/forms/Account/ChangePasswordForm.php

@@ -3,6 +3,7 @@
 
 namespace Icinga\Forms\Account;
 
+use Icinga\Authentication\PasswordPolicyHelper;
 use Icinga\Authentication\User\DbUserBackend;
 use Icinga\Data\Filter\Filter;
 use Icinga\User;
@@ -46,10 +47,12 @@ public function createElements(array $formData)
             'password',
             'new_password',
             array(
-                'label'         => $this->translate('New Password'),
-                'required'      => true
+                'label'      => $this->translate('New Password'),
+                'required'   => true
             )
         );
+        PasswordPolicyHelper::applyPasswordPolicy($this, 'new_password', 'old_password');
+
         $this->addElement(
             'password',
             'new_password_confirmation',

application/forms/Config/General/PasswordPolicyConfigForm.php

@@ -0,0 +1,37 @@
+<?php
+/* Icinga Web 2 | (c) 2025 Icinga GmbH | GPLv2+ */
+
+namespace Icinga\Forms\Config\General;
+
+use Icinga\Application\Hook\PasswordPolicyHook;
+use Icinga\Authentication\PasswordPolicyHelper;
+use Icinga\Web\Form;
+
+/**
+ * Configuration form for password policy selection
+ *
+ * This form is not used directly but as subform for the {@link GeneralConfigForm}.
+ */
+class PasswordPolicyConfigForm extends Form
+{
+    public function init(): void
+    {
+        $this->setName('form_config_general_password_policy');
+    }
+
+    public function createElements(array $formData): static
+    {
+        $this->addElement(
+            'select',
+            sprintf('%s_%s', PasswordPolicyHelper::CONFIG_SECTION, PasswordPolicyHelper::CONFIG_KEY),
+            [
+                'description'  => $this->translate('Enforce password requirements for new passwords'),
+                'label'        => $this->translate('Password Policy'),
+                'value'        => PasswordPolicyHelper::DEFAULT_PASSWORD_POLICY,
+                'multiOptions' => PasswordPolicyHook::all()
+            ]
+        );
+
+        return $this;
+    }
+}

application/forms/Config/GeneralConfigForm.php

@@ -7,6 +7,7 @@
 use Icinga\Forms\Config\General\DefaultAuthenticationDomainConfigForm;
 use Icinga\Forms\Config\General\LoggingConfigForm;
 use Icinga\Forms\Config\General\ThemingConfigForm;
+use Icinga\Forms\Config\General\PasswordPolicyConfigForm;
 use Icinga\Forms\ConfigForm;
 
 /**
@@ -32,9 +33,11 @@ public function createElements(array $formData)
         $loggingConfigForm = new LoggingConfigForm();
         $themingConfigForm = new ThemingConfigForm();
         $domainConfigForm = new DefaultAuthenticationDomainConfigForm();
+        $passwordPolicyConfigForm = new PasswordPolicyConfigForm();
         $this->addSubForm($appConfigForm->create($formData));
         $this->addSubForm($loggingConfigForm->create($formData));
         $this->addSubForm($themingConfigForm->create($formData));
         $this->addSubForm($domainConfigForm->create($formData));
+        $this->addSubForm($passwordPolicyConfigForm->create($formData));
     }
 }

application/forms/Config/User/UserForm.php

@@ -4,9 +4,13 @@
 namespace Icinga\Forms\Config\User;
 
 use Icinga\Application\Hook\ConfigFormEventsHook;
+use Icinga\Application\Logger;
+use Icinga\Authentication\PasswordPolicyHelper;
 use Icinga\Data\Filter\Filter;
 use Icinga\Forms\RepositoryForm;
+use Icinga\Web\Form\Element\Note;
 use Icinga\Web\Notification;
+use Throwable;
 
 class UserForm extends RepositoryForm
 {
@@ -38,10 +42,11 @@ protected function createInsertElements(array $formData)
             'password',
             'password',
             array(
-                'required'  => true,
-                'label'     => $this->translate('Password')
+                'required'   => true,
+                'label'      => $this->translate('Password')
             )
         );
+        PasswordPolicyHelper::applyPasswordPolicy($this, 'password');
 
         $this->setTitle($this->translate('Add a new user'));
         $this->setSubmitLabel($this->translate('Add'));

doc/05-Authentication.md

@@ -158,6 +158,107 @@ resource = icingaweb-mysql
 Please read [this chapter](20-Advanced-Topics.md#advanced-topics-authentication-tips-manual-user-database-auth)
 in order to manually create users directly inside the database.
 
+### Password Policy <a id="authentication-password-policy"></a>
+
+Icinga Web supports password policies when using database authentication. 
+You can configure this under **Configuration > Application > General**. 
+
+By default, no password policy is enforced (`Any`). 
+Icinga Web provides a built-in policy called `Common` with the following requirements:
+
+* Minimum length of 12 characters
+* At least one number
+* At least one special character
+* At least one uppercase letter
+* At least one lowercase letter
+
+#### Custom Password Policy <a id="authentication-custom-password-policy"></a>
+
+You can create custom password policies by developing a module with a provided hook.
+
+**Create Module Structure**
+```bash
+mkdir -p /usr/share/icingaweb2/modules/mypasswordpolicy/library/Mypasswordpolicy/ProvidedHook 
+cd /usr/share/icingaweb2/modules/mypasswordpolicy
+```
+
+Create `module.info`:
+```ini
+Module: mypasswordpolicy
+Name: My Password Policy
+Version: 1.0.0
+Description: Custom password policy implementation
+```
+
+**Implement the Hook**
+
+Icinga Web provides the `PasswordPolicyHook` with predefined methods 
+that simplify the extension of custom password policies.
+
+Create `library/Mypasswordpolicy/ProvidedHook/PasswordPolicy.php`:
+
+```php
+<?php
+
+namespace Icinga\Module\Mypasswordpolicy\ProvidedHook;
+
+use Icinga\Application\Hook\PasswordPolicyHook;use ipl\I18n\Translation;
+
+class PasswordPolicy extends PasswordPolicyHook
+{
+    use Translation;
+
+    public function getName(): string
+    {
+        return 'My Custom Policy';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Custom password requirements: 8+ chars, 1 number';
+    }
+
+    public function validate(string $newPassword, ?string $oldPassword = null): array;
+    {
+        $violations = [];
+
+        if (strlen($newPassword) < 8) {
+            $violations[] = 'Password must be at least 8 characters';
+        }
+
+        if (! preg_match('/[0-9]/', $newPassword)) {
+            $violations[] = 'Password must contain at least one number';
+        }
+
+        if ($oldPassword !== null && hash_equals($oldPassword, $newPassword)) {
+            $violations[] = 'New password must be different from the old password';
+        }
+
+        return $violations;
+    }
+}
+?>
+```
+
+**Register the Hook**
+
+Create `run.php`:
+```php
+<?php
+
+use Icinga\Module\Mypasswordpolicy\ProvidedHook\MyPasswordPolicy;
+Mypasswordpolicy::register();
+?>
+```
+
+Enable the module:
+```bash
+icingacli module enable mypasswordpolicy
+```
+
+You can choose in the settings the preferred password policy.
+
+The custom policy will now appear in **Configuration > Application > General** under Password Policy.
 
 ## Groups <a id="authentication-configuration-groups"></a>
 

library/Icinga/Application/ApplicationBootstrap.php

@@ -6,16 +6,18 @@
 use DirectoryIterator;
 use ErrorException;
 use Exception;
-use Icinga\Application\ProvidedHook\DbMigration;
-use ipl\I18n\GettextTranslator;
-use ipl\I18n\StaticTranslator;
-use LogicException;
 use Icinga\Application\Modules\Manager as ModuleManager;
+use Icinga\Application\ProvidedHook\DbMigration;
 use Icinga\Authentication\User\UserBackend;
 use Icinga\Data\ConfigObject;
 use Icinga\Exception\ConfigurationError;
-use Icinga\Exception\NotReadableError;
 use Icinga\Exception\IcingaException;
+use Icinga\Exception\NotReadableError;
+use ipl\I18n\GettextTranslator;
+use ipl\I18n\StaticTranslator;
+use LogicException;
+use Icinga\Application\ProvidedHook\AnyPasswordPolicy;
+use Icinga\Application\ProvidedHook\CommonPasswordPolicy;
 
 /**
  * This class bootstraps a thin Icinga application layer
@@ -740,6 +742,8 @@ public function hasLocales()
     protected function registerApplicationHooks(): self
     {
         Hook::register('DbMigration', DbMigration::class, DbMigration::class);
+        CommonPasswordPolicy::register();
+        AnyPasswordPolicy::register();
 
         return $this;
     }

library/Icinga/Application/Hook/PasswordPolicyHook.php

@@ -0,0 +1,44 @@
+<?php
+/* Icinga Web 2 | (c) 2025 Icinga GmbH | GPLv2+ */
+
+namespace Icinga\Application\Hook;
+
+use Icinga\Application\Hook;
+use Icinga\Authentication\PasswordPolicy;
+
+/**
+ * Base class for hookable password policies
+ */
+abstract class PasswordPolicyHook implements PasswordPolicy
+{
+    /**
+     * Hook name
+     */
+    protected const HOOK_NAME = 'PasswordPolicy';
+
+    /**
+     * Register password policy
+     *
+     * @return void
+     */
+    public static function register(): void
+    {
+        Hook::register(self::HOOK_NAME, static::class, static::class);
+    }
+
+    /**
+     * Return all registered password policies sorted by name
+     *
+     * @return array
+     */
+    public static function all(): array
+    {
+        $passwordPolicies = [];
+        foreach (Hook::all('PasswordPolicy') as $class => $policy) {
+            $passwordPolicies[$class] = $policy->getName();
+        }
+        asort($passwordPolicies);
+
+        return $passwordPolicies;
+    }
+}

library/Icinga/Application/ProvidedHook/AnyPasswordPolicy.php

@@ -0,0 +1,31 @@
+<?php
+/* Icinga Web 2 | (c) 2025 Icinga GmbH | GPLv2+ */
+
+namespace Icinga\Application\ProvidedHook;
+
+use Icinga\Application\Hook\PasswordPolicyHook;
+use ipl\I18n\Translation;
+
+/**
+ * Policy to allow any password
+ */
+class AnyPasswordPolicy extends PasswordPolicyHook
+{
+    use Translation;
+
+    public function getName(): string
+    {
+        // Policy is named 'None' to indicate that no password policy is enforced and any password is accepted
+        return $this->translate('None');
+    }
+
+    public function getDescription(): ?string
+    {
+        return null;
+    }
+
+    public function validate(string $newPassword, ?string $oldPassword = null): array
+    {
+        return [];
+    }
+}

library/Icinga/Application/ProvidedHook/CommonPasswordPolicy.php

@@ -0,0 +1,62 @@
+<?php
+/* Icinga Web 2 | (c) 2025 Icinga GmbH | GPLv2+ */
+
+namespace Icinga\Application\ProvidedHook;
+
+use Icinga\Application\Hook\PasswordPolicyHook;
+use ipl\I18n\Translation;
+
+/**
+ * Common implementation of a password policy
+ *
+ * Enforces:
+ * - Minimum length of 12 characters
+ * - At least one number
+ * - At least one special character
+ * - At least one uppercase letter
+ * - At least one lowercase letter
+ */
+class CommonPasswordPolicy extends PasswordPolicyHook
+{
+    use Translation;
+
+    public function getName(): string
+    {
+        return $this->translate('Common');
+    }
+
+    public function getDescription(): ?string
+    {
+        return $this->translate(
+            'Password requirements: minimum 12 characters, ' .
+            'at least 1 number, 1 special character, uppercase and lowercase letters.'
+        );
+    }
+
+    public function validate(string $newPassword, ?string $oldPassword = null): array
+    {
+        $violations = [];
+
+        if (mb_strlen($newPassword) < 12) {
+            $violations[] = $this->translate('Password must be at least 12 characters long');
+        }
+
+        if (! preg_match('/[0-9]/', $newPassword)) {
+            $violations[] = $this->translate('Password must contain at least one number');
+        }
+
+        if (! preg_match('/[^a-zA-Z0-9]/', $newPassword)) {
+            $violations[] = $this->translate('Password must contain at least one special character');
+        }
+
+        if (! preg_match('/[A-Z]/', $newPassword)) {
+            $violations[] = $this->translate('Password must contain at least one uppercase letter');
+        }
+
+        if (! preg_match('/[a-z]/', $newPassword)) {
+            $violations[] = $this->translate('Password must contain at least one lowercase letter');
+        }
+
+        return $violations;
+    }
+}