Configuring JGuard for JEE Web Applications

Who Should Read This Tutorial

This tutorial is aimed for those who need to setup a reliable security for a JEE web application
using JGuard framework and MyEclipse as the base developing tool.

What You Will Learn

At the end of this tutorial you will learn how to create, setup and configure a JEE web
application and secure it using JGuard framework in the three following levels:

• Using XML authentication/authorization

• Using database authentication/authorization

• Using jCaptcha authentication scheme

Requirements
Below is a list of software required before using this guide:

• Windows 2000 or XP

• IE 6+ or a Mozilla Based Web Browser

• JDK 1.4+

• Eclipse 3.1 SDK

• MyEclipse 4.1 Standard or Professional Edition

• JGuard 1.0.3 Bundle

• MySQL 5.0

• JBoss 4.0.x or Tomcat 5+

In order to setup JGuard properly, reader should have an average knowledge about JGuard
configuration and functionality and key xml files and related elements.

If you need complete information on JGuard, please visit JGuard home page at:

http://www.xwiki.jguard.com

In order to create and develop web application, a minimum knowledge on using MyEclipse web
development tools will help.

In order to setup databases, reader will need enough information on using MySQL and related
GUI Tools.

Outline
1. New Project Setup & Structure

2. Configuring Your web.xml

a. Add DTD Information

b. Configure JGuard

3. Creating JSP Files

4. Configuring Your struts-config.xml

a. Configure Form Bean

b. Configure Actions

c. Configure Global Forwards

d. Configure Controller

5. Checking on JGuard XML Files

6. Adding Required JAR Files

Preface
One of the tedious tasks in web application development especially for a JEE web application is
setting up a proper security for both authentication and authorization section.
As we all know, security is a relative concept and hence every system needs to set it up based on
its requirements. But most the times developers do not need to configure a high level of security
with complex access controls and etc. but a nice and reliable security plug-in will completely
suffice.

Meanwhile, two important factors that come in between would be the ease of configuration and
plugging and also flexibility to upgrade security level when needed.

JGuard
JGuard is an open source JEE security framework for resolving access control problems in web
and standalone applications.

New Project Setup & Structure

To organize our development artifacts, we will need to create a new Web Module Project in
MyEclipse that has Struts Capabilities added to it. You can create a web project using the wizard
located at File > New > Other > Project > J2EE > Web Project , as shown in Figure 1, below.
Figure 1 - Web Project Wizard Dialog

Now enter in all the new project information, as shown in Figure 2:

Figure 2 - Web Project Settings

Once the Web Project is created, we need to add Struts Capabilities to it. This is done by right
clicking on the root of our project in the Package Explorer View, and selecting MyEclipse >
Add Struts Capabilities, as shown in Figure 3.
Figure 3 - Adding Struts Capabilities to a Web Project

The default values for the Struts dialog are fine for the purposes of this tutorial. However, you
might want to change the Base package for new classes to reflect your desired location. In
Figure 4 below, we will simply leave the default values.
Figure 4 - Configuring Struts Capabilities

After the wizard completes, the project structure will look like that shown in Figure 5.

Now let’s make some redecoration on files and folders.

Create folders jGuard and tld under the WEB-INF/conf directory and to group tld
files move them to the tld folder. Now our project should look like this:
Figure 5 - Project Layout After Configuration

Configuring Your web.xml

Adding DTD Information
We need to edit web.xml file to configure JGuard AccessFilter, Listener and etc.
As you open web.xml you will see the struts ActionServlet configuration and will probably
notice that <web-app> element uses xmlns (as below) and hence you won’t be able to add
proper child elements in Myeclipse design mode.

<web-app
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="2.5"
xsi:schemaLocation=
 "http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

So, remove all <web-app> attributes from the source code and then in order to add proper DTD
information switch to design mode and right-click on <web-app> element and select Add DTD
Information.

On Public ID: field click Browse and select -//Sun Microsystems, Inc.//DTD Web Application
2.3//EN as the figure suggests and hit OK and again OK to add DTD Information to your
web.xml file.

Figure 6 – Adding DTD tag to our web.xml

Configure JGuard
To start, let’s give our web application a name which is also necessary for JGuard to realize the
application name.
So, in design mode, right-click on the <web-app> element and select Add Child>display-name
and for its value type securedapp. You can also add the description exactly the same way and
fill the value as you desire.

Now, let’s set JGuard key files and configuration in our web.xml through following steps.

1. To set JGuard Authentication file right-click on <web-app> and then Add Child >
context-param and set the values as following:
<param-name> with authenticationConfigurationLocation and
<param-value> with /WEB-INF/conf/jGuard/jGuardAuthentication.xml

2. To set JGuard Authentication scope add another context-param and set the values as
following:
<param-name> with authenticationScope and
<param-value> with local

3. To set JGuard Authorization file add another context-param and set the values as
following:
<param-name> with authorizationConfigurationLocation and
<param-value> with /WEB-INF/conf/jGuard/jGuardAuthorization.xml

4. To set JGuard Authorization scope add another context-param and set the values as
following:
<param-name> with authorizationScope and
<param-value> with local

5. In order to disable JMX add another context-param and set the values as following:
<param-name> with enableJMX and
<param-value> with false

6. Now, let’s add JGuard AccessFilter configuration by adding a <filter> in the same way
and setting related values as following:
<filter-name> with AccessFilter
<filter-class> with net.sf.jguard.jee.authentication.http.AccessFilter

7. To pass its location as an <init-param> element, right-click on <filter> element and add
the <init-param> element and set its values as following:

<param-name> with configurationLocation

<param-value> with /WEB-INF/conf/jGuard/jGuardFilter.xml

8. Now, We need to map this filter to every actions. Then, right-click on <web-app> and
add a <filter-mapping> element and set the values as following:
<filter-name> with AccessFilter
<url-pattern> with *.do
 9. The final step would be adding the listener class. So, right-click on <web-app>, add the
<listener> element and set the value as below:
<listener-class> with net.sf.jguard.jee.listeners.ContextListener

The main configuration of JGuard in web.xml ends here but you can set one more additional
element which tells your web application when to timeout your session. So, right-click on <web-
app> and add <session-config> element and set its value as: <session-timeout> with 30.

Your web.xml file should now look like this:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "web-app_2_3.dtd">
<web-app>
<display-name>securedapp</display-name>
<description>Provides security with jGuard</description>
<context-param>
<param-name>authenticationConfigurationLocation</param-name>
<param-value>
/WEB-INF/conf/jGuard/jGuardAuthentication.xml
</param-value>
</context-param>
<context-param>
<param-name>authenticationScope</param-name>
<param-value>local</param-value>
</context-param>
<context-param>
<param-name>authorizationConfigurationLocation</param-name>
<param-value>
/WEB-INF/conf/jGuard/jGuardAuthorization.xml
</param-value>
</context-param>
<context-param>
<param-name>authorizationScope</param-name>
<param-value>local</param-value>
</context-param>
<context-param>
<param-name>enableJMX</param-name>
<param-value>false</param-value>
</context-param>
<filter>
<filter-name>AccessFilter</filter-name>
<filter-class>
net.sf.jguard.jee.authentication.http.AccessFilter
</filter-class>
<init-param>
<param-name>configurationLocation</param-name>
<param-value>
/WEB-INF/conf/jGuard/jGuardFilter.xml
</param-value>
</init-param>
</filter>
<filter-mapping>
 <filter-name>AccessFilter</filter-name>
<url-pattern>*.do</url-pattern>
</filter-mapping>
<listener>
<listener-class>
net.sf.jguard.jee.listeners.ContextListener
</listener-class>
</listener>

<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
org.apache.struts.action.ActionServlet
</servlet-class>
<init-param>
<param-name>config</param-name>
<param-value>
/WEB-INF/conf/struts/struts-config.xml
</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>3</param-value>
</init-param>
<init-param>
<param-name>detail</param-name>
<param-value>3</param-value>
</init-param>
<load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>30</session-timeout>
</session-config>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>
</web-app>

Creating JSP Files

There are several main JSP files in order to handle authentication as well as representing
messages related to authentication and authorization events. It would be a good practice to place
all of our web application JSP files under the WEB-INF directory. We will address these files in
our struts-config.xml later on.

• Create the jsp directory under WEB-INF, right-click on the newly created directory and
then create a new JSP file and name it: logon.jsp and replace the source code with the
code below:
<%@ taglib prefix="html" uri="http://struts.apache.org/tags-html-el"%>
<title>authentication</title>
<html:form action="/LogonProcess" method="post">
you can enter admin/admin in user/password fields to authenticate
<div>
Login
<input
id="login" type="text" maxlength="20"
size="30" name="login" tabindex="1" />
</div>
<div>
Password
<input
id="password" type="password" value=""
size="30" name="password" tabindex="2" />
</div>
<input type="submit" value="submit" tabindex="4" />
<input type="reset" value="reset" tabindex="5" />
</html:form>

• create a new JSP file and name it: logoff.jsp and replace the source code with the code
below:
<%@ taglib prefix="html" uri="http://struts.apache.org/tags-html-el"%>
<title>logoff</title>
<h1>now you are unauthenticated</h1>

• create a new JSP file and name it: accessDenied.jsp and replace the source code with the
code below:
<%@ taglib prefix="html" uri="http://struts.apache.org/tags-html-el" %>
<title>access denied</title>
<h1>access to this ressource is denied</h1>

• create a new JSP file and name it: authenticationFailed.jsp and replace the source code
with the code below:
<%@ taglib prefix="html" uri="http://struts.apache.org/tags-html-el" %>
<title>authentication failed</title>
<h1>authentication Failed</h1>

We will create two more JSP files. The first file is to setup our welcome page and the second one
is created to test JGuard functionality.

• create a new JSP file and name it: welcome.jsp and replace the source code with the code
below:
<%@ taglib prefix="jguard" uri="http://jguard.net/tld/jguard.tld"%>
<%@ taglib prefix="html" uri="http://struts.apache.org/tags-html-el"%>
<title>welcome page</title>
<h1>JGuard Welcome page</h1>
<h2>all users in the jGuardExample webApp have access to this page</h2>
<html:link forward="vipArea">
go to the vip area!!!
</html:link>

<jguard:hasPrincipal principals="admin,customer" operator="NONE">

you have neither the 'admin' role , nor the 'customer' role
</jguard:hasPrincipal>

<jguard:hasPrincipal
 principals="customer"
applicationName="anotherApplication">
you have got the 'customer' role
</jguard:hasPrincipal>

• create a new JSP file and name it: vipArea.jsp and replace the source code with the code
below:
<%@ taglib prefix="jguard" uri="http://jguard.net/tld/jguard.tld" %>
<title>vip area</title>
<h1>vip area</h1>
<p>only authenticated users will have access to this page</p>
<jguard:hasPrincipal principals="businessManager">
role = businessManager
</jguard:hasPrincipal>

<jguard:hasPrincipal principals="admin,stuff">
hello!! you have got a role called admin
</jguard:hasPrincipal>

Configuring Your struts-config.xml

Configure Form Bean
In struts-config.xml you need to configure basic Actions and forms needed for JGuard
authentication and authorization.
Open struts-config.xml in Source Mode. Replace the <form-beans /> with the following code.

<form-beans>
<form-bean name="generalForm" type="org.apache.struts.action.DynaActionForm">
<form-property name="permissionName" type="java.lang.String" />
<form-property name="domainName" type="java.lang.String" />
<form-property name="Domains" type="java.util.ArrayList" />
<form-property name="DomainsNotBound" type="java.util.ArrayList" />
<form-property name="permissionsNotBound" type="java.util.ArrayList" />
<form-property name="description" type="java.lang.String" />
<form-property name="permissionURI" type="java.lang.String" />
<form-property name="scheme" type="java.lang.String" />
<form-property name="oldPermissionName" type="java.lang.String" />
<form-property name="oldDomainName" type="java.lang.String" />
<form-property name="principals" type="java.util.ArrayList" />
<form-property name="principalName" type="java.lang.String" />
<form-property name="principalAsc" type="java.lang.String" />
<form-property name="principalDesc" type="java.lang.String" />
<form-property name="oldPrincipalName" type="java.lang.String" />
<form-property
name="principal"
type="net.sf.jguard.core.principals.RolePrincipal" />
<form-property name="domainNames" type="java.lang.String" />
<form-property name="permissionNames" type="java.lang.String" />
<form-property name="permissionActions" type="java.lang.String" />
<form-property name="permissionClass" type="java.lang.String" />
<form-property name="scriptText" type="java.lang.String" />
<form-property name="scriptResult" type="java.lang.String" />
<form-property name="job" type="java.lang.String" />
<form-property name="location" type="java.lang.String" />
<form-property name="login" type="java.lang.String" />
<form-property name="oldLogin" type="java.lang.String" />
<form-property name="password" type="java.lang.String" />
<form-property name="users" type="java.util.ArrayList" />
<form-property name="firstname" type="java.lang.String" />
<form-property name="lastname" type="java.lang.String" />
<form-property name="country" type="java.lang.String" />
<form-property name="religion" type="java.lang.String" />
<form-property name="hobbies" type="java.lang.String" />
<form-property name="userPrincipalsNames" type="java.lang.String" />
</form-bean>
</form-beans>

Configure Actions
Switch to design mode and add New>Action, in the path field type /Welcome (MyEclipse will
show you an error sign because of empty use case field, but ignore it for now).
In Action Impl select Use existing Action class and click browse for Existing Type and look
for ForwardAction which resides in org.apache.struts.actions. When you click OK button,
MyEclipse error will disappear.
Figure 7 – Select ForwardAction as Existing Type

Now go to Parameter tab and type /WEB-INF/jsp/welcome.jsp in the parameter field and click
OK button.

Now repeat the above steps with the following values to setup remaining Actions. In all Actions
the Existing Type will remain the same.

• path="/AccessDenied", parameter="/WEB-INF/jsp/accessDenied.jsp"
• path="/AuthenticationFailed", parameter="/WEB-INF/jsp/authenticationFailed.jsp"
• path="/Logon", parameter="/WEB-INF/jsp/logon.jsp"
 • path="/VipArea", parameter="/WEB-INF/jsp/vipArea.jsp"
• path="/Logoff", parameter="/WEB-INF/jsp/logoff.jsp" />

To configure the last Action, do exactly the above steps with these values:
• path="/LogonProcess", parameter="/WEB-INF/jsp/welcome.jsp"
But before clicking OK button, in the Form tab, click Browse on Name: field and choose the
generalForm that We recently added and at the end delete the content of the Scope field.

Note: The /VipArea is a secured path where we will test if JGuard works properly.

Configure Global Forwards

In design mode right-click on the screen and select New>Forward.
In the Name field and Path field type the following values respectively:
• welcome, /Welcome.do.
• logon, /Logon.do and also check the Redirect and Context relative checkboxes.
• logoff, /Logoff.do and also check the Redirect checkbox.
• vipArea, /VipArea.do and also check the Redirect checkbox.

Configure Controller
As MyEclipse seems not able to setup the controller visually, you will have to add the following
code to your struts-config.xml manually right after the </action-mappings> element.

<controller
locale="false"
inputForward="true"
processorClass="org.apache.struts.action.RequestProcessor"
contentType="text/html" />

At the end, your struts-config.xml should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE struts-config PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 1.2//EN" "http://struts.apache.org/dtds/struts-
config_1_2.dtd">

<struts-config>
<data-sources />
<form-beans>
<form-bean name="generalForm" type="org.apache.struts.action.DynaActionForm">
<form-property name="permissionName" type="java.lang.String" />
<form-property name="domainName" type="java.lang.String" />
<form-property name="Domains" type="java.util.ArrayList" />
<form-property name="DomainsNotBound" type="java.util.ArrayList" />
<form-property name="permissionsNotBound" type="java.util.ArrayList" />
<form-property name="description" type="java.lang.String" />
<form-property name="permissionURI" type="java.lang.String" />
<form-property name="scheme" type="java.lang.String" />
<form-property name="oldPermissionName" type="java.lang.String" />
<form-property name="oldDomainName" type="java.lang.String" />
<form-property name="principals" type="java.util.ArrayList" />
<form-property name="principalName" type="java.lang.String" />
 <form-property name="principalAsc" type="java.lang.String" />
<form-property name="principalDesc" type="java.lang.String" />
<form-property name="oldPrincipalName" type="java.lang.String" />
<form-property
name="principal"
type="net.sf.jguard.core.principals.RolePrincipal" />
<form-property name="domainNames" type="java.lang.String" />
<form-property name="permissionNames" type="java.lang.String" />
<form-property name="permissionActions" type="java.lang.String" />
<form-property name="permissionClass" type="java.lang.String" />
<form-property name="scriptText" type="java.lang.String" />
<form-property name="scriptResult" type="java.lang.String" />
<form-property name="job" type="java.lang.String" />
<form-property name="location" type="java.lang.String" />
<form-property name="login" type="java.lang.String" />
<form-property name="oldLogin" type="java.lang.String" />
<form-property name="password" type="java.lang.String" />
<form-property name="users" type="java.util.ArrayList" />
<form-property name="firstname" type="java.lang.String" />
<form-property name="lastname" type="java.lang.String" />
<form-property name="country" type="java.lang.String" />
<form-property name="religion" type="java.lang.String" />
<form-property name="hobbies" type="java.lang.String" />
<form-property name="userPrincipalsNames" type="java.lang.String" />
</form-bean>
</form-beans>
<global-exceptions />
<global-forwards>
<forward name="welcome" path="/Welcome.do" />
<forward name="logon" path="/Logon.do" redirect="false" contextRelative="true" />
<forward name="logoff" path="/Logoff.do" redirect="false" />
<forward name="vipArea" path="/VipArea.do" redirect="false" />
</global-forwards>
<action-mappings>
<action
path="/Welcome"
type="org.apache.struts.actions.ForwardAction"
parameter="/WEB-INF/jsp/welcome.jsp" />
<action
path="/AccessDenied"
type="org.apache.struts.actions.ForwardAction"
parameter="/WEB-INF/jsp/accessDenied.jsp" />
<action
path="/AuthenticationFailed"
parameter="/WEB-INF/jsp/authenticationFailed.jsp"
type="org.apache.struts.actions.ForwardAction" />
<action
path="/Logon"
parameter="/WEB-INF/jsp/logon.jsp"
type="org.apache.struts.actions.ForwardAction" />

<action
path="/VipArea"
parameter="/WEB-INF/jsp/vipArea.jsp"
type="org.apache.struts.actions.ForwardAction" />
<action
path="/Logoff"
type="org.apache.struts.actions.ForwardAction"
parameter="/WEB-INF/jsp/logoff.jsp" />
<action
path="/Captcha"
type="com.nsbsfi.prsnt.struts.action.CaptchaAction"
name="generalForm" />
<action
path="/LogonProcess"
type="org.apache.struts.actions.ForwardAction"
name="generalForm"
parameter="/WEB-INF/jsp/welcome.jsp"
attribute="generalForm" />
</action-mappings>
 <controller
locale="false"
inputForward="true"
processorClass="org.apache.struts.action.RequestProcessor"
contentType="text/html" />

<message-resources parameter="com.sw.presentation.struts.ApplicationResources" />

</struts-config>

Checking on JGuard XML Files

As you may know, by now, JGuard uses five XML files (plus their related DTD files) to
configure authentication and authorization for your project. These files which We previously
addressed some of them in our web.xml, are:
1. jGuardAuthentication.xml
2. jGuardAuthorization.xml
3. jGuardFilter.xml
4. jGuardUsersPrincipals.xml
5. jGuardPrincipalsPermissions.xml

Configuring these files from scratch is beyond this tutorial. But you can refer to JGuard main
documentation for further information.
While, in order to setup XML based authentication and authorization, you can copy these XML
file and also their DTD files from WEB-INF/conf/jGuard of our securedapp.zip into yours.

NOTE: Open the jGuardUsersPrincipals.xml and notice that everywhere you can find the
applicatioName it is equal to securedapp (except for the customer role which belongs to
another web application). This name should exactly be the same and the one you define in your
<display-name> element in your web.xml. So, if you are configuring JGuard for a web
application with a different name, be sure to correct this in the jGuardUsersPrincipals.xml for all
principals that belong to this web application.

Adding Required JAR Files

The last step of configuring is to include some important JAR files needed by this project.
You can either use Maven to manage your project libraries or to copy these files in your WEB-
INF/lib yourself or you can add them through project properties>java built path.
Following is the list of necessary JAR files.

Charles please add the necessary jar files list here!

Author: Mahan Hooshmand Rad

Email: mahorad@yahoo.com