Agent Configuration

= Introduction = This section describes step by step the integration of a partner application that references the security service for authentication and authorization. This considers that your web-application has been written in java and that your web-container is tomcat-7.x. The instructions are very similar for other web-containers. Two main tasks should be executed in order to integrate a web-application from scratch.


 * Installation of the agent in your web-container.
 * Changes in your web application.

For the case that a second application should be integrated that runs in the same web-container, it is not necessary to execute the first step again.

Installation of Agent
A JOSSO Agent can be considered as a wrapper of the Java Realm. A Realm is a kind of structure, where users and groups are stored. These users and groups are necessary to access restricted parts of your web application. An agent replaces the Realm that is implemented by your web-container (in this context the Tomcat implementation). Thus, every time when your web application needs to authenticate a user, the agent connects to the remote security service to perform this action, instead of accessing a database or an xml file, as is done by the Realm implementation of Tomcat. The installation of the JOSSO agent can be achieved manually or by the execution of a JOSSO script.

Automatic Installation of JOSSO Agent
The distribution of JOSSO contains a script that starts the josso-console. In this console you can install automatically the agent following these steps.


 * Start the josso-console: ./JOSSO_HOME/bin/josso-gsh.
 * Install the agent: josso> agent install --target /var/lib/apache-tomcat-7.x.x --platform tc70.

Adding the libraries
The distribution of JOSSO provides all jars necessary for the agent in “$JOSSO_HOME/lib”. The following jars should be copied into the library folder of tomcat ($TOMACT_HOME/lib): List of 3rd party JARs:


 * activation-1.1.jar
 * aopalliance-1.0.jar
 * axis-1.4-wl81fix.jar
 * axis-1.4.jar
 * axis-ant-1.4.jar
 * axis-jaxrpc-1.4.jar
 * axis-saaj-1.4.jar
 * axis-wsdl4j-1.5.1.jar
 * commons-beanutils-1.6.1.jar
 * commons-codec-1.3.jar
 * commons-collections-3.0.jar
 * commons-digester-1.5.jar
 * commons-discovery-0.2.jar
 * commons-httpclient-3.1.jar
 * commons-lang-2.0.jar
 * commons-logging-1.1.1.jar
 * commons-logging-api-1.0.4.jar
 * commons-modeler-1.1.jar
 * portal-identity-lib-2.7.1.GA.jar
 * spring-aop-2.5.5.jar
 * spring-beans-2.5.5.jar
 * spring-context-2.5.5.jar
 * spring-core-2.5.5.jar
 * xbean-spring-3.4.3.jar

List of JOSSO JARs:


 * josso-agent-shared-1.8.4.jar
 * josso-agents-bin-1.8.4.jar

Configuration Files

 * The file server.xml located in $TONCAT_HOME/conf/ should be modified.

In this file two elements should be inserted: a new realm component Tomcat Realm Howto and a new valve component Tomcat Valve Howto. Both components should be located within the engine component of the servel.xml file. The following Figure illustrates the insertion of both components:

The security service is hosted on http://josso.dm2e.eu/josso/. The JOSSO agent must know where this service is located to be able to login and logout. This information must be configured in the file josso-agent-config.xml.
 * A file called josso-agent-config.xml should be inserted in $TOMCAT_HOME/lib/.


 * Insert a file called jaas.conf in $TOMCAT_HOME/conf/. This file should contain the following line:

Changes in Your Web Application
Due to the differences that each web application can have, it is not easy to provide a common guide for the adaptation of application to the JOSSO infrastructure. However, due to the standardization of the java application, there are common ways to configure the security constraints that are applicable to JOSSO. A complete guide to configure security constraints can be found in http://docs.oracle.com/cd/E19798-01/821-1841/bncbk/index.html. In order to configure the security constrains of your application, you have to modify your web.xml. There you can insert as many constraints as necessary. A constraint is basically composed of two elements: the web resource collection and authentication constraint. The first element lists what resources are protected by this constraint and the second one specifies who can access this list of resources when authenticated. The following Figure illustrates an example: