AAIportal - Installation Guide

Table of Contents

• Pre-Installation Tasks
  • Required deployment environment
  • Getting the distribution
• Installation
  • Unpack the distribution
  • Upgade an existing database
  • Create a new database
  • Configure PHP
  • Configure the web server
  • Configure AAIportal
• Post-Installation Tasks
• Changing default passwords
• Launching the Portal

Pre-Installation Tasks

Required deployment environment

• PHP 4.3 (or better) or PHP 5.1 (or better) with SSL support
• MySQL 4.1 (or better) or MySQL 5.0
• Apache 1.3.x/2.0/2.2 for Unix or IIS 6 for Windows
• SWITCHaai Shibboleth Service Provider (SWITCHaai Deployment Guides)
• mod_php for Apache or PHP ISAPI for IIS

Getting the distribution

Installation

Unpack the distribution

root# mv aai-portal-<version>.tar.gz <INSTALL_DIR>
root# cd <INSTALL_DIR>
root# gunzip -c aai-portal-<version>.tar.gz | tar xvf -

aai-portal-<version>
\-README                This file
  CHANGE-LOG            The change log 
  VERSION               Version information
  GPL                   GNU General Public License 
  +--config             Configuration files
  +--web                The public web application files (PHP)
  |  +--user            The user part of the portal
  |  +--admin           The administrator part of the portal
  |  +--adapters        Resource adapters
  |  \--lookandfeel     Look & feel specific libraries and components
  +--include            Libraries need by the web application
  +--i18n               Localized messages used in the web portals               
  |  +--en              English messages
  |  +--de              German messages 
  |  +--it              Italian messages
  |  \--fr              French messages
  +--db                 Database SQL creation and update scripts
  +--tools              Admin PHP scripts
  \--doc                Documentation

Upgrade an existing database

Upgrade from AAIportal version 1.3.X to 1.4.X

1. Go in the new 1.4.X db directory and apply the SQL update script to your existing 1.3.X database:

   root# cd aai-portal-1.4.X/db
   root# mysql -u root -p --database=PORTAL_DB < aai-portal-db-update-1.3.X.sql
   Enter Password: ***********
   

   Where PORTAL_DB is the name of your current 1.3.X database.

Upgrade from AAIportal version 1.0.X to 1.3.X

1. Copy the scripts aai-portal-db-update-1.0.X.sql and update_user_attributes.php in your existing AAIportal 1.0.X db directory:

   root# cd aai-portal-1.3.X/db
   root# cp aai-portal-db-update-1.0.X.sql update_user_attributes.php \
            ../aai-portal-1.0.1/db
   

2. Go to the 1.0.1 db directory and apply the SQL update script to your existing database:

   root# cd ../aai-portal-1.0.1/db
   root# mysql -u root -p --database=PORTAL_DB < aai-portal-db-update-1.0.X.sql
   Enter Password: ************
   

   Where PORTAL_DB is the name of your current 1.0.X database.
3. And run the PHP script to update your existing database content:

   root# php update_user_attributes.php
   ...
   

Upgrade from AAIportal version 0.9.X to 1.0.X

1. Copy the scripts aai-portal-db-update-0.9.X.sql and update_resource_keys.php in your old existing AAIportal db directory:

   root# cd aai-portal-1.0.1/db
   root# cp aai-portal-db-update-0.9.X.sql update_resource_keys.php \
            ../aai-portal-<old_version>/db
   

2. Go to your old db directory and apply the SQL update script to your existing database:

   root# cd ../aai-portal-<old_version>/db
   root# mysql -u root -p --database=PORTAL_DB < aai-portal-db-update-0.9.X.sql
   Enter Password: ************
   

3. Run the PHP script to update your existing database content:

   root# php update_resource_keys.php
   ...
   

Create a new database

We recommend to create a dedicated database for the AAIportal. Choose an appropriate database name , i.e. aaiportal, and create the database.

root# mysqladmin -u root -p create aaiportal
Enter Password: root-password

root# mysql -u root -p 
Enter Password: root-password
  
mysql> GRANT DELETE, INSERT, SELECT, UPDATE
        ON aaiportal.*
        TO aaiportal@localhost  IDENTIFIED BY 'your-password';

root# mysql -u root -p --database=aaiportal < aai-portal-db.sql
Enter Password: root-password
root#

Configure PHP

Required PHP Modules:

• curl - for accessing VITELS resource. This module allows WebService to be used.
• mhash - for generating checksums (MD5 or SHA-1 based).
• mysql - for accessing the AAIportal database
• openssl - for accessing resources protected by SSL. This module is only necessary if the Resource Adapter for WebCT courses is installed and used.
• session - session handling

AAIportal also makes use of the following optional PHP features:

• Open Short Tag - PHP code in the AAIportal starts with the short tag < instead of the long tag <?php
• No Global Variables - HTTP request parameters and other environment parameters are expected to be available in global arrays rather than indiviual global parameters
• Cookie based PHP Session Support - AAIportal's session handling relies on PHP sessions with cookies.
• PHP Include Path - AAIportal's include files must be on the PHP include path.

1. httpd.conf - Apache Configuration File

   Required PHP features can also be configured in the main Apache configuration file httpd.conf.

   # Allow the <? tag.  Otherwise, only <?php and <script> tags 
   # are recognized.
   php_flag  short_open_tag  On
   
   # You should do your best to write your scripts so that they do not require
   # register_globals to be on;  Using form variables as globals can easily lead
   # to possible security problems, if the code is not very well thought of.
   php_flag  register_globals Off
   
   # Session uses cookies 
   php_value session.use_cookies  1
   
   # PHP include path (Unix) 
   php_value  include_path "/aai-portal-install-dir:/aai-portal-install-dir/web"
   # PHP inlcude path (Windows)
   #php_value  include_path "C:\aai-portal-install-dir;C:\aai-portal-install-dir\web"
   

   If the required PHP configuration values for the AAIportal differ from PHP configuration values for other web applications on your server you can configure PHP specifically for the AAIportal installation directory. Here is an excerpt from the httpd.conf file in which PHP configuration values are set within an Apache <Directory> directive.

   <Directory "/your/install/dir/aai-portal<version>/web">
     # Allow the <? tag.  Otherwise, only <?php and <script> tags 
     # are recognized.
     php_flag  short_open_tag  On
   
     # You should do your best to write your scripts so that they do not require
     # register_globals to be on;  Using form variables as globals can easily lead
     # to possible security problems, if the code is not very well thought of.
     php_flag  register_globals Off
   
     # Session uses cookies 
     php_value session.use_cookies  1
   
     # PHP include path (Unix) 
     php_value  include_path "/aai-portal-install-dir:/aai-portal-install-dir/web"
     # PHP inlcude path (Windows) 
     #php_value  include_path "C:\aai-portal-install-dir;C:\aai-portal-install-dir\web"
   
   </Directory>
   

2. .htaccess - Per-directory configuration

   The third option is to configure PHP per directory. In this case, PHP configuration values have to be written to the respective .htaccess file in the AAIportal installation directory (or any sub directory thereof, if configuration parameters in sub-directories differ from those in the parent directory).

   First, in Apache configuration file httpd.conf, we have to make sure that we can override PHP configuration parameters per directory:

   # configure the directory with the AAIportal web application 
   #
   <Directory "/your/install/dir/aai-portal<version>/web">
           #
           # IMPORTANT ! Make sure we can override PHP configuration
           # and Shibboleth authentication settings in .htaccess files
           # in the web directory
           #
           AllowOverride AuthConfig Options 
   </Directory>
   

   Second, we can create (or edit the existing) .htaccess file in the directory /your/install/dir/aai-portal<version>/web and set PHP configuration parameters as follows:

   # sample .htaccess file in the AAIportal web directory
   #
   
   # set the PHP include path (the directories 'include' and
   # 'lookandfeel' should be on this path)
   #
   php_value include_path ".:.." # Unix path
   #php_value include_path ".;.." # Windows path
   
   # other PHP configuration values 
   #
   php_flag  register_globals Off
   php_flag  short_open_tag   On 
   php_value session.use_cookies  1
   

Configure Apache

If the directory $AAI_PORTAL_ROOT/web is not accessible by the web server or if you want to assign it an Alias, then you have to edit the respective configuration sections in the Apache configuration file httpd.conf.

In the following example we define an Alias aai-portal under which we want the AAIportal to be accessible.

The Apache configuration file is often found in /etc/apache/httpd.conf but your mileage may vary.

# define an Alias for the AAIportal
#
Alias /aai-portal  "/your/install/dir/aai-portal-<version>/web"

# configure the directory with the AAIportal web application 
#
<Directory "/your/install/dir/aai-portal-<version>/web">
        DirectoryIndex index.php
        #
        # IMPORTANT ! Make sure we can override PHP configuration
        # and Shibboleth authentication settings in .htaccess files
        # in the web directory
        #
        AllowOverride All
        Order allow,deny
        Allow from all
</Directory>

Configure AAIportal

Edit the file config/aai-portal.config and modify the following configuration parameters:

<?php

/* ******************************************************** */
/*                 AAIportal Version                        */ 
/* ******************************************************** */
/** 
 * The AAIportal version 
 */ 
define('AAI_PORTAL_VERSION', '1.4.2');

/* ******************************************************** */
/*                 Support and Helpdesk                     */ 
/* ******************************************************** */
/**
 * The AAIportal support email displayed in error message.
 */
define('SUPPORT_EMAIL', 'support@example.ch');

/**
 * The AAIportal support URL displayed in error message.
 */
define('SUPPORT_URL', 'http://www.example.ch/support');


/* ******************************************************** */
/*                 Database Connection                      */ 
/* ******************************************************** */
/**
 * The hostname or IP address of the MySQL server.
 */
//define('MYSQL_HOST', 'localhost');
define('MYSQL_HOST', 'mysql.example.ch');

/**
 * The name of the database  
 */
define('MYSQL_BASE', 'aaiportal_db');

/**
 * The MySQL username used to connect to the AAIportal database.
 */
define('MYSQL_USER', 'aaiportal');

/**
 * The MySQL user password.
 */
define('MYSQL_PASS', 'aaiportal_password');


/* ******************************************************** */
/*                     URLs and Paths                       */
/* ******************************************************** */
/** The portal base URL. Please enter an absolute URL. This URL is used
 *  in HTTP redirects which is required to send absolute URLs to the 
 *  browser  
 */
define('PORTAL_BASE_URL', 'https://aaiportal.example.ch/aai-portal');

/** The URL to the login script for a portal user */
define('USER_PORTAL_LOGIN_URL', PORTAL_BASE_URL . '/user/index.php');

/** The URL to the login script for a admin user */
define('ADMIN_PORTAL_LOGIN_URL', PORTAL_BASE_URL . '/admin/index.php');

/* ******************************************************** */
/*                         Logging                          */ 
/* ******************************************************** */
/** 
 * The log filename should be writable by the webserver's user.
 *   LOGGER_FILENAME := (filename|syslog) 
 */
// define('LOGGER_FILENAME', '/var/log/aai-portal.log');
define('LOGGER_FILENAME', 'syslog');

/** 
 * Set the log level (integer):
 *   0 := DEBUG
 *   1 := NOTICE
 *   2 := INFO
 *   3 := WARNING
 *   4 := ERROR,
 *   5 := CRITICAL 
 */
define('LOGGER_LOGLEVEL', 2 );


/* ******************************************************** */
/*                 Events Viewer                            */
/* ******************************************************** */
/**
 * You can disable the Events for performance reason (boolean)
 * If disable, then the events are not stored in the DB anymore.
 */
define('ENABLE_EVENTS', true);


/* ******************************************************** */
/*                 Email and Notification                   */ 
/* ******************************************************** */
/**
 * The mail server used to send emails (string):
 *   smtp.example.ch : uses that SMTP server
 *   mail : constant for the local MTA (sendmail, ...)
 */ 
//define('AAI_PORTAL_SMTP', 'smtp.example.ch');
define('AAI_PORTAL_SMTP', 'mail');

/**
 * Set to true if you want to enable automatic notification (boolean).
 * Otherwise set to false.
 */
define('ENABLE_NOTIFICATION', true);

/* Set to true if you want to use a email to sms gateway (boolean) */
define('USE_SMSGATEWAY', false);

/**
 * Email address of sms gateway, where  gets replaced
 * by the corresponding mobile number (string)
 */
define('SMSGATEWAY', "<mobile>@sms.switch.ch");

/** Maximum characters per sms (integer) */
define('MAX_SMS_LENGTH', 120);


/* ******************************************************** */
/*                      Languages                           */
/* ******************************************************** */

$I18N_AVAILABLE_LOCALES = array(
   "de" => "Deutsch",
   "en" => "English",
   "fr" => "Français",
   "it" => "Italiano",
);

?>

Post-Installation Tasks

Changing default passwords

1. portaladmin is the default Portal Administrator.
2. resourceadmin is a sample Resource Administrator.
3. subscriptionadmin is a sample Subscription Administrator.

To change the initial password for the user portaladmin

1. point your browser to the URL https://aaiportal.example.ch/aai-portal/admin.php
2. login as portaladmin (initial password is changeme)
3. select the menu item Change Password and set a new password

Launching the Portal

This will display a web page on which you can select whether you want to login as User or as Administrator.