New Installation

This chapter explains how to perform a new installation of Portal Server.

Start by checking “System Requirements” and the "Pre-Installation tasks".

When the webserver with PHP 8 is up and running with <INSTALL_ROOT>/public as root, move or copy the <INSTALL_ROOT>/check.php file to <INSTALL_ROOT>/public/check.php.

From your web browser, access https://yoursite/check.php and inspect the results and see if to see if there are obvious missing requirements.

When done either delete or move the script file back to <INSTALL_ROOT>/check.php to prevent direct access or execution by unauthorized users.

Configuration

Next step is to configure the Portal Server by creating the <INSTALL_ROOT>/config/config.php.

Copy <INSTALL_ROOT>/config/config.php.sample to <INSTALL_ROOT>/config/config.php and open it in your favorite editor.

Main Portal Settings

The $portal['title'] (string), $portal['subtitle'] (string) and $portal['logo'] (string: system path to file) are used in the header of the user- and admin-portals as well as in the login box.

The $portal['debug'] (boolean) setting indicates if additional debugging info may be shown. The $portal['debug_error_reporting'] and $portal['debug_ini_set_display_errors'] settings refer to values per standard PHP debugging levels.

Please refer to PHP documentation https://www.php.net/manual/en/function.error-reporting.php and https://www.php.net/manual/en/errorfunc.configuration.php#ini.display-errors for more details.

Enabling debugging can provide additional information to track down issues but is recomended to disable for regular use. Due to unpredictable behaviour it may break functionality of the portal. Inspecting error logs is a better starting point to identify issues.

The $portal['https'] setting allows for telling PHP that the portal is served over https. By default it is attempted to detect if the application is served over https but PHP cannot always correctly determine this due to webservers not setting values per the standard. This setting will make it explicit.

// BEGIN PORTAL
$portal['title']                          = '';
$portal['subtitle']                       = '';
$portal['logo']                           = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'monkeyproof.png';

$portal['debug']                          = false;
$portal['debug_error_reporting']          = 'E_ERROR';
$portal['debug_ini_set_display_errors']   = '1';

//true if serving over https, false if not, null to ignore this setting. 
//(This is an "override" if $_SERVER['HTTPS'] is not available on server or contains a value if not serving over https).
$portal['https']                          = null; 
// END PORTAL

Logging

The $logging['dir'] (string) contains the path to the top level logging directory. The default value included writes logs into the installation directory is not preferred for production environments. You can set any location with write permission for the php/webserver user here.

The $logging['log_rotate_enabled'] (boolean) setting enables or disables log rotation. When enabled log files are rotated on a daily basis (when there is activity). The $logging['log_rotate_keep'][*] (number) settings allow for setting the number of logs to keep for each log type. To keep rotated logs forever set to 0. Note that traffic logs are intended for debugging issues and can grow rapidly.

// BEGIN LOGGING
$logging['dir']                           = dirname(__DIR__) . DIRECTORY_SEPARATOR . 'log' . DIRECTORY_SEPARATOR;
// enable daily log rotate
$logging['log_rotate_enabled']            = true;
//number of rotated log files to keep (i.e. the last x days of activity on the portal)
//0 means all are kept
$logging['log_rotate_keep']['access']     = 0; 
$logging['log_rotate_keep']['error']      = 30; 
$logging['log_rotate_keep']['traffic']    = 5; 
// END LOGGING

Authorization

The setting $auth['disabled'] (boolean) allows for disabling authentication. When disabled the User Portal https://yoursite/ and the Admin Portal https://yoursite/admin_portal/ are accessible without user authentication.

It is a good idea to test the installation with authentication disabled. Once the Portal Server is displaying its content as expected, start configuring the LDAP authentication/authorization.

When authentication is enabled, $auth['user_password'] (boolean) must be set to true, and $auth['type'] (string) must be set to 'ldap'. The $auth['debug'] (boolean) should be set to false in production but setting it to true may help during configuration. Also inspect the access and error logs when running into issues during configuration.

// BEGIN AUTH
$auth['disabled']                         = false;
$auth['user_password']                    = true;
$auth['type']                             = 'ldap';
$auth['debug']                            = false;
// END AUTH

LDAP

The Portal Server can be configured to authenticate against Microsoft Active Directory (Azure AD is something different although it may work with the appropriate Azure AD plugin). LDAP integration is enabled by setting the $auth['type'] (boolean) to true.

The $ldapconfig['start_tls'] setting enables TLS for secure communication with the LDAP server.

The connection with the LDAP server is set up using the standard PHP LDAP plugin and can further be configured in $ldapconfig['ldap_options'] (array) by means of an array of the LDAP_OPT_* settings. More information can be found here https://www.php.net/manual/en/ldap.constants.php. Noteworthy is the 'LDAP_OPT_X_TLS_CACERTFILE' option which contains the path to the Certificate Authority Certificat file such that the certificate of the LDAP server can ve validated.

The $ldapconfig['host'] (string) and $ldapconfig['port'] (string) setting indicate on which address and port the LDAP server can be contacted.

The $ldapconfig['domain'] (string) is your microsoft domain name. The $ldapconfig['basedn'] (string) is the top level from where searches are being doen in the LDAP server.

The $ldapconfig['usersdn'] (string) is the distinguished name where searches will be exected for users (note that we reuse/concatenate the $ldapconfig['usersdn'] setting). The $ldapconfig['user_name_attribute'] (string) is the user attribute containing the name used for authentication (for MS AD this is 'sAMAccountName'). The $ldapconfig['user_photo_attribute'] (string) and $ldapconfig['user_displayname_attribute'] (string) contain the attributes containing the user display name and photo respectively.

The $ldapconfig['groupsdn'] (string) is the distinguished name where searches for security groups will be executed. The $ldapconfig['gropup_name_attribute'] (string) is the attribute being searched for to identify user membership (for MS AD this is 'sAMAccountName').

The LDAP integration oly uses user credentials for authentication. All other communication for e.g. retrieval of user details and querying group membership happens with a read-only LDAP user with username $ldapconfig['readonly_user'] (string) and password $ldapconfig['readonly_pw'] (string).

Access to the user portal requires membership of any of the groups listed in $ldapconfig['portal_user_groups'] (array of strings). Use empty array [] to not require portal user group membership (authentication is then still required). Access to the Admin Portal requires membership of any of the groups listed in $ldapconfig['admin_groups'] (array of strings).

// BEGIN LDAP
$ldapconfig['start_tls']                  = true;

// LDAP Options - see: https://www.php.net/manual/en/ldap.constants.php
$ldapconfig['ldap_options']               = array(
    'LDAP_OPT_X_TLS_CACERTFILE'           => 'path_to_cacert.crt',
    // 'LDAP_OPT_X_TLS_CACERTDIR'            => '',
    // 'LDAP_OPT_X_TLS_CERTFILE'             => '',
    // 'LDAP_OPT_X_TLS_KEYFILE'              => '',
    'LDAP_OPT_X_TLS_REQUIRE_CERT'         => 'LDAP_OPT_X_TLS_DEMAND',
    'LDAP_OPT_PROTOCOL_VERSION'           => 3,
    'LDAP_OPT_REFERRALS'                  => 0,
    'LDAP_OPT_NETWORK_TIMEOUT'            => 10,
);

$ldapconfig['host']                       = 'your.ldap.server';
$ldapconfig['port']                       = '389';

$ldapconfig['domain']                     = 'your_domain';
$ldapconfig['basedn']                     = 'dc=your,dc=domain';

$ldapconfig['usersdn']                    = 'cn=Users,' . $ldapconfig['basedn'];
$ldapconfig['user_name_attribute']        = 'sAMAccountName';
$ldapconfig['user_photo_attribute']       = 'thumbnailphoto';
$ldapconfig['user_displayname_attribute'] = 'displayname';

$ldapconfig['groupsdn']                   = 'cn=Groups,' . $ldapconfig['basedn'];
$ldapconfig['group_name_attribute']       = 'sAMAccountName';

// saMAccountName and password of (read-only) LDAP query user
$ldapconfig['readonly_user']              = '';
$ldapconfig['readonly_pw']                = '';	

$ldapconfig['portal_user_groups']         = ['your_portal_users_group']; // Must be an array. Use empty array [] to not require portal user group membership.
$ldapconfig['admin_groups']               = ['your_admin_group'];        // Must be an array
// END LDAP

Landing pages

When the Portal Server has been configured appropriately, the following pages are available: