test

The Java EE 6 Tutorial, Volume I

Example: Basic Authentication with a Servlet

This example discusses how to use basic authentication with a servlet. With basic authentication of a servlet, the web browser presents a standard login dialog that is not customizable. When a user submits their name and password, the server determines if the user name and password are those of an authorized user and sends the requested web resource if the user is authorized to view it.

    In general, the following steps are necessary for adding basic authentication to an unsecured servlet, such as the one described in Chapter 3, Getting Started with Web Applications. In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. The completed version of this example application can be found in the directory tut-install/examples/web/hello2_basicauth/.

  1. Follow the steps in Setting Up Your System for Running the Security Examples.

  2. Create a web module as described in Chapter 3, Getting Started with Web Applications for the servlet example, hello2.

  3. Add the appropriate security elements to the web.xml deployment descriptor. The deployment descriptor for the example application can be viewed at tut-install/examples/web/hello2_basicauth/web/WEB-INF/web.xml. The security elements are described in Specifying Security in the Deployment Descriptor.

  4. Build, package, and deploy the web application by following the steps in Building, Packaging, and Deploying the Servlet Basic Authentication Example Using NetBeans IDE or Building, Packaging, and Deploying the Servlet Basic Authentication Example Using Ant.

  5. Run the web application by following the steps described in Running the Basic Authentication Servlet.

  6. If you have any problems running this example, refer to the troubleshooting tips in Troubleshooting the Basic Authentication Example.

Specifying Security in the Deployment Descriptor

The elements of the deployment descriptor that add basic authentication to this example tells the server or browser to perform the following tasks:

Deployment descriptors elements are described in Introduction to Web Application Deployment Descriptors.

The following sample code shows the security elements for the deployment descriptor used in this example of basic authentication, which can be found in tut-install/examples/web/hello2_basicauth/web/WEB-INF/web.xml.

    <security-constraint>
        <display-name>SecurityConstraint</display-name>
        <web-resource-collection>
             <web-resource-name>WRCollection</web-resource-name>
            <url-pattern>/greeting</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>TutorialUser</role-name>
        </auth-constraint>
        <user-data-constraint>
             <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>
    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>file</realm-name>
    </login-config>
		<security-role>
			<role-name>TutorialUser</role-name>
		</security-role>

This deployment descriptor shows that all the request URI /greeting can only be accessed by users who have entered their user name and password and have been authorized to access this URL because they have been verified to be in the role TutorialUser. The data will be sent over a protected transport in order to keep the user name and password data from being read in transit.

Building, Packaging, and Deploying the Servlet Basic Authentication Example Using NetBeans IDE

    To build, package, and deploy the web/hello2_basicauth example application using NetBeans IDE, follow these steps:

  1. Follow the steps in Setting Up Your System for Running the Security Examples.

  2. Open the project in NetBeans IDE by selecting File->Open Project.

  3. Browse to the tut-install/examples/web/hello2_basicauth/ directory.

  4. Make sure that Open as Main Project is selected.

  5. Select Open Project.

  6. Right-click hello2_basicauth in the Projects pane, then select Clean and Build.

  7. Right-click hello2_basicauth in the Projects pane, then select Deploy.

  8. To run the servlet, follow the steps in Running the Basic Authentication Servlet.

Building, Packaging, and Deploying the Servlet Basic Authentication Example Using Ant

    To build, package, and deploy the web/hello2_basicauth example using the Ant tool, follow these steps:

  1. Follow the steps in Setting Up Your System for Running the Security Examples.

  2. From a terminal window or command prompt, change to the tut-install/examples/web/hello2_basicauth/ directory.

  3. Build and package the web application by entering the following command at the terminal window or command prompt:


    ant

  4. To deploy the example using Ant, enter the following command at the terminal window or command prompt:


    ant deploy

    The deploy target in this case gives you an incorrect URL to run the application. To run the application, please use the URL shown in Running the Basic Authentication Servlet.

  5. To run the web application, follow the steps in Running the Basic Authentication Servlet.

Running the Basic Authentication Servlet

    To run the web client, follow these steps:

  1. Open a web browser.

  2. Enter the following URL in your web browser:

    https://localhost:8181/hello2_basicauth/greeting

    You may be prompted to accept the security certificate for the server. If so, accept the security certificate.

  3. A default login form displays. Enter a user name and password combination that corresponds to a user that has already been created in the file realm of the Enterprise Server and has been assigned to the group of TutorialUser.

    Basic authentication is case-sensitive for both the user name and password, so enter the user name and password exactly as defined for the Enterprise Server.

    The server returns the requested resource if all of the following conditions are met:

    • There is a user defined for the Enterprise Server with the user name you entered.

    • The user with the user name you entered has the password you entered.

    • The user name and password combination you entered is assigned to the group of TutorialUser on the Enterprise Server.

    • The role of TutorialUser, as defined for the application, is mapped to the group of TutorialUser, as defined for the Enterprise Server.

    When these conditions are met, and the server has authenticated the user, the application will display as shown in Figure 25–6.

  4. Enter your name and click the Submit button. Because you have already been authorized, the name you enter in this step does not have any limitations. You have unlimited access to the application now.

    The application responds by saying “Hello” to you, as shown in Figure 25–7.

Figure 25–6 Running the Application

Screen shot of running basic authentication example showing text field for user to type name

Figure 25–7 The Running Basic Authentication Response

Screen shot of running basic authentication example showing response

Note –

For repetitive testing of this example, you may need to close and reopen your browser. You should also run the ant clean and ant undeploy targets or the NetBeans IDE Clean and Build option to get a fresh start.

Troubleshooting the Basic Authentication Example

    When doing iterative development with this web application, follow these steps if you are using NetBeans IDE:

  1. Close your web browser.

  2. Clean and recompile the files from the previous build by right-clicking hello2_basicauth and selecting Clean and Build.

  3. Redeploy the application by right-clicking hello2_basicauth and selecting Undeploy and Deploy.

  4. Open your web browser and reload the following URL:

    https://localhost:8181/hello2_basicauth/greeting

    Follow these steps if you are using the Ant tool:

  1. Close your web browser.

  2. Undeploy the web application. To undeploy the application, use the following command in the directory:


    ant undeploy

  3. Clean out files from the previous build, using the following command:


    ant clean

  4. Recompile, repackage, and redeploy the application, using the following commands:


    ant 
ant deploy

  5. Open your web browser and reload the following URL:

    https://localhost:8181/hello2_basicauth/greeting