Hooks¶
Modules provide hook implementations by extending one of the base classes in
Icinga\Application\Hook\. The class goes in the module’s ProvidedHook namespace:
library/<ModuleName>/ProvidedHook/<HookName>.php
For Icinga Web to call a hook, it needs to be registered. This happens in the module’s run.php:
<?php
use Icinga\Module\Acme\ProvidedHook\MyHook;
MyHook::register();
Writing a Hook ¶
Modules can define their own hook types for other modules to implement. The abstract base class goes in
library/<ModuleName>/Hook/<HookName>.php. Use the HookEssentials trait and implement getHookName(),
which returns a string that uniquely identifies the hook type:
<?php
namespace Icinga\Module\Acme\Hook;
use Icinga\Application\Hook\HookEssentials;
abstract class TicketHook
{
use HookEssentials;
protected static function getHookName(): string
{
return 'Acme/Ticket';
}
abstract public function createTicket(string $title): string;
}
The trait provides all() and first() for retrieving registered implementations,
isRegistered() to check if a hook of this type is already registered, and register()
for implementors to register themselves.
By default, an implementation is skipped for users without the module/<module-name> permission of the
providing module. Override isAlwaysRun() to return true if the hook should run regardless:
protected static function isAlwaysRun(): bool
{
return true;
}
Implement the new Hook ¶
Other modules can now provide implementations of the hook. Registration works
as described earlier, but the class goes in a subnamespace of the implementing
module’s ProvidedHook namespace:
library/<ModuleName>/ProvidedHook/Acme/<HookName>.php
Don’t forget to register the hook in the run.php.
CspHook ¶
The CspHook lets modules add directives to the Content Security Policy (CSP)
that Icinga Web sends when strict CSP is enabled. Icinga Web uses the hook only
if Enable Modules is enabled at Configuration > Application > Security
and no custom CSP is configured. The hook always runs, regardless of the
module/<module-name> permission.
Both methods return an ipl\Web\Common\Csp instance:
getCspForAllUsers()returns the directives every user needs, for example hosts from the module configuration. Icinga Web adds them to the CSP of every user and lists them in the CSP overview on the Security page.getCspForUser(User $user)returns the directives only the given user needs, for example a host from the user’s preferences. Icinga Web adds them to the CSP of that user only. The CSP overview does not list them. Implementing this method is optional. By default, it returns an empty CSP.
Icinga Web merges the directives of all modules with its own directives.
Modules can only add directives. Setting default-src is not allowed.
Hook example:
namespace Icinga\Module\Acme\ProvidedHook;
use Icinga\Application\Hook\CspHook;
use Icinga\User;
use ipl\Web\Common\Csp as CspInstance;
class Csp extends CspHook
{
public function getCspForAllUsers(): CspInstance
{
$csp = new CspInstance();
$csp->add('img-src', ['cdn.example.com', 'usercontent.example.com']);
$csp->add('style-src', 'cdn.example.com');
return $csp;
}
public function getCspForUser(User $user): CspInstance
{
$csp = new CspInstance();
$imageHost = $user->getPreferences()->getValue('acme', 'image_host');
if ($imageHost !== null) {
$csp->add('img-src', $imageHost);
}
return $csp;
}
}
TwoFactorHook ¶
The TwoFactorHook allows modules to provide a two-factor authentication method,
such as TOTP or email token. Icinga Web asks every registered method whether a user
is enrolled, and if so, requires the second factor after the primary login succeeds.
This hook always runs, regardless of the module/<module-name> permission.
Icinga Web derives a canonical name in the format <module>/<name>
(e.g. mymodule/totp) from the providing module and getName(), so two modules
may register a method using the same getName() without colliding.
If the module providing a user’s enrolled method is disabled, that method is no longer registered. The user’s enrollment is then ignored and they log in without a second factor. This is expected when an administrator disables a 2FA module.
The example below calls loadSecret(), checkToken(), generateSecret(),
storeSecret(), and deleteSecret(). These are placeholders that neither
TwoFactorHook nor this example provides. A real implementation must supply
them, including secure secret generation, token verification, and protected
persistent storage of the per-user secret.
Hook example:
<?php
namespace Icinga\Module\Mymodule\ProvidedHook;
use Icinga\Application\Hook\TwoFactorHook;
use Icinga\User;
use ipl\Html\FormElement\FieldsetElement;
use ipl\I18n\Translation;
use SensitiveParameter;
class TotpTwoFactor extends TwoFactorHook
{
use Translation;
public function getName(): string
{
return 'totp';
}
public function getDisplayName(): string
{
return $this->translate('TOTP');
}
public function isEnrolled(User $user): bool
{
return $this->loadSecret($user) !== null;
}
public function verify(User $user, #[SensitiveParameter] string $token): bool
{
return $this->checkToken($this->loadSecret($user), $token);
}
public function assembleEnrollmentFormElements(User $user, FieldsetElement $fieldset): void
{
$fieldset->addElement('text', 'secret', [
'readonly' => true,
'value' => $this->generateSecret(),
]);
$fieldset->addElement('text', 'token', [
'label' => $this->translate('Verification Code'),
'required' => true,
]);
}
public function enroll(User $user, FieldsetElement $fieldset): bool
{
$secret = $fieldset->getValue('secret');
if (! $this->checkToken($secret, $fieldset->getValue('token'))) {
$fieldset->getElement('token')->addMessage($this->translate('Invalid code'));
return false;
}
$this->storeSecret($user, $secret);
return true;
}
public function unenroll(User $user): void
{
$this->deleteSecret($user);
}
}
PasswordPolicyHook ¶
The PasswordPolicyHook allows modules to provide custom
password policies.
This hook always runs, regardless of the providing module’s
module/<module-name> permission.
Icinga Web derives a canonical name in the format <module>/<name>
(e.g. mypasswordpolicy/my-custom-policy) from the providing module and
getName(). This is what gets stored in the configuration file and must be
unique across all registered policies.
Hook example:
<?php
namespace Icinga\Module\Mypasswordpolicy\ProvidedHook;
use Icinga\Application\Hook\PasswordPolicyHook;
use ipl\Html\Text;
use ipl\Html\ValidHtml;
use ipl\I18n\Translation;
use SensitiveParameter;
class PasswordPolicy extends PasswordPolicyHook
{
use Translation;
public function getDisplayName(): string
{
return $this->translate('My Custom Policy');
}
public function getName(): string
{
return 'my-custom-policy';
}
public function getDescription(): ?ValidHtml
{
return new Text(
$this->translate('At least 8 characters, at least 1 number, and must differ from the last password'),
);
}
public function validate(
#[SensitiveParameter] string $newPassword,
#[SensitiveParameter] ?string $oldPassword = null,
): array {
$violations = [];
if (mb_strlen($newPassword) < 8) {
$violations[] = $this->translate('Password must be at least 8 characters long');
}
if (! preg_match('/[0-9]/', $newPassword)) {
$violations[] = $this->translate('Password must contain at least one number');
}
if ($oldPassword !== null && hash_equals($oldPassword, $newPassword)) {
$violations[] = $this->translate('New password must differ from the old password');
}
return $violations;
}
}