Thursday, July 10, 2008

Building & Deploying mod_cspace on Windows

mod_cpace is an Apache HTTPD module for processing Information Card based logins, which can be used with any Web application that is hosted with Apache HTTPD.

This has a binary distribution for Ubuntu, but NOT for Windows.

This post explains all what you need to know how to build mod_cpace for Windows from the source.

I am using Visual Studio 2008 Express Edition to do the build and the IDE can be freely downloaded from here.

Also, make sure you have installed .NET Framework 3.5 in your machine as well as the IE 7.

First we need to download the latest code from the SVN repository. You may use TortoiseSVN client for this, which is freely available from here.

Downloal all the code from https://svn.wso2.org/repos/wso2/trunk/solutions/identity/modules/mod-cspace to your local repository [LOCAL_REPO].

Now share the folder [LOCAL_REPO]\build\win32\vc\lib and map the network drive 'W' to this shared folder.

Solution file [mod_cspace.sln] is available at [LOCAL_REPO]\build\win32\vc\apache2 and click the file to open with VS 2008 Express Edition.

Add the following to your PATH env variable.

W:\openssl\bin;W:\libxml2-2.6.30.win32\bin;W:\iconv-1.9.2.win32\bin;W:\zlib-1.2.3.win32\bin;W:\libxmlsec-1.2.11.win32\bin;W:\libxslt-1.1.22.win32\bin

Add the following to your CLASSPATH env variable.

W:\apache2.2\apr-1.lib;W:\libxml2-2.6.30.win32\libxml2.lib;W:\apache2.2\libhttpd.lib;W:\apache2.2\aprutil-1.lib;W:\apache2.2\libapr-1.lib;W:\libxslt-1.1.22.win32\libxslt.lib;W:\libxmlsec-1.2.11.win32\libxmlsec.lib

Now do the build in Debug mode with VS 2008 Express Edition.

You'll find mod_cspace.dll in [LOCAL_REPO]\build\win32\vc\apache2\Debug.

With this we complete building the module on Windows.

Now we need to configure SSL on WAMP. Please strictly follow the exact steps [with exact folder names and key names] in my previous post to do this. Don't miss a single step there.

Let's deploy our module in WAMP, now.

Copy mod_cspace.dll to c:\wamp\bin\apache\apache2.2.8\modules.

Now, let's edit httpd.conf [c:\wamp\bin\apache\apache2.2.8\conf]

Add the following to the file..

#Load mod_cspace.so
LoadModule cspace_module modules/mod_cspace.dll

#cspace_module configurations
<IfModule cspace_module>

#Make sure you give the absoulte path here to cscafile
CardSpaceCAFile "c:/wamp/bin/apache/apache2.2.8/conf/cscafile"

#Enable Cardspace login for php-sample web application
<Location /php-sample/>
UseCardSpaceAuth
</Location>

</IfModule>
Still, you miss two things.

- Download cscafile from here and copy it to c:\wamp\bin\apache\apache2.2.8\conf\.

- Download php-sample folder from here and copy it to c:\wamp\www.

All set... we are ready to GO...!!!

Start Apache server [if it is already running, stop and start] and type the URL https://identity-rp:12444/php-sample on your browser.

Okay... then... how do I know this works ???

We need to test our relying part web site with an Identity Provider.

Let's download WSO2 Identity Solution from here.

Unzip the downloaded ZIP file to a local folder [say [IS]].

Setting up the Identity Solution takes no more than 5 minutes... please follow the steps given here.

Startup the Identity Solution and go to the link https://localhost:12443 .

There you can register your self and sign in. Once signed in, you can download an Information Card from there. This guide, which is a very short one explains all what you need to know.

Now, you are almost done. But still, we need to say our Identity Provider that I trust php-sample as a relying party web site.

To do that I need to upload the certificate of this RP to my Identity Provider [IdP]. How to register a RP certificate with the IdP is explained here [look for "How to register your trusted Relying Party? "].

Still you have a question, I guess. How do I get the certificate of my php-sample [RP] ???

On IE 7, when you are at https://identity-rp:12444/php-sample - just right click the page --> Properties --> Certificates --> Details --> Copy to File --> Select 'DER' format --> Give a file name [e.g. site.cer] and save the certificate.

Are we done now..? Of course almost.. but, still there is something I skipped.

Remember the file "cscafile" ??? - which you downloaded from here.

This file contains public certificates of all the Identity Providers, who are accepted by the RP web site.

For this case you need not to do anything with this file - since I have already added the default public certificate of our Identity Provider - which ships with the Identity Solution.

But, in case you want to make this work with any other IdP, you need to get it's public certificate and add it to the cscafile file.

This is how you do it.

On IE 7 go to the IdP site --> just right click the page --> Properties --> Certificates --> Details --> Copy to File --> Select 'Base-64 Encoded' format --> Give a file name [e.g. site.cer] and save the certificate --> Open the saved certficate in notepad --> Copy and paste its content to cscafile.

Okay, finally we are done.

Hit the url, https://identity-rp:12444/php-sample and click the link "Login to this site" to initiate the InfoCard login.

0 comments: