Pre & Post Hook configuration

How it works?

You can write a script that will be called before changing a password (pre hook) or after a successful password change (post hook).

This allow for example to update a file or a database on password change.

This script must be executable by the user running Apache. It will take 3 arguments:

  • $login : the user login

  • $newpassword : the new password

  • $oldpassword : the old password

Tip

The old password is only provided on standard password change, not on password reset

To declare this script, use:

$prehook = "/usr/share/self-service-password/prehook.sh";
$posthook = "/usr/share/self-service-password/posthook.sh";

You can choose to display an error if the script return code is greater than 0:

$display_prehook_error = true;
$display_posthook_error = true;

The displayed message will be the first line of the script output.

Another option can be enabled to encode the password in base64 before sending it to the script, which can avoid an execution issue if the password contains special characters:

$prehook_password_encodebase64 = false;
$posthook_password_encodebase64 = false;

By default With prehook script, the password will not be changed in LDAP directory if the script fails. You can change this behavior to ignore script error. This could be useful to run prehook script and display a warning if it fails, but still try to update password in the directory.

$ignore_prehook_error = true;

Here is an example of a simple hook script:

#!/bin/bash

LOGIN=$1
NEWPASSWORD=$2
OLDPASSWORD=$3

echo `date` >> /tmp/posthook.log
echo "$LOGIN / $NEWPASSWORD / $OLDPASSWORD" >> /tmp/posthook.log

... there is an error ...
echo "Posthook script has failed"
exit 1
... there is no error ...
exit 0

Warning

This script is an example, do use not it in production: passwords should never be put in logs. Write your own script to propagate the password in a safe place

Warning

If you are using systemd, it is possible that the PrivateTmp feature is enabled by default for Apache (in your httpd.service or apache2.service).

When enabled, all logs written from posthook.sh to /tmp will be redirected to /tmp/systemd-private-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-apache2.service-XXXXXX/tmp or similar.

Example : Multi LDAP posthook

You can configure multiple LDAP backend.

To enable this option, you have to add the posthook :

$posthook = "php /usr/share/self-service-password/multi_ldap_change.php";

You need to add the list of your ldap backend :

$secondaries_ldap[0]['ldap_url'] = 'ldap://ldap2.example.com';
$secondaries_ldap[1]['ldap_url'] = 'ldap://ldap3.example.com';

It’s necessary to activate the base64 enconding for special characters. You can be enabled this option with this configuration line :

$posthook_password_encodebase64 = true;

Warning

This script suppose that you use the same credentials on all your backend.