AAIportal - Installation Guide

Table of Contents

Pre-Installation Tasks

Required deployment environment

Getting the distribution

The latest distribution is available from SourceForge AAIportal download.

Installation

Unpack the distribution

Unpack the distribution aai-portal-<version>.tar.gz in your installation directory (i.e. INSTALL_DIR is /opt or /usr/local).
root# mv aai-portal-<version>.tar.gz <INSTALL_DIR>
root# cd <INSTALL_DIR>
root# gunzip -c aai-portal-<version>.tar.gz | tar xvf -
This should create an installation with the following installation layout. In the sequel $AAI_PORTAL_ROOT denotes the directory $INSTALL_DIR/aai-portal-<version>
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

The current version of AAIportal can be upgraded from previous versions 1.1.X, 1.2.X, and 1.3.X of AAIportal. If you have already an old AAIportal installation, you may choose to keep the existing resources, users and suscriptions stored in the MySQL database.

Note: An upgrade is only possible if you are running a MySQL database version 4.1 or never

Therefore, some database scripts are provided to update your existing database (i.e. PORTAL_DB) to the new version.

Upgrade from AAIportal version 1.3.X to 1.4.X

If you are using an old AAIportal version 1.3.X, you can simply upgrade your database, without loosing any data, for version 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

If you are using an AAIportal version 1.0.X, you can just upgrade it to version 1.3.X

Note: Some adapters configuration may be broken after the upgrade (in particular WebCT CE and Vista adapter configurations). Please review the resource adapter parameters after the upgrade process.

  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

If you are still using an old AAIportal version 0.9.X, you must first upgrade it to version 1.0.1

  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

A new AAIportal installation requires a running MySQL database instance.

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
We recommend to create a dedicated database user which the AAIportal web application will use to access the database. Choose a user name, i.e. aaiportal, and create the user. If you use a GRANT statement similar to that shown below, the new database user is also restricted to submit data manipulation statements only.
root# mysql -u root -p 
Enter Password: root-password
  
mysql> GRANT DELETE, INSERT, SELECT, UPDATE
        ON aaiportal.*
        TO aaiportal@localhost  IDENTIFIED BY 'your-password';
Finally, create and initialize the database schema for the AAIportal database. Switch to the directory db in the distribution and load the SQL file aai-portal-db.sql into the prepared database.
root# mysql -u root -p --database=aaiportal < aai-portal-db.sql
Enter Password: root-password
root#

Configure PHP

AAIportal is implemented in PHP. It requires at least PHP 4.3.2 because it relies on the fsockopen() metho which understands the SSL URL schema, a feature, which was introduced in PHP 4.3.2. In addition, the following modules have to be compiled into PHP (we give a short canonical name for the module and a reason, why this module is required)

Required PHP Modules:

AAIportal also makes use of the following optional PHP features:

There are different possible places to configure these features:
  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

Depending on your Installation Layout, the apache configuration file has to be modified.

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

There is only one configuration file in the AAIportal distribution which has to be modified according to your local settings.

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

When the database is initialized some default users are created in the AAIportal database:
  1. portaladmin is the default Portal Administrator.
  2. resourceadmin is a sample Resource Administrator.
  3. subscriptionadmin is a sample Subscription Administrator.
The initial password for both users is changeme. It is highly recommended to change these initial passwords !

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
Proceed likewise to change the initial password for the user resourceadmin and for the user subscriptionadmin.

Launching the Portal

You can now launch the AAIportal start page at the URL https://aaiportal.example.ch/aai-portal/.

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