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.0 or better)
 o libxml2 (2.6.20 or better)
 o libxmlsec1 (1.2.0 or better)
 o PHP (5.x)

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: Installing the CardSpace Module and the Sample Web Application
======================================================================

If you built mod_cspace using the source distribution, copy libmod_cspace.so
file inside the .libs directory to the modules directory of your apache
installation as mod_cspace.so. (/usr/lib/apache2/modules/ is the modules 
directory of a typical apache2 installation)

In addition, you may install the module using the packages provided (.deb and
.rpm), if you happen to be on one of the supported platforms.

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

Step 3: 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 4: Run Apache2 server and try to login ot the web app
==========================================================

Point your browser to the location you have installed the web application. If
you followed this guide properly, it will be "https://localhost/php-sample"

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.

