821 reset url doc

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on: [push]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: PHPUnit Tests for php7.4
+      uses: php-actions/phpunit@v3
+      with:
+        configuration: tests/phpunit.xml
+        version: 5.7.25
+        php_version: 7.4
+        args: --coverage-text

.gitignore

@@ -0,0 +1 @@
+/vendor/

README.md

@@ -1,7 +1,7 @@
 # LDAP Tool Box Self Service Password
 
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/372/badge)](https://bestpractices.coreinfrastructure.org/projects/372)
-[![Build Status](https://travis-ci.org/ltb-project/self-service-password.svg?branch=master)](https://travis-ci.org/ltb-project/self-service-password)
+[![Build Status](https://github.com/ltb-project/self-service-password/actions/workflows/ci.yml/badge.svg)](https://github.com/ltb-project/self-service-password/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/self-service-password/badge/?version=latest)](https://self-service-password.readthedocs.io/en/latest/?badge=latest)
 
 ## Presentation

composer.json

@@ -0,0 +1,5 @@
+{
+    "require": {
+        "ltb-project/ldap": "v0.1.0"
+    }
+}

conf/config.inc.php

@@ -303,6 +303,12 @@
 # Changing it will also invalidate all previous tokens and SMS codes
 $keyphrase = "secret";
 
+# Use attributes update page
+$use_attributes = false;
+#$attribute_mail = "mail";
+#$attribute_phone = "mobile";
+#$who_change_attributes = "manager";
+
 # Reset URL (if behind a reverse proxy)
 #$reset_url = $_SERVER['HTTP_X_FORWARDED_PROTO'] . "://" . $_SERVER['HTTP_X_FORWARDED_HOST'] . $_SERVER['SCRIPT_NAME'];
 
@@ -355,6 +361,9 @@
 #$messages['passwordchangedextramessage'] = NULL;
 #$messages['changehelpextramessage'] = NULL;
 
+# Audit
+#$audit_log_file = "/var/log/self-service-password/audit.log";
+
 ## Pre Hook
 # Launch a prehook script before changing password.
 # Script should return with 0, to allow password change.

docs/audit.rst

@@ -0,0 +1,39 @@
+.. _audit:
+
+Audit
+=====
+
+You can enable audit to log all actions done through Self Service Password.
+
+The items provided in the audit log are:
+
+* Date
+* IP of connected user
+* DN of account being updated (user DN, can be empty if error occurs before finding the DN)
+* Who has done the action (user login)
+* Action
+* Result of the action
+
+Example:
+
+.. code-block:: json
+
+   {
+    "date":"Wed, 21 Jun 2023 15:58:11",
+    "ip":"127.0.0.1",
+    "user_dn":"uid=donald,ou=users,dc=example,dc=com",
+    "done_by":"donald",
+    "action":"change",
+    "result":"nomatch"
+   }
+
+Audit log file
+--------------
+
+Set the file where actions are logged:
+
+.. code-block:: php
+
+   $audit_log_file = "/var/log/self-service-password/audit.log";
+
+.. tip:: The file must be writable by the PHP or WebServer process

docs/config_general.rst

@@ -259,14 +259,19 @@ Prefill user login
 ------------------
 
 If Self Service Password is called from another application, you can
-prefill the login but sending an HTTP header.
+prefill the login by sending an HTTP header.
 
-To enable this feature:
+To enable this feature, configure the name of the HTTP header:
 
 .. code-block:: php
 
    $header_name_preset_login = "Auth-User";
 
+It is also possible to prefill the login by using the ``login_hint``
+GET or POST parameter. This method does not require any configuration.
+
+Example: ``https://ssp.example.com/?actionresetbyquestions&login_hint=spiderman``
+
 Captcha
 -------
 

docs/config_sms.rst

@@ -13,6 +13,9 @@ reset code trough SMS.
 A message is sent either to an Email to SMS gateway, either trough an
 API (called with PHP code or by script).
 
+.. tip:: You can enable :ref:`set_attributes` feature to allow users to
+   update their phone number in the LDAP directory.
+
 SMS provider
 ------------
 

docs/config_tokens.rst

@@ -14,6 +14,9 @@ Then, the user click on the link in the mail, an can set a new password.
 .. tip:: PHP sessions are used to store and retrieve token on server
   side.
 
+.. tip:: You can enable :ref:`set_attributes` feature to allow users to
+   update their mail address in the LDAP directory.
+
 Activation
 ----------
 
@@ -81,3 +84,4 @@ this case you can set yourself the reset URL:
 
    $reset_url = $_SERVER['HTTP_X_FORWARDED_PROTO'] . "://" . $_SERVER['HTTP_X_FORWARDED_HOST'] . $_SERVER['SCRIPT_NAME'];
 
+.. warning:: Make sure your webserver/reverse-proxy hosting self-service-password is only answering to a dedicated Full Qualified Domain Name. Else you should define a hard-coded ``$reset_url`` parameter for preventing self-service-password to forge urls based on arbitrary host headers.

docs/index.rst

@@ -22,4 +22,5 @@ LDAP Tool Box Self Service Password documentation
    config_sshkey.rst
    config_rate_limit.rst
    webservices.rst
-
+   audit.rst
+   set_attributes.rst

docs/set_attributes.rst

@@ -0,0 +1,50 @@
+.. _set_attributes:
+
+Attributes update
+=================
+
+You can allow user to update their mail or phone in the LDAP directory.
+
+Users need of course to authenticate to change these information.
+
+When enabling this feature, a note will be added in help messages to advertise users they can change their mail or their phone. You can also access directly to the page with ``?action=setattributes``.
+
+Activation
+----------
+
+Enable the feature:
+
+.. code-block:: php
+
+   $use_attributes = true;
+
+Mail attribute
+--------------
+
+Define which attribute contains the mail address:
+
+.. code-block:: php
+
+   $attribute_mail = "mail";
+
+.. tip:: If attribute is not defined, the mail is not displayed in set attributes page.
+
+Phone attribute
+---------------
+
+Define which attribute contains the phone number:
+
+.. code-block:: php
+
+   $attribute_phone = "mobile";
+
+.. tip:: If attribute is not defined, the phone is not displayed in set attributes page.
+
+Who change attributes
+----------------------
+
+By default the change is done in LDAP directory with the user account. You can change this behavior to let the SSP service account do the change:
+
+.. code-block:: php
+
+   $who_change_attributes = "manager";