{scrollbar}

top

This article focuses on the web application security related features of the Apache Geronimo server. The sample application covered in this article is a basic time reporting system that uses Servlets, JSPs and J2EE declarative security. In addition to above features it uses Geronimo's embedded Derby database to store user information of the system. Even though this application uses a database to hold user information, it is merely for configuration purposes. For detailed information on the usage of JDBC in Geronimo, refer the Simple database access sample application article.

After reading this article you should be able to configure Geronimo application server for web applications with declarative security features.

This article is organized in to following sections.

For users that are unfamiliar with J2EE form based authentication reading the following resources may be helpful in understanding Geronimo web application security:

Web Applications in Geronimoweb

Apache Geronimo includes a Web application container supporting J2EE Web applications. The Web container itself supports basic configuration such as network ports and SSL options, and each Web application may include Geronimo-specific configuration information as well. Web applications participate in the Geronimo security infrastructure, so authenticating to a Web application allows access to secure EJBs and Connectors as well.

Apache Geronimo currently supports two Web containers: Jetty and Tomcat.

Jetty

Jetty is a 100% Java HTTP Server and Servlet Container. This means that you do not need to configure and run a separate Web server in order to use servlets and JSPs to generate dynamic content. Jetty is a fully featured Web server for static and dynamic content.

Unlike separate server/container solutions, Jetty's Web server and Web application run in the same process without interconnection overheads and complications. Furthermore, as a pure java component, Jetty can be easily included in your application for demonstration, distribution or deployment. Jetty is available on all Java supported platforms.
http://jetty.mortbay.org/jetty/index.html

Tomcat

Apache Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies.
http://tomcat.apache.org/

Application Overview overview

The Time Report application helps to report working times of different projects. Even though this is not a full blown time reporting application, it covers most of the displaying and security related features web applications in Apache Geronimo.

This sample application allows two types of user groups to report their time tasks to the system, namely managers and employees. Both type of users have to provide their credentials before reporting time tasks. Managers are more of super users of the system, so they can add employees to the system additionally.

The Time Report application has the following list of pages.

Welcome
Login
Time Report
Add Employees
Logout

The following figure illustrates overview of application flow:

By default the given sample application is directed to the Welcome page with a link to the Time Report functionality. The users can access the Time Report page by providing a valid user name and password to the Login page. If those provided user credentials are from a manager role, Time Report page will display an additional link to the Add Employees functionality too.

Application contents

Following is the main folder hireachy of the Time Reporting application. It display both JSPs and configuration files used in the application.

java

In addition to the above JSPs and configurations, two other servlets are also required to fullfil the business logic of the application.

AddTimeRecordServlet - Read the input data from the Time Report page
AddEmployeeServlet - Capture input information from Add Employee page

Security configuration of the Time Report application is handled by geronimo-web.xml and web.xml files. geronimo-web.xml is used to define user roles of the application with TimeReportRealm.

xmlsolidgeronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"> <environment> <moduleId> <artifactId>TimeReportApp</artifactId> </moduleId> </environment> <context-root>/timereport</context-root> <security-realm-name>TimeReportRealm</security-realm-name> <security> <default-principal realm-name="TimeReportRealm"> <principal name="anonymous" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" /> </default-principal> <role-mappings> <role role-name="employee"> <realm realm-name="TimeReportRealm"> <principal name="EmployeeGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> <realm realm-name="TimeReportRealm"> <principal name="ManagerGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> </role> <role role-name="manager"> <realm realm-name="TimeReportRealm"> <principal name="ManagerGroup" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" /> </realm> </role> </role-mappings> </security> </web-app>

web.xml will map the defined user roles to resources in the web application. It also defines the login configurations of the application.

xmlsolidweb.xml

<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <welcome-file-list> <welcome-file>index.jsp</welcome-file> </welcome-file-list> <security-constraint> <web-resource-collection> <web-resource-name>employee</web-resource-name> <url-pattern>/employee/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>employee</role-name> </auth-constraint> </security-constraint> <security-constraint> <web-resource-collection> <web-resource-name>manager</web-resource-name> <url-pattern>/manager/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <realm-name>TimeReportRealm</realm-name> <form-login-config> <form-login-page>/login/login.jsp</form-login-page> <form-error-page>/login/login_error.jsp</form-error-page> </form-login-config> </login-config> <security-role> <role-name>employee</role-name> </security-role> <security-role> <role-name>manager</role-name> </security-role> <servlet> <display-name>AddTimeRecordServlet</display-name> <servlet-name>AddTimeRecordServlet</servlet-name> <servlet-class>org.timereport.web.employee.AddTimeRecordServlet</servlet-class> </servlet> <servlet> <display-name>AddEmployeeServlet</display-name> <servlet-name>AddEmployeeServlet</servlet-name> <servlet-class>org.timereport.web.manager.AddEmployeeServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>AddTimeRecordServlet</servlet-name> <url-pattern>/employee/add_timerecord</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>AddEmployeeServlet</servlet-name> <url-pattern>/manager/add_employee</url-pattern> </servlet-mapping> </web-app>

To restrict access to the Add Employee functionality from Time Report page, programmatic authentication has beeen used as in indicated below.

javasolidemployee/index.jsp

... <BR> <%if(request.isUserInRole("manager")){%> <A href="../manager/">Add Employees</A> <BR> ...

Tools used

The tools used for developing and building the Time Reporting sample application are:

Eclipse

The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. It has a integration plug-ins to the Geronimo too. Eclipse can be downloaded from the following URL:
http://www.eclipse.org

Apache Ant

Ant is a pure Java build tool. It is used for building the war files for the Time Reporting application. Ant can be downloaded from the following URL:
http://ant.apache.org

Back to Top

Configuring, Building and Deploying the Sample Application configure

Download the Time Reporting application from the following link:
Time Report

After extracting the zip file, the <time_report> directory is created.

Configuring

Since Time Reporting application is going to use J2EE declarative security, user needs to create a database to hold the information and deploy the security realm.

Create Database to hold User Information

After starting Apache Geronimo server, log into the console and follow the given steps to create the TimeReportDB to hold user information for the application.

solidTimeReportDB.sql

CREATE TABLE users( userid VARCHAR(15) PRIMARY KEY, password VARCHAR(15), name VARCHAR(40) ); CREATE TABLE usergroups( userid VARCHAR(15), groupname VARCHAR(20), PRIMARY KEY (userid, groupname) ); INSERT INTO users VALUES('emp1', 'pass1', 'Employee 1'); INSERT INTO users VALUES('emp2', 'pass2', 'Employee 2'); INSERT INTO users VALUES('mgm1', 'pass3', 'Manager 1'); INSERT INTO users VALUES('mgm2', 'pass4', 'Manager 2'); INSERT INTO usergroups VALUES('emp1', 'EmployeeGroup'); INSERT INTO usergroups VALUES('emp2', 'EmployeeGroup'); INSERT INTO usergroups VALUES('mgm1', 'ManagerGroup'); INSERT INTO usergroups VALUES('mgm2', 'ManagerGroup');

Select DB Manager link from the Console Navigation in the left.
Give the database name as TimeReportDB in the Create DB field and click Create button.
Select TimeReportDB to the Use DB field.
Open TimeReportDB.sql in the time_report/config directory.
Paste the content TimeReportDB.sql to the SQL Commands text area and press Run SQL button.

Configure Security Realm

As same as in the creating database, follow the given steps to deploy the security relam of the Time Reporting application.

xmlsolidTimeReportRealm.xml

<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1"> <environment> <moduleId> <groupId>console</groupId> <artifactId>TimeReportRealm</artifactId> <version>1.0</version> <type>car</type> </moduleId> <dependencies> <dependency> <groupId>geronimo</groupId> <artifactId>j2ee-security</artifactId> <type>car</type> </dependency> <dependency> <groupId>geronimo</groupId> <artifactId>system-database</artifactId> <type>car</type> </dependency> </dependencies> </environment> <gbean name="TimeReportRealm" class="org.apache.geronimo.security.realm.GenericSecurityRealm"> <attribute name="realmName">TimeReportRealm</attribute> <reference name="ServerInfo"> <name>ServerInfo</name> </reference> <reference name="LoginService"> <name>JaasLoginService</name> </reference> <xml-reference name="LoginModuleConfiguration"> <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.1"> <log:login-module control-flag="REQUIRED" server-side="true" wrap-principals="false"> <log:login-domain-name>TimeReportRealm</log:login-domain-name> <log:login-module-class>org.apache.geronimo.security.realm.providers.SQLLoginModule</log:login-module-class> <log:option name="jdbcDriver">org.apache.derby.jdbc.EmbeddedDriver</log:option> <log:option name="jdbcUser">app</log:option> <log:option name="userSelect">select userid, password from users where userid=?</log:option> <log:option name="groupSelect">select userid, groupname from usergroups where userid=?</log:option> <log:option name="jdbcURL">jdbc:derby:TimeReportDB</log:option> </log:login-module> </log:login-config> </xml-reference> </gbean> </module>

Select Deploy New link from Console Navigation.
Load time_report/config/TimeReportRealm.xml to the Plan input box.
Press Install button deploy security realm to the application server.
(Make sure Start app after install check box is checked before pressing install button.)

For the verification after the deployment,click on the Security Realms link in the Geronimo Console and check under new security realm for the TimeReportRealm.

Building

Time Report application comes with an Ant script to help users to build from source code. Open a command prompt window and navigate to the time_report directory and just give ant command to build. This will create a TimeReport.war under the releases folder in the time_report. Now, you are ready to deploy the Time Report application in the Geronimo Application server.

Deploying

Deploying the sample application is pretty straight forward, since we are using the Geronimo Console.

Scroll down to Deploy New from the Console Navigation panel.
Load TimeReport.war from time_report/releases folder in to the Archive input box.
Press Install button to deploy application in the server.

Back to Top

Testing of the Sample Application testing

To test the sample application open a browser and type http://localhost:8080/timereport. It will forward to the Welcome page of the application.

User can access Time Report page providing username as emp1 and password with pass1. To login to the application as a Manager provide mgm1 and pass3 credentials.

Summary summary

This article has shown you how to deploy web application in to the Geronimo Application server with J2EE declarative security features. You followed step-by-step instructions to build, deploy and test the sample application.

Some highlights of the article are:-

Apache Geronimo provides two different web containers namely Jetty and Tomcat.
Create a database to hold security data with built-in Derby.
Define security roles in Geronimo Web applications.
Deploy deployment plans and web archives using the Geronimo Console.