HOME / Docs & Support / NetBeans 6.0 / Web Application Documentation

Securing a Web Application in NetBeans IDE 6.1

Contributed by Dan Kolar

This document takes you through the basics of adding security to a web application that is deployed to either the Tomcat server or the Sun Java System Application Server.

This document shows you how to configure security authentication using a basic login window and also using a login form in a web page. This document takes you through the steps for creating users on the Tomcat server and Sun Java System Application Server (GlassFish). After creating the users, you then create the security roles by setting the security properties in the deployment descriptor. This document also shows how you can use JDBC authentication to secure your application when deploying to the Sun Java System Application Server (GlassFish).

Note: This document uses the NetBeans IDE 6.1 Release. If you are using NetBeans IDE 6.5, see Securing a Web Application in NetBeans IDE 6.5.

Contents

Content on this page applies to NetBeans IDE 6.0 and 6.1

Installing and Configuring the Working Environment
Creating the Web Application
Creating Users and Roles on the Target Server
- Defining Roles on Tomcat Web Server
- Defining Roles on Sun Java System Application Server
Configuring the Login Method
Configuring Security Deployment Descriptors
Deploying and Running the Application

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	Version 6.1 or 6.0
Java Developer Kit (JDK)	Version 6 or version 5
JavaServer Faces Components/ Java EE Platform	1.2 with Java EE 5* or 1.1 with J2EE 1.4
Travel Database	Not Required
Application Server	Tomcat or GlassFish V2

Notations Used in the Tutorial

<NETBEANS_HOME> - NetBeans IDE installation directory
<APPSERVER_HOME> - Sun Java System Application Server or GlassFish installation directory
<TOMCAT_HOME> - Tomcat installation directory
<PROJECT_HOME> - directory containing your project

Installing and Configuring the Working Environment

Install and start NetBeans IDE 6.0 or 6.1. You can do this tutorial using the bundled Tomcat server or GlassFish V2.

If you are using the Sun Java System Application Server (GlassFish), make sure the server is installed and a server instance is registered with the IDE. You can use the Server Manager to register the server instance. (Choose Tools > Servers > Add Server. Select "GlassFish V2" and click Next. Click Browse and locate the installation directory of the application server. Click Finish.)

Creating the Web Application

In this excercise you first create the web application project and the directory structure. You then create some simple html files in each of the secure directories. The web application uses a basic login authentication for accessing the secure directories. If you want to use a login form for authentication, you can add a jsp page with the form.

Creating the Secure Directories

Choose File > New Project (Ctrl-Shift-N), select Web Application from the Web category, and click Next.
Name the project WebApplicationSecurity. Accept the default settings and click Next.
Note: If you are using NetBeans 6.0, select the GlassFish V2 application server and continue to step 4.
Select the server to which you want to deploy your application. Only servers that are registered with the IDE are listed.
You do not need to add a framework, so click Finish.
In the Projects window of the IDE, right-click Web Pages and choose New > Other.
In the New File wizard, select Other as Category and Folder as File Type.
In the New Folder wizard, name the folder secureAdmin and click Finish.
Repeat steps 5, 6, and 7 to create another folder named secureUser.
Create a new html file in the secureUser folder by right-clicking the folder secureUser in the Projects window and choosing New > HTML.
Name the new file pageU and click Finish.
When you click Finish, the file pageU.html opens in the Source Editor.

In the Source Editor, replace the existing code in pageU.html with the following code.

<html>
   <head>
      <title>User secure area</title>
   </head>
   <body>
      <h1>User Secure Area</h1>
   </body>
</html>

Right-click the secureAdmin folder and create a new html file named pageA.

In the Source Editor, replace the existing code in pageA.html with the following code.

<html>
   <head>
      <title>Admin secure area</title>
   </head>
   <body>
      <h1>Admin secure area</h1>
   </body>
</html>

Creating the JSP Index Page

You now create the JSP index page containing links to the secure areas. When the user clicks on the link they are prompted for the username and password. If you use a basic login, they are prompted by the default browser login window. If you use a login form page, the user enters the username and password in a form.

Open index.jsp in the Source Editor and add the following links to pageA.html and pageU.html:

<p>Request a secure Admin page <a href="secureAdmin/pageA.html">here!</a></p>
<p>Request a secure User page <a href="secureUser/pageU.html" >here!</a></p>

Save your changes.

Creating a Login Form (optional)

If you want to use a login form instead of the basic login, you can create a jsp page containing the form. You then specify the login and error pages when configuring the login method.

In the Projects window, right-click the folder Web Pages and choose New > JSP.
Name the file login, leave the other fields at their default value and click Finish.

In the Source Editor, add the following code to the top of login.jsp.

<%@taglib uri="http://java.sun.com/jstl/core" prefix="c" %>

In the Source Editor, insert the following code between the <body> tags of login.jsp.

          <form action="j_security_check" method="POST">
              Username:<input type="text" name="j_username"><br>
              Password:<input type="password" name="j_password">
              <input type="submit" value="Login">
          </form>

Create a new html file named loginError.html in the Web Pages folder. This is a simple error page.

In the Source Editor, replace the existing code in loginError.html with the following code.

<html>
    <head>
        <title>Login Test: Error logging in</title>
    </head>
    <body>
        <h1>Error Logging In</h1>
        <br/>
    </body>
</html>

Creating Users and Roles on the Target Server

To be able to use user/password authentication (basic login or form-based login) security in web applications, the users and their appropriate roles have to be defined for the target server. To log in to a server, the user account has to exist on that server.

How you define the users and roles varies according to the target server you specified. In this tutorial the users admin and tomcat are used to test the security setup. You need to confirm that these users exist on the respective servers, and that the appropriate roles are assigned to the users.

Defining Roles on the Sun Java System Application Server (GlassFish)

The Sun Java System Application Server (GlassFish) has one pre-defined user named admin, which is used for accessing the Admin Console. For this scenario you first need to use the Admin Console of the Sun Java System Application Server to create two new users named user and admin. user will have limited access to the application, admin will have administration privileges. You then need to map these users to roles by modifying sun-web.xml. sun-web.xml is located in the Configuration Files directory of your project.

Open the Admin Console by right-clicking Servers > GlassFish V2 in the Services window of the IDE. The login page for the Sun Java System Application Server opens in your browser window. You need to log in using the admin username and password to access the Admin Console.

Note: The Application Server must be running before you can access the Admin Console. To start the server, right-click the GlassFish V2 node and choose Start.
In the Admin Console, navigate to Configuration > Security > Realms. Click New.
Type file as the name of the realm and click OK.
Select the file realm and choose Manage Users.
Click New to add a new user. Type user as the user ID and user as the password. Click OK.
Follow the previous steps ot create a user named admin in the file realm.

Defining Roles on the Tomcat Web Server

The Tomcat server bundled with the IDE already has some pre-defined users and roles.

The basic users and roles for the Tomcat server are defined in tomcat-users.xml. You can find tomcat-users.xml in your <USER_DIR>\apache-tomcat-5.5.17_base\conf directory. Your tomcat-users.xml file should like similar to this:

<tomcat-users>
    <role rolename="tomcat"/>
    <role rolename="role1"/>
    <role rolename="manager"/>
    <role rolename="admin"/>
    <user username="ide" password="(generated password)" roles="manager,admin"/>
    <user username="tomcat" password="tomcat" roles="tomcat"/>
    <user username="role1" password="tomcat" roles="role1"/>
    <user username="both" password="tomcat" roles="tomcat,role1"/>
</tomcat-users>

Note: The password for the user ide is generated when Tomcat is installed. You can change the password for the user ide, or copy the password in tomcat-users.xml.

Configuring the Login Method

When configuring the login method for your application, you can use the login window provided by your browser for basic login authentication. Alternatively, you can create a web page with a login form. Both types of login configuration are based on user/password authentication.

You configure the login method for the application by configuring web.xml. The web.xml file can be found in the Configuration Files directory of the Projects window.

When you use the basic login configuration, the login window is provided by the browser. A valid username and password is needed to access the secure content.

The following steps show how to configure a basic login for the Sun Java System Application Server.

In the Projects window, double-click web.xml located in the Configuration Files directory to open the file in the Visual Editor.
Click Security in the toolbar to open the file in Security view.
Expand the Login Configuration node and set the Login Configuration to Basic.
Note: If you want to use a form , select Form sintead of basic and specify the login and login error pages.
Enter file as the Realm Name. This corresponds to the realm name where you created the users on the Sun Java System Application Server.
Expand the Security Roles node and click Add to add a role name.
Add the following Security Roles:
- Admin. Users added to this role will have access to the secureAdmin directory of the server.
- User. Users added to this role will have access to the secureUser directory of the server.
Create and configure a security constraint named AdminConstraint by doing the following:
1. Click Add Security Constraint to create a new security constraint.
2. Enter AdminConstraint for the Display Name of the new security constraint.
3. Click Add to add a Web Resource Collection.
4. In the Add Web Resource dialog box, set the Resource Name to Admin and the URL Pattern to /secureAdmin/* and click OK.
  
  Note: When you use an asterisk (*), you are giving the user access to all files in that folder.
5. Select Enable Authentication Constraint and click Edit to edit the Role Name field.
6. In the Edit Role Names dialog box, select Admin in the left pane, click Add and then click OK.
Create and configure a security constraint named UserConstraint by doing the following:
1. Click Add Security Constraint to create a new security constraint.
2. Enter UserConstraint for the Display Name of the new security constraint.
3. Click Add to add a Web Resource Collection.
4. In the Add Web Resource dialog box, set the Resource Name to User and the URL Pattern to /secureUser/* and click OK.
5. Select Enable Authentication Constraint and click Edit to edit the Role Name field.
6. In the Edit Role Names dialog box, select Admin and User in the left pane, click Add and then click OK.
  After completing the above steps, the result should resemble the following figure:

Note: You can also set the timeout for the session in web.xml. To set the timeout, click the General tab of the Visual Editor and specify how long you want the session to last. The default is 30 minutes.

Configuring Security Deployment Descriptors

If you are deploying your application to the Sun Java System Application Server (GlassFish), you need to configure the security deployment descriptors in sun-web.xml to map the security roles defined in web.xml. Note that the values you entered in web.xml are displayed in sun-web.xml. sun-web.xml pulls these values from web.xml for you.

Double-click sun-web.xml located in the Configuration Files directory in the Projects window.
Select the Security tab to reveal the security roles.
Select the Admin security role node to open the Security Role Mapping pane.
Click Add Principal and enter admin for the principal name. Click OK.
Select the User security role node to open the Security Role Mapping pane.
Click Add Principal and enter user for the principal name. Click OK
Save your changes to sun-web.xml.

You can also view and edit sun-web.xml in the XML editor by clicking Edit As XML in the top right corner of the Sun Web Application visual editor. If you open sun-web.xml in the XML editor, you can see that sun-web.xml has the following security role mapping information:

<security-role-mapping>
    <role-name>Admin</role-name>
    <principal-name>admin</principal-name>
</security-role-mapping>
<security-role-mapping>
    <role-name>User</role-name>
    <principal-name>user</principal-name>
</security-role-mapping>

Deploying and Running the Application

In the Projects window, right-click the project node and choose Run. After building and deploying the application to the server, the start page opens in your web browser. Choose the secure area which you want to access by clicking either admin or user.

After supplying the user and password, there are three possible results:

Password for this user is correct and user has privileges for secured content -> secure content page is displayed
Password for this user is incorrect -> Error page is displayed
Password for this user is correct, but user does not have right to access the secured content -> browser displays Error 403 Access to the requested resource has been denied

Summary

In this tutorial, you created a secure web application. You edited security settings using the web.xml and sun-web.xml Descriptor editors, creating web pages with secure logins and multiple identities.