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;
@@ -45,11 +46,14 @@ public function createElements(array $formData)
         $this->addElement(
             'password',
             'new_password',
-            array(
-                'label'         => $this->translate('New Password'),
-                'required'      => true
-            )
+            [
+                'label'      => $this->translate('New Password'),
+                'required'   => true
+            ]
         );
+
+        PasswordPolicyHelper::applyPasswordPolicy($this, 'new_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
 {
@@ -37,12 +41,14 @@ protected function createInsertElements(array $formData)
         $this->addElement(
             '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,97 @@ 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
+Name: My Password Policy
+Version: 1.0.0
+Description: Custom password policy implementation
+Author: Your Name
+```
+
+**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
+namespace Icinga\Module\MyPasswordPolicy\ProvidedHook;
+
+use Icinga\Application\Hook\PasswordPolicyHook;
+
+class PasswordPolicy extends PasswordPolicyHook
+{
+    public function getName(): string
+    {
+        return 'My Custom Policy';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Custom password requirements: 8+ chars, 1 number';
+    }
+
+    public function validate(string $password): array
+    {
+        $violations = [];
+
+        if (strlen($password) < 8) {
+            $violations[] = 'Password must be at least 8 characters';
+        }
+
+        if (!preg_match('/[0-9]/', $password)) {
+            $violations[] = 'Password must contain at least one number';
+        }
+
+        return $violations;
+    }
+}
+```
+
+**Register the Hook**
+
+Create `run.php`:
+```php  
+/** @var $this \Icinga\Application\Modules\Module */
+
+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,20 @@
 use DirectoryIterator;
 use ErrorException;
 use Exception;
-use Icinga\Application\ProvidedHook\DbMigration;
-use ipl\I18n\GettextTranslator;
-use ipl\I18n\StaticTranslator;
-use LogicException;
+use Icinga\Application\Hook\PasswordPolicyHook;
 use Icinga\Application\Modules\Manager as ModuleManager;
+use Icinga\Application\ProvidedHook\AnyPasswordPolicy;
+use Icinga\Application\ProvidedHook\CommonPasswordPolicy;
+use Icinga\Application\ProvidedHook\DbMigration;
+use Icinga\Authentication\PasswordPolicy;
 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;
 
 /**
  * This class bootstraps a thin Icinga application layer
@@ -740,6 +744,9 @@ 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,40 @@
+<?php
+/* Icinga Web 2 | (c) 2025 Icinga GmbH | GPLv2+ */
+
+namespace Icinga\Application\Hook;
+
+use Icinga\Application\Hook;
+use Icinga\Authentication\PasswordPolicy;
+
+/**
+ * This class connects with the PasswordPolicy interface to use it as hook
+ */
+abstract class PasswordPolicyHook implements PasswordPolicy
+{
+    /**
+    * Registers Hook as Password Policy
+    *
+    * @return void
+    */
+    public static function register(): void
+    {
+        Hook::register('PasswordPolicy', static::class, static::class);
+    }
+
+    /**
+    * Returns all registered password policies sorted by
+    *
+    * @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,35 @@
+<?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;
+
+    /**
+     *  Policy named 'none' to indicate that no password policy is enforced and any password is accepted
+     *
+     * @return string
+     */
+    public function getName(): string
+    {
+        return $this->translate('None');
+    }
+
+    public function getDescription(): ?string
+    {
+        return null;
+    }
+
+    public function validate(string $password): array
+    {
+        return [];
+    }
+}

library/Icinga/Application/ProvidedHook/CommonPasswordPolicy.php

@@ -0,0 +1,63 @@
+<?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 $password): array
+    {
+        $violations = [];
+
+        if (mb_strlen($password) < 12) {
+            $violations[] = $this->translate('Password must be at least 12 characters long');
+        }
+
+        if (! preg_match('/[0-9]/', $password)) {
+            $violations[] = $this->translate('Password must contain at least one number');
+        }
+
+        if (! preg_match('/[^a-zA-Z0-9]/', $password)) {
+            $violations[] = $this->translate('Password must contain at least one special character');
+        }
+
+        if (! preg_match('/[A-Z]/', $password)) {
+            $violations[] = $this->translate('Password must contain at least one uppercase letter');
+        }
+
+        if (! preg_match('/[a-z]/', $password)) {
+            $violations[] = $this->translate('Password must contain at least one lowercase letter');
+        }
+
+        return $violations;
+    }
+}