![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
The development of the Apache Geronimo application server is steadily advancing. As a result, more enterprise application developers are starting to take advantage of its benefits -- including its recent official J2EE 1.4 certification.
As with any Web server, protecting your directory by restricting access to it from arbitrary Web browsers is an essential part of security. This article shows you how to create a simple Web application that allows users to visit, log in, and then gain access to other areas on the site using Apache Geronimo. The article is geared toward small- to medium-sized applications, because it implements simple security by using the properties file login module. Directory access is controlled by deploying GBeans that specify a security deployment plan on Geronimo. Your application extends this deployment plan in the geronimo-web.xml file and creates security constraints in your web.xml file. This article uses the Apache Geronimo M5 release and assumes that you have no prior knowledge of Geronimo.
Get started with Apache Geronimo
To use Geronimo, you need Java 2 Platform, Standard Edition (J2SE) 1.4.2_08 (or later, but before 1.5). After you have the Java code installed, download Geronimo M5 from Apache (see Resources for a link to the Web site). Select either the .zip file (for Microsoft® Windows or Linux® operating systems) or the .tar.gz file (for the Linux operating system).
After the download completes, decompress the .zip or .tar.gz file. Now you're ready to start the server.
Go to the root directory of your Geronimo distribution in a console window, and execute the server.jar file by typing:
java -jar bin/server.jar |
The server starts to load all modules along with any other application modules (see Figure 1).
Figure 1. Starting Geronimo
Now you're ready to create the application.
This article contains an example application called XYZ Enterprise example application, which you can download. The application requires users to log in before they can access content. The site is composed of three easy-to-use Web pages. An index page at the root of the site acts as the main page of the Web site, a downloads area, and an area for administrators (hereafter called admin). First you need to learn the directory structure of the application.
Understand the directory structure
The application has a directory structure that holds all the elements of the application. Create a directory called secApp. This is the root directory of your application. Then create the following subdirectories to secApp:
- downloads (the downloads area)
- restricted (the admin area)
- verify (contains the login form and the invalid user/password page
- WEB-INF (contains .xml files needed by Geronimo for your application
The remainder of this article covers the contents of each of these directories.
The start page -- the first page shown when a visitor comes to the Web site -- points to other sections and activities available for users. Create a file called index.html at the root directory of your application (./secApp/index.html). Add HTML code to it, as shown in Listing 1.
Listing 1. The start page
<html><head><title>TylerCo.</title></head> <body> <h1>Welcome to TylerCo.</h1> There's a lot to do on this Web site.<br> The user's downloads area is <a href="downloads/">here</a>.<br> Administrators can log in <a href="restricted/">here</a>. </body> </html> |
This page displays two links that take users to the downloads area, and it also provides a link for admin users to log in. See Figure 2 for example browser output.
Figure 2. Displaying the start page
Now let's look at the downloads area.
The downloads area allows users to view pages or download available content. Create a file called index.html, and place it in the downloads directory. Add the HTML code, as shown in Listing 2.
Listing 2. The downloads area
<html><head><title>Welcome to TylerCo.</title></head> <body> <h1>DOWNLOADS AREA</h1> Welcome to the downloads area for registered users only!<br> Go back to the <a href="../">main page</a>. </body> </html> |
This page can be extended to contain links of files for download or other pages for users to view. A link to return to the main page is also displayed. See Figure 3 for example browser output of the downloads area.
Figure 3. Displaying the downloads area
Now let's look at the admin area.
The admin area exists to represent an area that would allow only users with administrative access to enter and perform any admin-related activities, like adding or approving new content for users. Create another file called index.html, and place it in the restricted directory (see Listing 3).
Listing 3. The admin page
<html><head><title>ADMIN</title></head> <body> <h1>HELLO ADMIN</h1> What would you like to do?<br> Go back to the <a href="../">main page</a>. </body> </html> |
This page can be extended to contain links that allow administrators to add, edit, approve, or remove content from the downloads area. See Figure 4 for example browser output of the downloads area.
Figure 4. Displaying the admin page
Next, find out how to set up security.
Geronimo secures directory access to sensitive data through a series of files. The first, a deployment plan defined by my-realm.xml, specifies a deployment plan your application adheres to in securing access. The web.xml file lists constraints and security roles that exist in your application as well as the roles that are allowed access to a certain directory. The geronimo-web.xml file defines which users or group of users comprise the security roles defined in the web.xml file.
A GBean is Geronimo's unique way of packaging objects, managing their life cycles, and expressing dependencies. In fact, the Geronimo kernel is totally independent of the specific modules loaded in the server. This modular approach makes Geronimo a highly scalable application server. A GBean is the interface that connects your deployment plan to Geronimo's kernel. GBeans have state, and they communicate and interact with other GBeans and the kernel, which is how your application authenticates users. Upon submitting a username and password, Geronimo interacts with your GBeans to authenticate a visiting user.
Next you configure your deployment plan using GBeans.
Your deployment plan is deployed and connected to Geronimo's kernel using GBeans. The file my-realm.xml defines three GBeans that coordinate authentication type, login usage, and the security realm users log in to. Create the file my-realm.xml, place it in the WEB-INF directory, and begin to define it, as shown in Listing 4.
Listing 4. The login properties GBean
<?xml version="1.0" encoding="UTF-8"?>
<configuration
xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"
configId="com/ibm/geronimo/security/myRealm"
parentId="org/apache/geronimo/Security"
>
<gbean name="my-login"
class="org.apache.geronimo.security.jaas.LoginModuleGBean">
<attribute name="loginModuleClass">
org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule
</attribute>
<attribute name="serverSide">true</attribute>
<attribute name="options">
usersURI=var/security/my_users.properties
groupsURI=var/security/my_groups.properties
</attribute>
<attribute name="loginDomainName">my-realm</attribute>
</gbean>
...
|
First you specify the configId of the deployment plan in the configuration tag, which extends the org.apache.geronimo.Security class specified by the parentId. Your application links to this deployment plan in the geronimo-web.xml file.
The first GBean (my-login) specifies the registered users and groups that are allowed directory access as defined in their respective property files. These files are checked when a user logs in and enters a username and password. This GBean is linked to the second GBean (my-realm, shown in Listing 5) through the loginDomainName attribute, specified in Listing 4.
Listing 5. The login domain name GBean (the realm)
...
</gbean>
<gbean name="my-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
<attribute name="realmName">my-realm</attribute>
<reference name="LoginModuleConfiguration">
<name>my-login</name>
</reference>
<reference name="ServerInfo">
<module>org/apache/geronimo/System</module>
<name>ServerInfo</name>
</reference>
<reference name="LoginService">
<module>org/apache/geronimo/Security</module>
<name>JaasLoginService</name>
</reference>
</gbean>
...
|
This my-realm GBean specifies the domain that users log in to and defines the System and Security modules. It links itself to the next GBean (my-login again) through the LoginModuleConfiguration, specified in Listing 6.
Listing 6. The login configuration GBean
...
</gbean>
<gbean name="my-login"
class="org.apache.geronimo.security.jaas.JaasLoginModuleUse">
<attribute name="controlFlag">REQUIRED</attribute>
<reference name="LoginModule">
<name>my-login</name>
</reference>
</gbean>
</configuration>
|
This last GBean (my-login) specifies login configuration properties. controlFlag specifies that for authentication to succeed, a valid result must be returned. This GBean links to the first GBean (same names) in Listing 4 through the LoginModule reference.
Next up is configuring security in the web.xml file.
Declarative J2EE security: web.xml
Now that you have the GBeans set up, you need to tie them to your application. Create a file called web.xml, place it in the WEB-INF directory, and begin to define it, as shown in Listing 7.
Listing 7. Specifying security roles
<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">
<security-role>
<role-name>registered-users</role-name>
</security-role>
<security-role>
<role-name>administrators</role-name>
</security-role>
...
|
This sets up the web.xml file by specifying the XML namespaces. However, security roles, shown in bold, are the focus here. There are two roles in your application: registered-users and administrators. Users in each role are specified later in the geronimo-web.xml file. Next, define the security constraints on directories, as shown in Listing 8.
Listing 8. Specifying security constraints
...
<role-name>administrators</role-name>
</security-role>
<security-constraint>
<web-resource-collection>
<web-resource-name>Registered Users</web-resource-name>
<url-pattern>/downloads/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>registered-users</role-name>
<role-name>administrators</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Administrators Only!</web-resource-name>
<url-pattern>/restricted/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>administrators</role-name>
</auth-constraint>
</security-constraint>
...
|
There are two constraints: one for the downloads directory and one for the restricted directory. The downloads directory gives both registered-users and administrators access, as defined within auth-constraint tags. Next you define the forms used for logging in, as shown in Listing 9.
Listing 9. Specifying login forms
...
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name>Jetty Realm</realm-name>
<form-login-config>
<form-login-page>/verify/login.html</form-login-page>
<form-error-page>/verify/loginError.html</form-error-page>
</form-login-config>
</login-config>
</web-app>
|
The form-login-page tag specifies the login page, while the form-error-login tag specifies the page to redirect users to when a username/password combination fails to authenticate.
Declarative J2EE security: geronimo-web.xml
You now have the three GBeans and the realm set up, and your security roles and constraints are defined. Now you need to define the role to user/group mappings. Create a file called geronimo-web.xml, place it in the WEB-INF directory, and define it, as shown in Listing 10.
Listing 10. Specifying role to user/group mappings
<?xml version="1.0" encoding="UTF-8"?>
<web-app
xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.0"
configId="com/ibm/geronimo/security/myApp"
parentId="com/ibm/geronimo/security/myRealm">
<context-root>/security</context-root>
<context-priority-classloader>false</context-priority-classloader>
<security-realm-name>my-realm</security-realm-name>
<security>
<default-principal realm-name="my-realm">
<principal class=
"org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
name="nobody"/>
</default-principal>
<role-mappings>
<role role-name="registered-users">
<realm realm-name="my-realm">
<principal class=
"org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
name="registeredUsers" designated-run-as="true"/>
</realm>
</role>
<role role-name="administrators">
<realm realm-name="my-realm">
<principal class=
"org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
name="admin"/>
<principal class=
"org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
name="root"/>
</realm>
</role>
</role-mappings>
</security>
</web-app>
|
First, take a look at the configId and parentId values. The configId specifies the name of your application, com/ibm/geronimo/security/myApp, and extends the realm you configured earlier: com/ibm/geronimo/security/myRealm. Next you set up the context, which is the directory where your application is placed once deployed on Geronimo.
Then the name of the realm that you're going to use is identified in the <security-realm-name> tag, which you already defined in the my-realm.xml file, and the mappings are defined in the <security> tag.
The default user mapping -- nobody -- is defined first. Then the role mappings are defined. Recall that you defined two security roles in the web.xml file. The first mapping maps all users in the registeredUsers group to the registered-users role. The second and last mapping maps the admin and root users to the administrators role. Next you'll define the users associated with the registeredUsers group as well as each user and their passwords.
Remember the user and group properties files that you referenced in Listing 4? The usernames and passwords that your application references when someone logs in are going to be stored in a users.properties and a groups.properties file. The users.properties file stores the usernames and passwords, while the groups.properties file stores the group names and the users associated with each group.
Now you need to define the properties. First, create a file called my_users.properties, and place it at the following location, rooted at your Geronimo distribution: ./var/security/my_users.properties. Define it as shown in Listing 11.
Listing 11. Defining users and their passwords
admin=imtheboss root=icandeleteanything bob=by joe=schmoe kris=sy john=doe nobody=nobody |
You have now specified the users and the passwords that are validated against when users try to log in later. Groups of users can also be defined. Create a file, my_groups.properties, and place it in the same directory as the my_users.properties file you just created:
bosses=admin,root registeredUsers=bob,joe,kris,john nobody=nobody |
The registeredUsers group is the group of interest, as it is the group associated with the registered-users role in your application. Thus, bob, joe, kris, and john are the registered users that can gain access to the downloads directory of your application.
Next you define the login pages.
In Listing 9 you specified the forms used when a user requests access to either of the restricted directories. Now you get to define them.
Users are redirected to the login page when they click the downloads area link on the start page. Create a file, login.html, place it in the verify directory, and define it, as shown in Listing 12.
Listing 12. Login page
<html> <h1>LOGIN</h1> <form method="POST" action="j_security_check"> Username:<br> <input size="20" name="j_username"> <br><br> Password:<br> <input size="20" name="j_password" type="password"> amp;nbsp;amp;nbsp;<input name="submit" type="submit" value="Login"> </form> </html> |
This form is written using J2EE security. A form with the j_security_check as the action tells Geronimo that authentication is form based. j_username specifies the username of the user requesting a security check, and j_password is the password. Submitting the form sends the data to Geronimo, which connects to your GBeans and authenticates the user. See Figure 5 for example browser output.
Figure 5. Displaying the login page
Next, define the login error page.
This is the page that users are redirected to when their user/password combination fails to authenticate. Create a page, loginError.html, place it in the same directory as the login.html file. Then verify and define it, as shown in Listing 13.
Listing 13. Login error page
<html> <h1>ERROR</h1> UNABLE TO VERIFY:<br> INVALID username or password. </html> |
A simple page is shown to users, communicating that they entered an invalid user/password combination (see Figure 6).
Figure 6. Displaying the error page
Congratulations, your application is complete! Next you test it by deploying it on Geronimo.
Test your application by first deploying the security plan onto the server and then by deploying your application.
Deploying and connecting the security deployment plan to Geronimo allows your application to later extend and use the security configuration contained therein. Go to the root directory of your Geronimo installation in a new console window. Type the following to deploy the deployment plan:
java -jar bin/deployer.jar --user system --password manager
deploy ../secApp/WEB-INF/my-realm.xml
|
This command executes the deployer.jar file by passing in the default user and password combination and by executing the deploy command, passing in your my-realm.xml file as the file to deploy. Geronimo indicates a successful deployment by outputting:
Deployed com/ibm/geronimo/security/myRealm |
It has taken the configId of your deployment plan, and deployed it on Geronimo! You can now use it in your application.
Next you get to deploy and test your application on Geronimo. First, however, you need to archive it in a .war file. Open another console window, and go to the root directory of your application, the secApp directory. Create a .war file of your application by typing the following command:
jar cvf security.war downloads verify WEB-INF restricted index.html |
This places all the files of your application into a .war file, security.war, which Geronimo reads. Deploy your application on Geronimo by typing:
java -jar bin/deployer.jar --user system --password manager
deploy ../secApp/security.war
|
Your application is now deployed on Geronimo. Geronimo communicates successful deployment by outputting something similar to:
Deployed com/ibm/geronimo/security/myApp @ http://your-a9279112e3:8080/security |
The application is deployed and ready for testing.
Test you application by visiting the Web site you just created. Open a Web browser, and point it to the URL http://localhost:8080/security/. The start page should load, as shown in Figure 2.
Now click the link that takes you to the user's downloads area. The login page should now load, as shown in Figure 5. Enter a username with password, as defined in the my_user.properties file you created earlier (see Figure 7).
Figure 7. Logging in
After you click Login, the downloads page loads. Click the link to return to the main page. Now click the link that takes you to the administrators login area. Example browser output is shown in Figure 8.
Figure 8. Forbidden
Bob is allowed access to the downloads area, but because he isn't the admin or root user, he is forbidden access to the security directory. The registered-users role is working!
To test the administrators role, you need to log out by closing and reopening your browser. Doing so resets all the login information. Now you can test the administrators role. Click the link that takes you to the administrator login area (you may have to reload the page by pressing Shift and clicking Reload). This takes you to the same login page, except this time you enter a different username/password combination (see Figure 9).
Figure 9. Logging in as root
The admin page loads as expected. Now go back to the main page, and go to the downloads area. The downloads area page also loads as expected. The administrators role is working!
Congratulations! You've learned how to create and deploy an application on the Apache Geronimo application server, securing directory content from unauthorized access. By allowing access only to certain users, you build in another level of security to your operations.
| Description | Name | Size | Download method |
|---|---|---|---|
| XYZ Enterprise example application | source.zip | 4 KB |
HTTP
 |
Download Director
|
Information about download methods
Learn
- Find helpful resources for beginners and experienced users at the Get started with Geronimo section of developerWorks.
- Learn about various Apache Geronimo security topics in the article "Build a secure enterprise infrastructure with Geronimo" (developerWorks, July 2005).
- Browse the following topics in the online book Apache Geronimo Development and Deployment by Aaron Mulder:
- Join one or more of the mailing lists at the Apache Geronimo Web site.
- Read the following developerWorks articles for more information about developing with Apache Geronimo:
- "Building a better J2EE server, the open source way" (developerWorks, May 2005)
- "Geronimo! Part 1: The J2EE 1.4 engine that could" (developerWorks, May 2005)
- "Geronimo! Part 2: Tame this J2EE 1.4 bronco" (developerWorks, May 2005)
- "Three ways to connect a database to a Geronimo application server" (developerWorks, June 2005)
- "Create, deploy, and debug Apache Geronimo applications" (developerWorks, May 2005)
- "Apache Geronimo uncovered" (developerWorks, August 2005)
- Check out the IBM Support for Apache Geronimo offering, which lets you develop Geronimo applications backed by world-class IBM support.
- Go to the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today.
- Visit the developerWorks developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
- Get information on the announcement of IBM WebSphere® Application Server Community Edition, as well as resources on other WebSphere products and technologies, at the developerWorks WebSphere home page.
Get products and technologies
- Download Apache Geronimo M5 from the Apache Software Foundation.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
Discuss
- Get involved in the developerWorks Apache Geronimo community by participating in the
Focus on Apache Geronimo forum.
- Stay up to date on Geronimo developments at the Apache Geronimo blog.
Table of contents
Next steps from IBM
Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).
- Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
- Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
- Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
- Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
- Buy: Rational Application Developer
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
