This installation guide describes the process of installing and configuring FOAFRealm version 2.*.

Requirements

In order to use FOAFRealm, the following requirements need to be met.

• Make sure to have Java Development Kit (JDK 1.5.x or higher required) installed on your computer.
• FOAFRealm works with Apache Tomcat 6.x or greater only.

Installation

First, you need to download the latest release from here. Each package contains some common files and directories.

• docs - contains project documentation and javadoc
• endorsed - contains libraries which must be present in $CATALINA_HOME/endorsed directory
• lib - libraries
• foafrealm-manage-x.x.x.jar - FOAFRealm library
• foafrealm-realm-x.x.x.jar - contains Tomcat authentication plugin, needs to be placed inside $CATALINA_HOME/lib/ directory
• foafrealm-soa-x.x.x.jar - FOAFRealm library
• LICENSE.txt - license
• README.txt - short instruction

Configure Apache Tomcat

It's recommended to prepare you Apache Tomcat installation to confirm project's requirements. Please read and follow this guide.

For a web application to use FOAFRealm, we need to tell Tomcat to use it. This can be done by setting Realm anv Valve in the context configuration. You can read about contexts here, or you can skip it and perform this simple step.

Place the following text in $CATALINA_BASE/webapps/[webappname]/META-INF/context.xml file.

    <Context>
        <Realm className="org.foafrealm.realm.FOAFRealm" soaURI="http://localhost:8080/users/" />
        <Valve className="org.foafrealm.realm.FOAFValve" />
    </Context>

Configuring Web Application

Web application is configured by means of elements contained in the web application deployment descriptor (web.xml). Please refer to Servlet documentation on how to secure resources in you web application.

Declaring Servlets

Several Servlets need to be exposed in the web application as FOAFRealm services.

Place the following declarations in you web.xml file.

	<filter>
		<filter-name>RealmFilter</filter-name>
		<filter-class>org.foafrealm.bean.RealmFilter</filter-class>
	</filter>
	<filter-mapping>
		<filter-name>RealmFilter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>

	<servlet>
		<display-name>OIdUserAuthentication</display-name>
		<servlet-name>OIdUserAuthentication</servlet-name>
		<servlet-class>org.foafrealm.openid.auth.OIdUserAuthentication</servlet-class>
	</servlet>
	<servlet>
		<servlet-name>ConfirmationServlet</servlet-name>
		<servlet-class>org.foafrealm.servlet.ConfirmationServlet</servlet-class>
	</servlet>
	<servlet>
		<description>Returns FOAF from the FOAFRealm</description>
		<servlet-name>GetFoaf</servlet-name>
		<servlet-class>org.foafrealm.servlet.GetFoaf</servlet-class>
	</servlet>
	<servlet>
		<description>Main SOA REST servlet</description>
		<servlet-name>RESTRequestDispatcher</servlet-name>
		<servlet-class>org.foafrealm.soa.rest.RESTRequestDispatcher</servlet-class>
	</servlet>
	<servlet>
		<servlet-name>ManagePicture</servlet-name>
		<servlet-class>org.foafrealm.servlet.ManagePicture</servlet-class>
	</servlet>
	<servlet>
		<servlet-name>PasswordServlet</servlet-name>
		<servlet-class>org.foafrealm.servlet.PasswordServlet</servlet-class>
	</servlet>
	<servlet>
		<servlet-name>RegisterServlet</servlet-name>
		<servlet-class>org.corrib.aparicio.soa.foafrealm.RegisterServlet</servlet-class>
	</servlet>
	<servlet>
		<description>very simple image displayer</description>
		<servlet-name>ShowPicture</servlet-name>
		<servlet-class>org.foafrealm.servlet.ShowPicture</servlet-class>
	</servlet>

	<servlet-mapping>
		<servlet-name>OIdUserAuthentication</servlet-name>
		<url-pattern>/oiauth</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>ConfirmationServlet</servlet-name>
		<url-pattern>/confirmation/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>GetFoaf</servlet-name>
		<url-pattern>/FOAF</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>ManagePicture</servlet-name>
		<url-pattern>/pic/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>PasswordServlet</servlet-name>
		<url-pattern>/password</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>RESTRequestDispatcher</servlet-name>
		<url-pattern>/users/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>RESTRequestDispatcher</servlet-name>
		<url-pattern>/soa/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>RegisterServlet</servlet-name>
		<url-pattern>/registerProxy</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>ShowPicture</servlet-name>
		<url-pattern>/showpicture</url-pattern>
	</servlet-mapping>

Configuring FOAFRealm

You can override default parameters for FOAFRealm in a file called 'foafrealm.properties'. Place it at the "root" of your classpath or classloader.

Testing

Now you are ready to test you web application. The easiest way to do it is by accesing a secured resource. When promt for login and password, use the ones configured in foafrealm.properties.