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 using the geronimo SQLLoginModule and the derby database.
After reading this article you should be able to configure Geronimo application server for web applications with declarative security features.

NOTE: The sample does not actually add new employees when the manager function is executed. This capability may be added in the future. However the sample does demonstrate a method of implementing web application security using the pre-defined users.

This article is organized into the following sections.

Web Applications in Geronimo

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 a servlet container developed at the Apache Software Foundation.
http://tomcat.apache.org/

Application 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 uses two security roles, namely manager and employee. Both type of users have to provide their credentials before reporting time tasks.

The employee role allows the user to report time.
The manager role allows the user to add employees.
The configuration of this application illustrates a simple form of hierarchical role based access control in that the javaee roles have disjoint permissions and the mapping from group principals to application roles provides users in the manager group with the employee role.

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

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

|- employee
	+- index.jsp
|- login
	+- login.jsp
	+- login_error.jsp
	+- logout.jsp
|- manager
	+- index.jsp
|- WEB_INF
	+- web.xml
|- index.jsp

In addition to the above JSPs and configurations, two other servlets are also required to fulfill 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 the Geronimo deployment plan plan.xml and web.xml files.

web.xml includes the standard security constraints relating user roles to resources in the web application.

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements. See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership. The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License. You may obtain a copy of the License at
    
    http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied. See the License for the
    specific language governing permissions and limitations
    under the License.
-->
<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.html</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.apache.geronimo.samples.timereport.web.AddTimeRecordServlet</servlet-class>
    </servlet>
    <servlet>
        <display-name>AddEmployeeServlet</display-name>
        <servlet-name>AddEmployeeServlet</servlet-name>
        <servlet-class>org.apache.geronimo.samples.timereport.web.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>

The Geronimo deployment plan ( plan.xml found after building the project at timereport/timereport-jetty/target/resources/META-INF/plan.xml) includes the Geronimo specific security configuration including the security realm configuration and the principal-role mapping relating the principals from the security realm to the application roles defined above in web.xml This project uses two roles, manager and employee. There is a business rule that every manager is an employee. This is enforced through the principal-role mapping: both the EmployeeGroup and ManagerGroup imply the app specific employee role.

plan.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
     http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.-->
<!--$Rev: 497879 $ $Date: 2007-01-19 12:11:01 -0500 (Fri, 19 Jan 2007) $-->
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <dep:moduleId>
      <dep:groupId>org.apache.geronimo.samples.javaee5</dep:groupId>
      <dep:artifactId>timereport-tomcat</dep:artifactId>
      <dep:version>3.0-beta-1</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>org.apache.geronimo.samples</dep:groupId>
        <dep:artifactId>sample-datasource</dep:artifactId>
        <dep:version>3.0-beta-1</dep:version>
        <dep:type>car</dep:type>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>org.apache.geronimo.configs</dep:groupId>
        <dep:artifactId>jasper</dep:artifactId>
        <dep:version>3.0-beta-1</dep:version>
        <dep:type>car</dep:type>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>org.apache.geronimo.configs</dep:groupId>
        <dep:artifactId>tomcat7</dep:artifactId>
        <dep:version>3.0-beta-1</dep:version>
        <dep:type>car</dep:type>
      </dep:dependency>
    </dep:dependencies>
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
    <dep:private-classes/>
  </dep:environment>

    <context-root>timereport-jetty</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>

    <gbean name="DBInitialization" class="org.apache.geronimo.connector.wrapper.DatabaseInitializationGBean">
        <!--<attribute name="testSQL">select * from users</attribute>-->
        <attribute name="path">TimeReportDB.sql</attribute>
        <reference name="DataSource">
            <name>SampleTxDatasource</name>
        </reference>
    </gbean>

    <gbean name="TimeReportRealm" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
        <attribute name="realmName">TimeReportRealm</attribute>
        <reference name="ServerInfo">
            <name>ServerInfo</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" 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="dataSourceName">SampleNoTxDatasource</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:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
</web-app>

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

employee/index.jsp

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

Testing of the Sample Application

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

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.

Child pages

timereport - Web Application Security Sample