corner imagecorner image
IDEPlatformPluginsDocs & SupportCommunityPartners

Securing a Web Application in NetBeans IDE

Contributed by Dan Kolar, Maintained by James Branam and Jeff Rubinoff

This document takes you through the basics of adding security to a web application that is deployed to either the Tomcat server or the GlassFish 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 the GlassFish server . 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 GlassFish server .

Expected duration: 40 minutes

Contents

Content on this page applies to NetBeans IDE 6.7

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

Software or Resource Version Required
NetBeans IDE Java version
Java Developer Kit (JDK) Version 6 or version 5
Java EE Platform Java EE 5 or 6 or J2EE 1.4
Travel Database Not Required
Java EE-compliant web or application server Tomcat web server 6.0 and/or
GlassFish Server Open Source Edition 2.1 or 3.0.1

 

Notations Used in the Tutorial

<NETBEANS_HOME> - NetBeans IDE installation directory
<APPSERVER_HOME> - the GlassFish server installation directory
<TOMCAT_HOME> - Tomcat installation directory
<PROJECT_HOME> - directory containing your project
<USER_DIR> - Your NetBeans user directory. For example, on Vista this is C:/Users/name/.netbeans.

 

Installing and Configuring the Working Environment

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

If you are using the GlassFish server, make sure the server is installed and a server instance is registered with the IDE. You can use the Server Manager to register an installed server instance. (Choose Tools > Servers > Add Server. Select "the GlassFish server <version number>" 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

  1. Choose File > New Project (Ctrl-Shift-N), select Java Web Application from the Web category, and click Next.
  2. Name the project WebApplicationSecurity. Accept the default settings.
  3. (Optional) Select the Use Dedicated Folder for Storing Libraries checkbox and specify the location for the libraries folder. See Sharing Project Libraries for more information on this option.
  4. Click Next.
  5. Select the server to which you want to deploy your application. Only servers that are registered with the IDE are listed. Click Next.
  6. You do not need to add a framework, so click Finish.
  7. If you created an EE 6 application, go to the Projects window of the IDE, right-click the project's node and select New > Standard Deployment Descriptor (web.xml). This tutorial shows how to configure security in the deployment descriptor, but EE 6 applications use annotations instead of a deployment descriptor, by default.
  8. In the Projects window of the IDE, right-click Web Pages and choose New > Other.
  9. In the New File wizard, select Other as Category and Folder as File Type. Click Next.

  10. In the New Folder wizard, name the folder secureAdmin and click Finish.

    The secureAdmin folder appears in the Projects window in the Web Pages folder.
  11. Repeat steps 7, 8, and 9 to create another folder named secureUser.
  12. Create a new html file in the secureUser folder by right-clicking the folder secureUser in the Projects window and choosing New > HTML.
  13. Name the new file pageU and click Finish.

    When you click Finish, the file pageU.html opens in the Source Editor.

  14. 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>
  15. Right-click the secureAdmin folder and create a new html file named pageA.
  16. 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.

  1. 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>
  2. Save your changes.

Creating a Login Form (required for Tomcat, optional for the GlassFish server)

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.

Important: Tomcat users must create a login form.

  1. In the Projects window, right-click the folder Web Pages and choose New > JSP.
  2. Name the file login, leave the other fields at their default value and click Finish.
  3. 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>
  4. Create a new html file named loginError.html in the Web Pages folder. This is a simple error page.
  5. 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, user, and ide 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 GlassFish server

The GlassFish server 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 GlassFish server to create two new users named user and admin. The user named 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. The sun-web.xml file is located in the Configuration Files directory of your project.

Note: If you are using GlassFish version 3.1, the file is called glassfish-web.xml.

  1. Open the Admin Console by right-clicking Servers > the GlassFish server 2.1 > View Admin Console in the Services window of the IDE. The login page for the GlassFish 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 server 2.1 node and choose Start.

  2. In the Admin Console, navigate to Configuration > Security > Realms.
  3. Select the file realm, and in the Edit Realm screen click Manage Users.
  4. Click New to add a new user. Type user as the user ID and user as the password. Click OK.
  5. Follow the previous steps to create a user named admin in the file realm.

Defining Roles on the Tomcat Web Server

The Tomcat server bundled with the IDE has the ide user defined with a password and the administrator and manager 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-6.0.x_base\conf directory. Your tomcat-users.xml file should like similar to this:

<tomcat-users>
<!--
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="role1" password="tomcat" roles="role1"/>
-->
<user username="ide" password="xxxxxxxx" roles="manager,admin"/>
</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.

Add a user role and a user named user, with password tomcat and role user. The tomcat-users.xml file now looks like this:

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

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.

Basic Login

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 GlassFish server. Tomcat users need to use form login.

  1. In the Projects window, double-click web.xml located in the Configuration Files directory to open the file in the Visual Editor.
  2. Click Security in the toolbar to open the file in Security view.
  3. Expand the Login Configuration node and set the Login Configuration to Basic.

    Note: If you want to use a form , select Form instead of basic and specify the login and login error pages.

  4. Enter file as the Realm Name. This corresponds to the realm name where you created the users on the GlassFish server.

    Login Configuration
  5. Expand the Security Roles node and click Add to add a role name.
  6. 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.
  7. 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.

      Add Web Resource dialog box
    5. Select Enable Authentication Constraint and click Edit. The Edit Role Names dialog opens.
    6. In the Edit Role Names dialog box, select Admin in the left pane, click Add and then click OK.

      After completing the above steps, the result should resemble the following figure:

      Admin and User Constraints
  8. 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.
    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.

    Form Login

    Using a form for login enables you to customize the content of the login and error pages. The steps for configuring authentication using a form are the same as for the basic login configuration, except that you specify the login and error pages you created.

    The following steps show how to configure a login form

    1. In the Projects window, double-click web.xml located in the Web Pages/WEB-INF directory to open the file in the Visual Editor.
    2. Click Security in the toolbar to open the file in Security view and expand the Login Configuration node.
    3. Set the Login Configuration to Form.
    4. Set the Form Login Page by clicking Browse and locating login.jsp.

    5. Set the Form Error Page by clicking Browse and locating loginError.html.

      Setting up login forms in web.xml
    6. GlassFish Users: Enter file as the Realm Name. This corresponds to the realm name where you created the users on the GlassFish server. Tomcat users do not enter a realm name.
    7. Expand the Security Roles node and click Add to add a role name.
    8. Add the following Security Roles:
      GlassFish server role Tomcat role(case-sensitive) Description
      Admin admin Users added to this role have access to the secureAdmin directory of the server.
      User user Users added to this role have access to the secureUser directory of the server.
    9. 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.

        Add Web Resource dialog box
      5. Select Enable Authentication Constraint and click Edit. The Edit Role Names dialog opens.
      6. In the Edit Role Names dialog box, select Admin in the left pane, click Add and then click OK.

        After completing the above steps, the result should resemble the following figure:

        Admin and User Constraints
    10. 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.
      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 GlassFish server , 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.

  1. Double-click sun-web.xml located in the Configuration Files directory in the Projects window.
  2. Select the Security tab to reveal the security roles.
  3. Select the Admin security role node to open the Security Role Mapping pane.

  4. Click Add Principal and enter admin for the principal name. Click OK.

    Add Principal dialog box
  5. Select the User security role node to open the Security Role Mapping pane.
  6. Click Add Principal and enter user for the principal name. Click OK
  7. 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.

Note: By default, the project has been created with the Compile on Save feature enabled, so you do not need to compile your code first in order to run the application in the IDE. For more information on the Compile on Save feature, see the Compile on Save section of the Creating, Importing, and Configuring Java Projects guide.

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.

Deployed Application 1

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

    User Secure Area

  • Password for this user is incorrect -> Error page is displayed

    Login Error Page

  • 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

    Access 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.


See Also


This page was last modified: June 18, 2009