Feat http notifications

conf/config.inc.php

@@ -181,7 +181,9 @@
 
 # Notify users anytime their sshPublicKey is changed
 ## Requires mail configuration below
-$notify_on_sshkey_change = false;
+$mail_notify_on_sshkey_change = false;
+## Or HTTP notifications configuration
+$http_notify_on_sshkey_change = false;
 
 ## Questions/answers
 # Use questions/answers?
@@ -241,7 +243,22 @@
 $mail_from_name = "Self Service Password";
 $mail_signature = "";
 # Notify users anytime their password is changed
-$notify_on_change = false;
+$mail_notify_on_change = false;
+
+# HTTP notifications settings / Disable them
+$http_notifications_address = false;
+$http_notifications_body = false;
+$http_notifications_headers = array();
+$http_notifications_method = 'POST';
+$http_notifications_params = array();
+# Use http notifications confirming password changes
+$http_notify_on_change = false;
+# Use http notifications submitting password resets
+$use_httpreset = false;
+# TODO/maybe: use an alternate attribute submitting HTTP notifications?
+# $http_notifications_login_attribute = "uid";
+# $http_notifications_ldap_filter = "(&(objectClass=person)($http_notifications_ldap_login_attribute={login}))";
+
 # PHPMailer configuration (see https://github.com/PHPMailer/PHPMailer)
 $mail_sendmailpath = '/usr/sbin/sendmail';
 $mail_protocol = 'smtp';
@@ -288,7 +305,7 @@
 # Max attempts allowed for SMS token
 $max_attempts = 3;
 
-# Encryption, decryption keyphrase, required if $use_tokens = true and $crypt_tokens = true, or $use_sms, or $crypt_answer
+# Encryption, decryption keyphrase, required if $use_tokens = true and $crypt_tokens = true, or $use_http = true and $crypt_tokens = true, or $use_sms, or $crypt_answer
 # Please change it to anything long, random and complicated, you do not have to remember it
 # Changing it will also invalidate all previous tokens and SMS codes
 $keyphrase = "secret";
@@ -412,3 +429,11 @@
  }
  }
 }
+
+# Legacy configuration options support / translation
+if (isset($notify_on_change)) {
+ $mail_notify_on_change = $notify_on_change;
+}
+if (isset($notify_on_sshkey_change)) {
+ $mail_notify_on_sshkey_change = $notify_on_sshkey_change;
+}

docs/config_http.rst

@@ -0,0 +1,108 @@
+.. _config_http:
+
+HTTP Notifications
+==================
+
+Self-Service-Password could be configured issuing HTTP notifications when updating objects, or sending password reset links.
+
+In an effort to integrate with as much services, as possible, a handful of configuration options would let you customize where and how to submit those notifications.
+
+Slack Configuration
+-------------------
+
+Integrating with Slack, we would create a new app, connecting to https://api.slack.com/apps
+
+We would name it "self-service-password".
+
+Go to the Features / OAuth & Permissions menu. In the Scopes section, select the "chat.write" permission - optionally, "chat.write.customize".
+
+Go to the Basic Informations menu. Building Apps for Slack section, click "Install to Workspace", then "Allow".
+
+Go back to the Features / OAuth & Permissions menu. You would now find your own Bearer Token, that starts wit "xoxb".
+
+Having that token ready, we may now configure Self Service Password integrating with Slack:
+
+.. code:: php
+
+ $http_notifications_address = 'https://slack.com/api/chat.postMessage';
+ $http_notifications_body = array(
+ "channel" => "@{login}",
+ "text" => "{data}",
+ "username" => "self-service-password"
+ );
+ $http_notifications_headers = array(
+ "Authorization: Bearer xoxb-01234567890-0123456789012-abcDEFghiJKLmnoPQRstuVWX",
+ "Content-Type: application/x-www-form-urlencoded"
+ );
+ $http_notifications_method = 'POST';
+ $http_notifications_params = array();
+
+Rocket.Chat Configuration
+-------------------------
+
+Integrating with Rocket.Chat, we would first create a custom Role, connecting to your administration interface: https://chat.example.com/admin/permissions
+
+Create a Role, named "Self Service Password", global scope, click Save. We would then grant that Role with the following privileges: "Bypass rate limit for REST API" (optional), "Create Direct Messages", "Create Personal Access Token", "Send Many Messages" (optional).
+
+Next we would create a new bot user, from https://chat.example.com/admin/users
+
+Create a new user, named "self-service-password", same username, we could set an email address - and confirm it is verified - maybe set a nickname. Set a password, make sure the "Join default channels" and "Send welcome email" are disabled. In the "Roles" selection, pick the one we created above.
+
+Next, we would login to Rocket.Chat, using that bot account credentials. Click your profile picture, enter the "My Account" menu. Then to the "Personal Access Tokens" page, and create a new Token. A popup shows up, giving you a pair of User ID and Token.
+
+Having those credentials ready, we may now configure Self Service Password integrating with Rocket.Chat:
+
+.. code:: php
+
+ $http_notifications_address = 'https://chat.example.com/api/v1/chat.postMessage';
+ $http_notifications_body = array(
+ "alias" => "self-service-password",
+ "roomId" => "@{login}",
+ "text" => "{data}"
+ );
+ $http_notifications_headers = array(
+ "Content-Type: application/json",
+ "X-Auth-Token: auth-token-generated-previously",
+ "X-User-Id: auth-user-generated-previously"
+ );
+ $http_notifications_method = 'POST';
+ $http_notifications_params = array();
+
+Generic GET Configuration
+-------------------------
+
+While the samples above could be reused integrating with services receiving HTTP POST based notifications, in theory, we may also submit those using an HTTP GET request.
+
+A basic configuration, ignoring any authentication considerations, could look like the following:
+
+.. code:: php
+
+ $http_notifications_address = 'https://my.example.com/api/notify-user';
+ $http_notifications_body = array();
+ $http_notifications_headers = array();
+ $http_notifications_method = 'GET';
+ $http_notifications_params = array(
+ "username" => "{login}",
+ "text" => "{data}"
+ );
+
+Reset Password Links
+--------------------
+
+We may allow users to request a password reset link submittion as an HTTP notification adding the following, having configured the variables shown previously:
+
+.. code:: php
+
+ $use_httpreset = true;
+
+.. warning:: If you enable this option, you must change the default
+ value of the security keyphrase.
+
+Change password notification
+----------------------------
+
+Use this option to send an HTTP notification to the user, just after a successful password change:
+
+.. code:: php
+
+ $http_notify_on_change = true;

docs/config_mail.rst

@@ -30,11 +30,11 @@ Change password notification
 ----------------------------
 
 Use this option to send a confirmation mail to the user, just after a
-successful mail change:
+successful password change:
 
 .. code:: php
 
- $notify_on_change = true;
+ $mail_notify_on_change = true;
 
 PHPMailer
 ---------

docs/config_questions.rst

@@ -115,7 +115,7 @@ option can now be used to encrypt answers:
 You can set this option to ``false`` to keep the old behavior.
 
 .. warning:: If you enable this option, you must change the default
- value of the `security keyphrase <config_general#security>`__
+ value of the `security keyphrase <config_general.html#security>`__
 
 A script is provided to encrypt all clear text answers in LDAP
 directory, to allow a swooth migration. Just run the script (it will use

docs/config_sshkey.rst

@@ -47,11 +47,16 @@ If you want the LDAP manager account to edit that attribute, we may instead set
  $who_change_sshkey = "manager"
 
 SSH Public Key changes notification
-----------------------------------
+-----------------------------------
 
-Use this option to send a confirmation mail to the user, just after a
-successful mail change:
+Use this option to send a confirmation mail to the user, just after a successful SSH Public Key change - see <config_mail.html#phpmailer> setting up PHPMailer:
 
 .. code:: php
 
- $notify_on_sshkey_change = true;
+ $mail_notify_on_sshkey_change = true;
+
+Or that one, to send HTTP notifications instead - see :ref:`config_httpnotifications` integrating with some third-party web service:
+
+.. code:: php
+
+ $http_notify_on_sshkey_change = true;

docs/index.rst

@@ -17,6 +17,7 @@ LDAP Tool Box Self Service Password documentation
  config_tokens.rst
  config_sms.rst
  config_mail.rst
+ config_http.rst
  config_preposthook.rst
  config_sshkey.rst
  webservices.rst

htdocs/change.php

@@ -124,7 +124,7 @@
  } else {
 
  # Get user email for notification
- if ($notify_on_change) {
+ if ($mail_notify_on_change) {
  for ($i = 0; $i < sizeof($mail_attributes); $i++) {
  $mailValues = ldap_get_values($ldap, $entry, $mail_attributes[$i]);
  if ($mailValues["count"] > 0) {
@@ -223,10 +223,23 @@
 # Notify password change
 #==============================================================================
 if ($result === "passwordchanged") {
- if ($mail and $notify_on_change) {
+ if ($mail and $mail_notify_on_change) {
  $data = array( "login" => $login, "mail" => $mail, "password" => $newpassword);
- if ( !send_mail($mailer, $mail, $mail_from, $mail_from_name, $messages["changesubject"], $messages["changemessage"].$mail_signature, $data) ) {
+ if (! send_mail($mailer, $mail, $mail_from, $mail_from_name, $messages["changesubject"], $messages["changemessage"].$mail_signature, $data)) {
  error_log("Error while sending change email to $mail (user $login)");
  }
  }
+ if ($http_notifications_address and $http_notify_on_change) {
+ $data = array( "login" => $login, "password" => $newpassword);
+ $httpoptions = array(
+ "address" => $http_notifications_address,
+ "body" => $http_notifications_body,
+ "headers" => $http_notifications_headers,
+ "method" => $http_notifications_method,
+ "params" => $http_notifications_params
+ );
+ if (! send_http($httpoptions, $messages["changemessage"], $data)) {
+ error_log("Error while sending change http notification to $http_notifications_address (user $login)");
+ }
+ }
 }

htdocs/changesshkey.php

@@ -115,7 +115,7 @@
  } else {
 
  # Get user email for notification
- if ($notify_on_sshkey_change) {
+ if ($mail_notify_on_sshkey_change) {
  for ($i = 0; $i < sizeof($mail_attributes); $i++) {
  $mailValues = ldap_get_values($ldap, $entry, $mail_attributes[$i]);
  if ($mailValues["count"] > 0) {
@@ -162,10 +162,23 @@
 # Notify SSH Key change
 #==============================================================================
 if ($result === "sshkeychanged") {
- if ($mail and $notify_on_sshkey_change) {
+ if ($mail and $mail_notify_on_sshkey_change) {
  $data = array( "login" => $login, "mail" => $mail, "sshkey" => $sshkey);
  if (! send_mail($mailer, $mail, $mail_from, $mail_from_name, $messages["changesshkeysubject"], $messages["changesshkeymessage"].$mail_signature, $data)) {
  error_log("Error while sending change email to $mail (user $login)");
  }
  }
+ if ($http_notifications_address and $http_notify_on_sshkey_change) {
+ $data = array( "login" => $login, "sshkey" => $sshkey);
+ $httpoptions = array(
+ "address" => $http_notifications_address,
+ "body" => $http_notifications_body,
+ "headers" => $http_notifications_headers,
+ "method" => $http_notifications_method,
+ "params" => $http_notifications_params
+ );
+ if (! send_http($httpoptions, $messages["changesshkeymessage"], $data)) {
+ error_log("Error while sending change http notification to $http_notifications_address (user $login)");
+ }
+ }
 }

htdocs/index.php

@@ -90,7 +90,11 @@
 if ( ! function_exists('utf8_decode') ) { $dependency_check_results[] = "nophpxml"; }
 
 # Check keyphrase setting
-if ( ( ( $use_tokens and $crypt_tokens ) or $use_sms or $crypt_answers ) and ( empty($keyphrase) or $keyphrase == "secret") ) { $dependency_check_results[] = "nokeyphrase"; }
+if ((($crypt_tokens and ($use_tokens or $use_httpreset or $use_sms))
+ or ($use_questions and $crypt_answers))
+ and (empty($keyphrase) or $keyphrase == "secret")) {
+ $dependency_check_results[] = "nokeyphrase";
+}
 
 
 #==============================================================================
@@ -175,6 +179,7 @@
 if ( $use_questions ) { array_push( $available_actions, "resetbyquestions", "setquestions"); }
 if ( $use_tokens ) { array_push( $available_actions, "resetbytoken", "sendtoken"); }
 if ( $use_sms ) { array_push( $available_actions, "resetbytoken", "sendsms"); }
+if ( $use_httpreset ) { array_push( $available_actions, "resetbytoken", "sendhttp"); }
 
 # Ensure requested action is available, or fall back to default
 if ( ! in_array($action, $available_actions) ) { $action = $default_action; }
@@ -215,6 +220,7 @@
 $smarty->assign('use_questions', $use_questions);
 $smarty->assign('use_tokens', $use_tokens);
 $smarty->assign('use_sms', $use_sms);
+$smarty->assign('use_httpreset', $use_httpreset);
 $smarty->assign('change_sshkey', $change_sshkey);
 $smarty->assign('mail_address_use_ldap', $mail_address_use_ldap);
 $smarty->assign('default_action', $default_action);

htdocs/resetbyquestions.php

@@ -163,7 +163,7 @@
  }
 
  # Get user email for notification
- if ($notify_on_change) {
+ if ($mail_notify_on_change) {
  for ($i = 0; $i < sizeof($mail_attributes); $i++) {
  $mailValues = ldap_get_values($ldap, $entry, $mail_attributes[$i]);
  if ($mailValues["count"] > 0) {
@@ -228,6 +228,13 @@
 
  $entry = ldap_get_attributes($ldap, $entry);
  $entry['dn'] = $userdn;
+
+ if ( $use_ratelimit ) {
+ if ( ! allowed_rate($login,$_SERVER[$client_ip_header],$rrl_config) ) {
+ $result = "throttle";
+ error_log("Question - User $login too fast");
+ }
+ }
  }
  }
  }
@@ -270,9 +277,24 @@
 #==============================================================================
 # Notify password change
 #==============================================================================
-if ($mail and $notify_on_change and $result === 'paswordchanged') {
- $data = array( "login" => $login, "mail" => $mail, "password" => $newpassword);
- if ( !send_mail($mailer, $mail, $mail_from, $mail_from_name, $messages["changesubject"], $messages["changemessage"].$mail_signature, $data) ) {
- error_log("Error while sending change email to $mail (user $login)");
+if ($result === "passwordchanged") {
+ if ($mail and $mail_notify_on_change) {
+ $data = array( "login" => $login, "mail" => $mail, "password" => $newpassword);
+ if (! send_mail($mailer, $mail, $mail_from, $mail_from_name, $messages["changesubject"], $messages["changemessage"].$mail_signature, $data)) {
+ error_log("Error while sending change email to $mail (user $login)");
+ }
+ }
+ if ($http_notifications_address and $http_notify_on_change) {
+ $data = array( "login" => $login, "password" => $newpassword);
+ $httpoptions = array(
+ "address" => $http_notifications_address,
+ "body" => $http_notifications_body,
+ "headers" => $http_notifications_headers,
+ "method" => $http_notifications_method,
+ "params" => $http_notifications_params
+ );
+ if (! send_http($httpoptions, $messages["changemessage"], $data)) {
+ error_log("Error while sending change http notification to $http_notifications_address (user $login)");
+ }
  }
 }