INSTALL

Requirements posed upon the user:

In this document,with user, we mean *you*, the person that downloads,
configures and installs Confusa on a server.

You should have
- some experience with Apache-configuration
- basic knowledge about cryptography (i.e. what a certificate is, and
  how it's used) but not much more is required.
- some, but not excessive, knowledge about PHP and bash-scripting, as
  this will help both *you* and *us* to track down bugs
- an open and positive mind (for a more pleasent interaction with the
  world as a whole). This has nothing to do with Confusa

To install Confusa

=== Requirements: ===
 - git (for latest checkout of confusa source code). *not* required, but handy
 - svn (for latest simplesamlphp checkout). *not* required, but handy
 - Apache2
 - PHP5
 - PEAR with MDB2.MySQL
 - Smarty (the PHP template engine)

=== Install process ===

1) Webserver (apache)

     apache2

2) Database (MySQL)
     mysql-server-5.0
     mysql-client-5.0 (you need this for bootstrapping the tables)

3) PHP

     libapache2-php5
     php5-mysql
     PEAR::MDB2_mysql_driver
     
3 b) When using online, you will also need the mcrypt and curl libraries:

     php5-mcrypt
     php5-curl

4) Configure Apache to use SSL, use the following lines in your 
   apache2/sites-enabled/appropriate.config.file and php5-openssl

# Redirect http to https
<VirtualHost your.host.org:80>
        Servername your.server.org
        Redirect permanent / https://your.host.org
</VirtualHost>

<VirtualHost your.host.org:443>
        Servername your.server.org
        SSLEngine On
        SSLProtocol All
        SSLCipherSuite ALL:!ADH:!EXPORT56:!EXPORT40:RC4+RSA:!SSLv2:+HIGH:+MEDIUM:+LOW:+EXP
        SSLVerifyClient optional_no_ca
        SSLVerifyDepth 10
        SSLOptions +StdEnvVars +ExportCertData
        SSLCertificateFile /etc/apache2/ssl/slcstest.crt
        SSLCertificateKeyFile /etc/apache2/ssl/slcstest.key

	...
</VirtualHost>

Note that ServerName can be the same as the host-name in VirtualHost.
Make sure you create the folder /etc/apache2/ssl/ as the create-ca.sh
will put hostkeys there for you (a self-signed certificate, you should
get a properly signed certificate for any production-grade instances of
Confusa!).

Alternatively, if you don't want to use this script, put the
key/certificate in the folder of your choice and configure the 2 lines
in the given config-file.

Finally, this is a *sample* configuration. If you know your way around
an Apache configuration, this should be more of a guideline than
anything else. 

5) simpleSAMLphp
   confusa uses simpleSAMLphp to handle AuthN, and thus, you should
   configure simpleSAMLphp before venturing on.

   http://rnd.feide.no contains excellent guides on how to configure
   simpelSAMLphp, and is required reading.

   IN saml20-sp-hosted.php, let the __DYNAMIC:1-entry from template
   stay, but add the custom Authentication Processing Filters for Confusa:

   'authproc' => array(
        60 => 'core:ConfusaAttributeMap',
        61 => 'core:CountryMap',
        62 => 'core:CharacterMap',
	63 => 'core:NRENMap',
    ),
	ForceAuthn	 => true

   You will have to either copy or symlink these into
	simplesamlphp/modules/core/lib/Auth/
   like this:
	ln -s /var/www/confusa/include/ConfusaAttributeMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/ConfusaAttributeMap.php
	ln -s /var/www/confusa/include/CountryMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/CountryMap.php
	ln -s /var/www/confusa/include/CharacterMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/CharacterMap.php
	ln -s /var/www/confusa/include/NRENMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/NRENMap.php

6) Install and configure Confusa:

a) Put Confusa in a directory, say /var/www/confusa/

b) Configure Apache with something along the following line:

             Alias /confusa "/var/www/confusa/www/"
	     Alias /simplesaml "/var/www/simplesamlphp/www/"
             <Directory /var/www/confusa/www>
                        Options Indexes MultiViews
                        AllowOverride None
                        Order allow,deny
                        Allow from all
             </Directory>

   then reload the config: /etc/init.d/apache2 reload (or httpd (or
   other relevant name for apache - consult your distro's documentation)
   and reaload.

   This will enable your host to show the www directory of the
   confusa-folder.

c) Configure the confusa_config.php file (copy the
   confusa_config_template.php and modify with values that makes sense
   to you - the template explaines the attributes).
   
d) Run the create_database.sh script in confusa/init folder
   This will create the database, the user and the tables. it will use
   the confusa_config.php file, so make sure that this is configured
   properly before you run this script.

e) Add a cron-job of the following type:
   */5 *   * * * /var/www/confusa/programs/clean_db.sh

   This will run the clean_db script every 5 minutes and keep the
   database nice and tidy.

f) Add a cron-job that takes backup of the database. The most critical
   part is the certificate hash part.
   A sample script lies in confusa/programs. Note that this is a simple
   mysqldump script that dumps the database specified in confusa_config

7) If you want NREN-admins to be able to customize the appearance of Confusa,
you have to give the apache user write permissions to the "custom" folders in
www/css and www/graphics. The apache user is often called 'www-data', sometimes
also 'apache' or something else.
If you are unsure about the user-name and have apache running, try to find it
out by executing

ps aux | grep apache | awk '{print $1}'
or
ps aux | grep httpd | awk '{print $1}'

If your apache username is www-data, execute

chown -R www-data /usr/share/confusa/www/css/custom
chown -R www-data /usr/share/confusa/www/graphics/custom
chmod -R 0755 /usr/share/confusa/www/css/custom
chmod -R 0755 /usr/share/confusa/www/graphics/custom

8) Test and verify that the system is operational before you allow
   public access.

9*) Enable OAuth authorization for third party applications. OAuth has the
advantage that Confusa-based non-browser applications won't need to maintain cookies any more
and that it protects against replay attacks. Simplesamlphp supports OAuth in more recent versions.

In order to enable OAuth in Confusa, it must first be enabled in simplesamlphp. chdir to the OAuth
module directory (<simplesaml-dir>/modules/oauth/ and create a file named enable there, e.g. by executing "touch enable".

OAuth uses the SAML2 AuthN module for the authentication phase. Hence, make sure that that module is enabled
as well (see <simplesaml-dir>/modules/saml2) and add a metadata-entry for it in <simplesaml-dir>/metadata/saml2-sp.hosted.php.
You can just copy the default one, yielding for instance:

'https://slcs.example.com/simplesaml/module.php/saml2/sp/metadata.php?source=saml2' => array(
  'host'  => '__DEFAULT__',
  'authproc' => array(
    50 => 'core:NRENMap',
    60 => 'core:ConfusaAttributeMap',
    61 => 'core:CountryMap'
  ),
  'ForceAuthn' => true
)

Until IdP discovery will be implemented in simplesamlphp's SAML2 module, the IdP must be hardcoded in the configuration. E.g. add/edit
the following line to <simplesamlphp-dir>/config/authsources.php:

'saml2' => array(
            'saml2:SP',
            'idp' => 'https://exampleidp.example.com',
),

Bear in mind that the IdP with which you wish to establish the above trust relationship needs to accept the metadata of the
saml2 module on your side, not only your standard metadata. And OAuth may oblige you to create a directory /tmp/oauth with write
permissions for the webserver-process, which it will use as a token store. 


*) optional