Example: Basic Authentication with a Servlet

This example explains 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 his or her name and password, the server determines whether 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 ones 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/security/hello2_basicauth/.

1. Follow the steps in To Set 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 annotations to the servlet. The security annotations are described in Specifying Security for Basic Authentication Using Annotations.

4. Build, package, and deploy the web application by following the steps in To Build, Package, and Deploy the Servlet Basic Authentication Example Using NetBeans IDE or To Build, Package, and Deploy the Servlet Basic Authentication Example Using Ant.

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

Specifying Security for Basic Authentication Using Annotations

The default authentication mechanism used by the GlassFish Server is basic authentication. With basic authentication, the GlassFish Server spawns a standard login dialog to collect user name and password data for a protected resource. Once the user is authenticated, access to the protected resource is permitted.

To specify security for a servlet, use the @ServletSecurity annotation. This annotation allows you to specify both specific constraints on HTTP methods and more general constraints that apply to all HTTP methods for which no specific constraint is specified. Within the @ServletSecurity annotation, you can specify the following annotations:

• The @HttpMethodConstraint annotation, which applies to a specific HTTP method

• The more general @HttpConstraint annotation, which applies to all HTTP methods for which there is no corresponding @HttpMethodConstraint annotation

Both the @HttpMethodConstraint and @HttpConstraint annotations within the @ServletSecurity annotation can specify the following:

• A transportGuarantee element that specifies the data protection requirements (that is, whether or not SSL/TLS is required) that must be satisfied by the connections on which requests arrive. Valid values for this element are NONE and CONFIDENTIAL.

• A rolesAllowed element that specifies the names of the authorized roles.

For the hello2_basicauth application, the GreetingServlet has the following annotations:

@WebServlet(name = "GreetingServlet", urlPatterns = {"/greeting"})
@ServletSecurity(
@HttpConstraint(transportGuarantee = TransportGuarantee.CONFIDENTIAL,
    rolesAllowed = {"TutorialUser"}))

These annotations specify that the request URI /greeting can be accessed only by users who 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.

To Build, Package, and Deploy the Servlet Basic Authentication Example Using NetBeans IDE

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

2. In NetBeans IDE, select File->Open Project.

3. In the Open Project dialog, navigate to:

   tut-install/examples/security

4. Select the hello2_basicauth folder.

5. Select the Open as Main Project check box.

6. Click Open Project.

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

   This option builds and deploys the example application to your GlassFish Server instance.

To Build, Package, and Deploy the Servlet Basic Authentication Example Using Ant

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

2. In a terminal window, go to:

   tut-install/examples/security/hello2_basicauth/

3. Type the following command:

   ant

   This command calls the default target, which builds and packages the application into a WAR file, hello2_basicauth.war, that is located in the dist directory.

4. Make sure that the GlassFish Server is started.

5. To deploy the application, type the following command:

   ant deploy

To Run the Basic Authentication Servlet

1. In a web browser, navigate to the following URL:

   https://localhost:8181/hello2_basicauth/greeting

   You may be prompted to accept the security certificate for the server. If so, accept the security certificate. If the browser warns that the certificate is invalid because it is self-signed, add a security exception for the application.

   An Authentication Required dialog box appears. Its appearance varies, depending on the browser you use. Figure 25–6 shows an example.

   Figure 25–6 Sample Basic Authentication Dialog Box

   
   

2. Type a user name and password combination that corresponds to a user who has already been created in the file realm of the GlassFish Server and has been assigned to the group of TutorialUser; then click OK.

   Basic authentication is case sensitive for both the user name and password, so type the user name and password exactly as defined for the GlassFish Server.

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

   • A user with the user name you entered is defined for the GlassFish Server.

   • 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 TutorialUser on the GlassFish Server.

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

   When these conditions are met and the server has authenticated the user, the application will appear as shown in Figure 3–2 but with a different URL.

3. Type a name in the text field 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 3–3 but with a different URL.

Next Steps

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