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.

NOTE: Keep the trailing DIRECTORY_SEPARATOR intact when editing paths.

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 portal currently supports four authentication modes that can be selected by setting $auth['type']. The four modes are:

1. 'anonymous': Anonymous mode allows users to use the portal and applications without authentication. When a session expires it cannot be restored and data may be lost.

NOTE: Anonymous mode should only be used for testing purposes during installation. It should NOT be used in production.

2. 'managed': Basic user management included in the portal. See Managed.
3. 'ldap': Authentication against Microsoft Active Directory. See LDAP.
4. 'azure_ad': Authentication against Azure Active Directory. See Azure AD.

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['type']                             = 'managed';
$auth['debug']                            = false;
// END AUTH

Managed

The managed mode provides basic stand-alone user management in the admin portal. Users can be created, added to groups in the admin portal and can be invited via email.

In order to send the invitation emails, PHPMailer must be configured in mail_config.php.

use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer;

$mail->isSMTP();
$mail->SMTPDebug = 0;
$mail->Debugoutput = 'html';
$mail->Host = "smtp.example.com";
$mail->Port = 25;
$mail->SMTPAuth = false;
$mail->SMTPAutoTLS = false;
$mail->SMTPSecure = false;
$mail->setFrom('simian-suite@example.com', 'Simian Suite');

In order to create the administrator account, copy <INSTALL_ROOT>/src/auth/managed/reset_admin_password.php to <INSTALL_ROOT>/public/. Then, in the browser navigate to https://yoursite/reset_admin_password.php. After specifying the password, it will be possible to log in as user admin.

Note: Do not forget to remove the file from the public folder afterwards!

LDAP

The Portal Server can be configured to authenticate against Microsoft Active Directory. LDAP integration is enabled by setting the $auth['type'] to 'ldap'.

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 done 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).

Direct subgroups of $ldapconfig['portal_parent_groups'] (array of strings) will be selectable in applications configurations in the admin portal. Leave unspecified to show all groups. 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['portal_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_parent_groups']       = ['CN=your_parent_group,CN=Users,DC=example,DC=com'];
$ldapconfig['portal_user_groups']         = ['CN=group_name,CN=Groups,DC=example,DC=com'];
$ldapconfig['portal_admin_groups']        = ['CN=group_name,CN=Groups,DC=example,DC=com'];
// END LDAP

Azure AD

The Azure AD authorization mode allows users to authenticate using their Microsoft Azure AD account. When the user is already signed in, the authorization happens without user interaction. After successful authorization, the user can sign out of (or stay signed in on) the portal independently from the Microsoft Azure AD account.

The Portal Server can be configured to authenticate against Azure Active Directory. Azure integration is enabled by setting the $auth['type'] to 'azure_ad'.

The $azure_ad_config['ad_tenant'] (string) is the Azure Active Directory Tenant ID. With Multitenant apps you can use "common" as Tenant ID, but using specific endpoint is recommended when possible.

The $azure_ad_config['client_id'] (string) is the client application ID provided by Azure.

The $azure_ad_config['client_secret'] (string) is the Client Secret provided by Azure. Remember that this expires someday unless you haven't set it not to do so.

The $azure_ad_config['portal_admin_groups'] (array of strings) are the user group IDs that will be granted access to the admin portal.

The $azure_ad_config['portal_parent_groups'] (array of strings) are user group IDs of which direct member groups will be listed for selection in the admin portal to grant users access to individual applications.

// Azure AD Options
$azure_ad_config['ad_tenant']               = "ea4656af-8f49-46cd-b355-fef4d8735127";
$azure_ad_config['client_id']               = "54d7c310-9afa-4e9a-9717-d934f64f4161";
$azure_ad_config['client_secret']           = "PmcZIvH0kxA8W9IECyymu6ZzjEy+MbAvXqDHFe3G";
$azure_ad_config['portal_admin_groups']     = ["f2884a1c-62e8-425c-b32a-25881f375823"];
$azure_ad_config['portal_parent_groups']    = ["ea2d7058-a486-46c5-bc4b-7c7fc14db767"];
// END Azure AD

Landing pages

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