Document password policy configuration and extension

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>

Author: 3 people

doc/05-Authentication.md

@@ -158,6 +158,108 @@ 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;
+
+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 $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:
+```shell
+icingacli module enable mypasswordpolicy
+```
+
+The custom policy will now appear in **Configuration > Application > General** under Password Policy.
 
 ## Groups <a id="authentication-configuration-groups"></a>