=== Self Password Change ===

LDAP Self Service Password is a web application for end users. It allows them to change or reset their password if they lost it.

You need to install these prerequisites:

- Apache or another web server
- php (>=7.4)
- php-curl (haveibeenpwned api)
- php-filter
- php-gd (captcha)
- php-ldap
- php-mbstring (reset mail)
- php-openssl (token crypt, probably built-in)
- smarty (3 or 4)


'''Installation From tarball'''

Uncompress and unarchive the tarball:
https://ltb-project.org/download.html

{{{$ tar -zxvf ltb-project-self-service-password-*.tar.gz}}}

Install files in /usr/share/:

{{{mkdir /usr/share/self-service-password}}}

{{{mkdir /usr/share/self-service-password/cache}}}

{{{mkdir /usr/share/self-service-password/templates_c}}}

{{{  mv ltb-project-self-service-password-* /usr/share/self-service-password}}}

Adapt ownership of Smarty cache repositories so Apache user can write into them. For example:

{{{chown www-data:www-data /usr/share/self-service-password/cache}}}
{{{chown www-data:www-data /usr/share/self-service-password/templates_c}}}

//Due to a bug in old Debian and Ubuntu smarty3 package, you may face the error syntax error, unexpected token "class". In this case, install a newer version of the package://

//{{{# wget http://ftp.us.debian.org/debian/pool/main/s/smarty3/smarty3_3.1.47-2_all.deb}}}//

//{{{# dpkg -i smarty3_3.1.47-2_all.deb}}}//

'''Configure the repository'''

{{{# vi /etc/apt/sources.list.d/ltb-project.list}}}

{{{deb [arch=amd64 signed-by=/usr/share/keyrings/ltb-project.gpg] https://ltb-project.org/debian/stable stable main}}}

Import repository key:

{{{wget -O - https://ltb-project.org/documentation/_static/RPM-GPG-KEY-LTB-project | gpg --dearmor | sudo tee /usr/share/keyrings/ltb-project.gpg >/dev/null}}}

Then update:

{{{apt update}}}

You are now ready to install:
{{{apt install self-service-password}}}


''' Apache configuration'''

{{{
<VirtualHost *:80>
    ServerName ssp.example.com

    DocumentRoot /usr/share/self-service-password/htdocs
    DirectoryIndex index.php

    AddDefaultCharset UTF-8

    <Directory /usr/share/self-service-password/htdocs>
        AllowOverride None
        <IfVersion >= 2.3>
            Require all granted
        </IfVersion>
        <IfVersion < 2.3>
            Order Deny,Allow
            Allow from all
        </IfVersion>
    </Directory>

    Alias /rest /usr/share/self-service-password/rest

    <Directory /usr/share/self-service-password/rest>
        AllowOverride None
        <IfVersion >= 2.3>
            Require all denied
        </IfVersion>
        <IfVersion < 2.3>
            Order Deny,Allow
            Deny from all
        </IfVersion>
    </Directory>

    LogLevel warn
    ErrorLog /var/log/apache2/ssp_error.log
    CustomLog /var/log/apache2/ssp_access.log combined
</VirtualHost>
}}}

{{{a2ensite self-service-password}}}

Check you configuration and reload Apache:
{{{
# apachectl configtest
# apachectl reload
}}}

[[Image( SP.png, 850px, nolink))]]

To change configurations - 
{{{
cd /etc/self-service-password
}}}

{{{
vim config.inc. php
}}}
'''Graphics'''

You change the default logo with your own

{{{$logo = "images/ltb-logo.png";}}}

You change the background image with your own

{{{$background_image = "images/unsplash-space.jpeg";}}}

To easily customize CSS

{{{$custom_css = "css/custom.css";}}}

You can hide the footer bar

{{{$display_footer = false;}}}

'''Debug'''

{{{$debug = true;}}}

{{{$smarty_debug = true;}}}

'''Security'''

You need a key phrase if you use ciphered tokens

{{{$keyphrase = "secret";}}}

There is also a protection on login to avoid LDAP injections. Some characters are forbidden, you can change the list of forbidden characters in login

{{{$login_forbidden_chars = "*()&|";}}}

For the reset process via mail token and send sms token, errors are hidden by default, to avoid account disclosure

{{{
$obscure_usernotfound_sendtoken = true;
$obscure_notfound_sendsms = true;
}}}

'''LDAP Connection'''

Server address

Use an LDAP URI to configure the location of your LDAP server

{{{$ldap_url = "ldap://localhost:389";}}}

To use SSL

{{{$ldap_url = "ldaps://localhost";}}}

To use StartTLS, set true in $ldap_starttls

{{{$ldap_starttls = true;}}}

//Note://
//LDAP certificate management in PHP relies on LDAP system libraries. Under Linux, you can configure /etc/ldap.conf (or /etc/ldap/ldap.conf on Debian or Ubuntu, or C:\OpenLDAP\sysconf\ldap.conf for Windows).//

- Provide the certificate from the certificate authority that issued your LDAP server’s certificate
{{{TLS_CACERT /etc/ssl/ca.crt}}}

Or, disable server certificate checking:

{{{TLS_REQCERT allow}}}

If you face issues with non matching TLS versions between SSP and your LDAP server, you should try to modify TLS_CIPHER_SUITE to match the requirements of your server. For example:

{{{TLS_CIPHER_SUITE TLSv1+RSA}}}

You can also define the ldap connection timeout:

{{{$ldap_network_timeout = true;}}}

'''Credentials'''

Configure DN and password in $ldap_bindn and $ldap_bindpw, for example a service account

{{{
$ldap_binddn = "cn=ssp,ou=dsa,dc=example,dc=com";

$ldap_bindpw = "secret";
}}}

To instead use user’s credentials when writing in LDAP directory, replace manager with user in $who_change_password

{{{
$who_change_password = "user";
}}}

'''Search parameters'''

{{{$ldap_base = "dc=learn,dc=ac,dc=lk";}}}

The filter can be set in $ldap_filter
{{{
$ldap_filter = "(&(objectClass=person)(uid={login}))";
}}}

'''Extensions'''

You can use LDAP password modify extended operation wit

{{{
$ldap_use_exop_passwd = true;
}}}

You can also enable LDAP password policy control with

{{{
$ldap_use_ppolicy_control = true;
}}}

Force unlock: will unlock a locked account when password is changed

{{{
$ad_options['force_unlock'] = true;
}}}

Force user to change password at next login:
{{{
$ad_options['force_pwd_change'] = true;
}}}

Allow user to change password if password is expired (this will force the password to be changed as manager):

{{{
$ad_options['change_expired_password'] = true;
}}}

//'''Password Policy'''//

You can use these schemes to hash the password before sending it to LDAP directory:
- SHA, SHA256, SHA384, SHA512
- SSHA, SSHA256, SSHA384, SSHA512
- MD5
- SMD5
- CRYPT
- ARGON2
- clear
- auto

Set one of them in $hash

{{{
$hash = "clear";
}}}

You can configure the crypt salt prefix to choose the algorithm
Optional:
[http://php.net/manual/en/function.crypt.php crypt document]

{{{
$hash_options['crypt_salt_prefix'] = "$6$";
}}}

'''Size'''

Set minimal and maximal length in $pwd_min_length and $pwd_max_length:

{{{
$pwd_min_length = 4;
$pwd_max_length = 8;
}}}

//{{{Set 0 in $pwd_max_length to disable maximal length checking.}}}//

'''Characters'''
You can set the minimal number of lower, upper, digit and special characters:

{{{
$pwd_min_lower = 3;
$pwd_min_upper = 1;
$pwd_min_digit = 1;
$pwd_min_special = 1;
}}}

Special characters are defined with a regular expression, by default:
{{{
$pwd_special_chars = "^a-zA-Z0-9";
}}}

This means special characters are all characters except alphabetical letters and digits.

You can check that these special characters are not at beginning or end of the password:

{{{
$pwd_no_special_at_ends = true;
}}}

You can also disallow characters from being in password, with $pwd_forbidden_chars:

{{{
$pwd_forbidden_chars = "@%";
}}}

//This means that @ and % could not be present in a password.//

You can define how many different class of characters (lower, upper, digit, special) are needed in the password:
{{{
$pwd_complexity = 2;
}}}

'''Pwned Passwords'''

Allows to check if the password was already compromised
[https://haveibeenpwned.com/]
{{{
$use_pwnedpasswords = true;
}}}

'''Re use'''
You can prevent a user from using his old password as a new password if this check is not done by the directory:
{{{
$pwd_no_reuse = true;
}}}

You may also want to check for partial password reuses, ensuring the new password includes at least N distinct new characters:

{{{
$pwd_diff_last_min_chars = 3;
}}}

'''Forbidden words'''

Give a list of forbidden words that the password should not contain
{{{
$pwd_forbidden_words = array("azerty", "qwerty", "password");
}}}

'''Forbidden LDAP fields'''

Give a list of LDAP fields which values should not be present in the password:

{{{
$pwd_forbidden_ldap_fields = array('cn', 'givenName', 'sn', 'mail');
}}}

'''Reset by mail tokens'''

First, the user will enter his login and his mail address. A mail is sent to him.

Then, the user click on the link in the mail, an can set a new password.

//PHP sessions are used to store and retrieve token on server side.//

You can enable or disable this feature with $use_tokens

{{{
$use_tokens = true;
}}}

'''Mail configuration'''

You can also avoid to request the mail to the user, only the login will be asked, and the mail will be read in LDAP:

{{{
$mail_address_use_ldap = true;
}}}

'''Security'''

You can crypt tokens, to protect the session identifier:

{{{
$crypt_tokens = true;
}}}

You should set a token lifetime, so they are deleted if unused. The value is in seconds:

{{{
$token_lifetime = "3600";
}}}

'''Log'''

By default, generated URLs are logged in the default Apache error log. This behavior can be changed, to log in a specific file:

{{{
$reset_request_log = "/var/log/self-service-password";
}}}

'''Reset URL'''

//Optional//

By default, reset URL is computed using server name and port, but these values can be wrong if the application is behind a reverse proxy. In this case you can set yourself the reset URL:

{{{
$reset_url = $_SERVER['HTTP_X_FORWARDED_PROTO'] . "://" . $_SERVER['HTTP_X_FORWARDED_HOST'] . $_SERVER['SCRIPT_NAME'];
}}}

'''Mail Attributes'''

Set the LDAP attributes where user email may be stored:

{{{
$mail_attributes = array( "mail", "gosaMailAlternateAddress", "proxyAddresses" );
}}}

'''Sender Name'''

You can change the default From header and add a signature:

{{{
$mail_from = "admin@learn.ac.lk";
$mail_from_name = "Self Service Password administrator";
$mail_signature = "";
}}}

'''Change password notification'''

Use this option to send a confirmation mail to the user, just after a successful mail change:

{{{
$notify_on_change = true;
}}}

'''PHPMailer'''

{{{
$mail_sendmailpath = '/usr/sbin/sendmail';
$mail_protocol = 'smtp';
$mail_smtp_debug = 0;
$mail_debug_format = 'html';
$mail_smtp_host = 'localhost';
$mail_smtp_auth = false;
$mail_smtp_user = '';
$mail_smtp_pass = '';
$mail_smtp_port = 25;
$mail_smtp_timeout = 30;
$mail_smtp_keepalive = false;
$mail_smtp_secure = 'tls';
$mail_smtp_autotls = true;
$mail_smtp_options = array();
$mail_contenttype = 'text/plain';
$mail_wordwrap = 0;
$mail_charset = 'utf-8';
$mail_priority = 3;
}}}

For more info Regarding PHPmailer: https://github.com/PHPMailer/PHPMailer

'''Ip Configuration'''

{{{ 
vi /etc/netplan/00-installer-config.yaml 
}}}
{{{
# This is the network config written by 'subiquity'
network:
  renderer: networkd
  ethernets:
    enp0s3:
      addresses:
        - 192.248.4.XX/24
      nameservers:
        addresses: [192.248.1.161, 8.8.8.8]
      routes:
        - to: default
          via: 192.248.4.254
  version: 2
}}}              

Other info: https://self-service-password.readthedocs.io/en/stable/presentation.html