This sample demonstrate how the relying party Apache2 module (mod_cspace) can be
used to enable CardSpace authentication on a PHP web application.

IMPORTANT: This guide assumes that you are installing all the components of the
           Identity Solution in the same system, and that you try it out from
           the same system (i.e., we assume that everything is done within the
           localhost).

Requirements:

 o Apache2 Web Server (2.2.X or better)
  o OpenSSL (0.9.8c or better)
 o PHP (5.x)
 o JDK 1.5

Please follow the instructions listed below:

Step 1: Setting up Apache2 Web Server with SSL/TLS and PHP
==========================================================

Please refer to the following web sites for information on installing Apache2
with SSL/TLS enabled:
    o http://httpd.apache.org/docs/2.2/ssl/
    o http://httpd.apache.org/docs/2.2/mod/mod_ssl.html

NOTE: you do not have to generate your own keys. This sample provides you
the keys required. The "keys" directory contains three PEM encoded files;
server.key, server.crt, and cacert.crt which are the server private key, server
certificate (public key), and the certificate authority's certificate,
respectively.

Your configuration of keys in httpd.conf should look like the following

    SSLCertificateFile /usr/local/apache2/conf/keys/server.crt
    SSLCertificateKeyFile /usr/local/apache2/conf/keys/server.key
    SSLCACertificateFile /usr/local/apache2/conf/keys/cacert.crt

Step 2: Running the Token Verifier Service
==========================================

Please follow the Identity Provider installation guide and install the Token
Verifier Service.

Since the Identity Provider by default adds the localhost as a globally trusted
relying party, no configuration is necessary there. (Please see the Identity
Provider documentation for more information)

Step 3: Installing the CardSpace Module and the Sample Web Application
======================================================================

Copy the mod_cspace.so file provided with the distribution to the modules
directory of your apache installation. (usually /usr/lib/apache2/modules/)

Copy the "php-sample" directory to the document root of your Apache2 
installation.

Set the environment variable WSFC_HOME to point to the
"wsf-c" directory inside the package extracted.
(i.e., the package which contained this sample)

Set the environment variable LD_LIBRARY_PATH to include the 
"wsf-c/lib" directory as well.

For instance if your current working directory is where you have extracted the
identity solution package:

% export WSFC_HOME=`pwd`/wsf-c
% export LD_LIBRARY_PATH=${WSFC_HOME}/lib

Step 4: Configuring Apache2 (httpd.conf)
========================================

Following configuration should be done in your httpd.conf file of the apache
installation.

Assuming that you have copied the "php-sample" to the document root of your
Apache2 installation, add the following configuration in "httpd.conf".

LoadModule cspace_module modules/mod_cspace.so

<Location /php-sample/>
    UseCardSpaceAuth
    CardSpaceTVS http://localhost:12080/wsas/services/RelyingPartyService
</Location>

IMPORTANT: 
  * If you copied the sample to a different directory please set the url
    accordingly.

  * Since you have already configured SSL/TLS, using mod_ssl, 
    "SSLCertificateKeyFile" directive should be already in the httpd.conf file.

  * For further information on the configuration derectives that can be used
    with mod_cspace please refer to the module configuration guide.

Step 5: Run Apache2 server and try logging in to the web app
============================================================

Point your browser to the location you have installed the web application. Now
you can try out the sample web application.

IMPORTANT: 
  * You must use IE 7 or any other browser has CardSpace authentication support.

  * You must install the cacert.crt certificate in your certificate
    stores so that the web app will be trusted by the identity-selector.

