Web-Tier Security

The Java^TM Web Services Tutorial

Web-Tier Security

The following sections address protecting resources and authenticating users in the Web tier.

Protecting Web Resources

You can protect Web resources by specifying a security constraint. A security constraint determines who is authorized to access a Web resource collection, a list of URL patterns and HTTP methods that describe a set of resources to be protected. Security constraints can be defined using deploytool, as described in Controlling Access to Web Resources.

If you try to access a protected Web resource as an unauthenticated user, the Web container will try to authenticate you. The container will only accept the request after you have proven your identity to the container and have been granted permission to access the resource.

Security constraints only work on the original request URI, not on calls made via a RequestDispatcher (which include <jsp:include> and <jsp:forward>). Inside the application, it is assumed that the application itself has complete access to all resources and would not forward a user request unless it had decided that the requesting user had access also.

Controlling Access to Web Resources

Use the following procedure in deploytool to specify a security constraint to control access to a Web resource.

Select the WAR containing the Web resource.
Select the Security tabbed pane.
Select Basic for the type of User Authentication. The types of User Authentication techniques are discussed in Authenticating Users of Web Resources.
Select the Add button in the Security Constraints section of the screen. A Security Constraint is added to the application.
Select the Add button adjacent to the Web Resource Collections field to add a Web resource collection to the security constraint. The Web resource collection describes a URL pattern and HTTP method pair that refer to the resources that need to be protected.
Select the Get checkbox (for the Getting Started example).
Select the Edit button below the Get checkbox. Browse to the Web client (in the Getting Started WAR this is index.jsp). Select Add, then select OK to close this dialog.
Select the Edit button adjacent to the Authorized Roles field to add the user role to the security constraint. You are specifying the set of roles that are allowed to access the Web resource collection.
Select Import Roles to import the roles added to tomcat-users.xml via admintool.
Select the user role on the left. Select Add. The role is added to the Authorized Roles List.
Select OK. The selected role displays in the Authorized Roles list for this application. (See Managing Roles and Users for information about creating users and roles with admintool.)

Now that security constraints have been added to the application, let's run it for verification purposes.
Select Tools -> Deploy to make sure the latest version of the WAR is being used. Select OK to any dialogs.
Close the Deploy Console when the deployment is complete.
Open the application in a Web browser using the following URL for the Getting Started application:
  http://localhost:8080/GSApp
 
Enter the user name (Duke) and password (javarocks) that we set up earlier.
The Getting Started application loads in the browser.

Security Settings without deploytool

In Creating the Getting Started Application we discussed the "best practices approach to Web services programming", which is described in more detail in the file <JWSDP_HOME>/docs/tomcat/appdev/deployment.html. One of the files that should always be present in a Web Services application is web.xml, which should be created in the /web/WEB-INF/ directory of your Web application. The file web.xml is the deployment descriptor for the application. Initially, in this example, we provided a description of the application. We could set the same settings for Web application security that we created using deploytool directly in the file web.xml. For the example given in the previous section, deploytool writes a web.xml file that looks like this:
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web 
Application 2.3//EN' 'http://java.sun.com/dtd/web-
app_2_3.dtd'>

<web-app>
  <display-name>GSApp</display-name>
  <servlet>
    <servlet-name>index</servlet-name>
    <display-name>index</display-name>
    <jsp-file>/index.jsp</jsp-file>
  </servlet>
  <session-config>
    <session-timeout>30</session-timeout>
  </session-config>
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>WRCollection</web-resource-name>
      <url-pattern>/index.jsp</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>user</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name></realm-name>
  </login-config>
  <security-role>
    <role-name>admin</role-name>
  </security-role>
  <security-role>
    <description>Getting Started App User</description>
    <role-name>user</role-name>
  </security-role>
  <security-role>
    <role-name>manager</role-name>
  </security-role>
  <security-role>
    <role-name>provider</role-name>
  </security-role>
</web-app>
 
Authenticating Users of Web Resources

When you try to access a protected Web resource, the Web container activates the authentication mechanism that has been configured for that resource. You can configure the following authentication mechanisms for a Web resource:

None
HTTP basic authentication
Form-based authentication
Client-certificate authentication
Digest authentication

Basic Authentication

If you specify HTTP basic authentication, the Web server will authenticate a user by using the user name and password obtained from the Web client. For an example that adds basic authentication to an the sample Getting Started application, see Controlling Access to Web Resources.

Form-Based Authentication

If you specify form-based authentication, you can customize the login screen and error pages that are presented to the end user by an HTTP browser.

Neither form-based authentication nor HTTP basic authentication is particularly secure. In form-based authentication, the content of the user dialog is sent as plain text, and the target server is not authenticated. Basic authentication sends user names and passwords over the Internet as text that is uuencoded, but not encrypted. This form of authentication, which uses Base64 encoding, can expose your user names and passwords unless all connections are over SSL. If someone can intercept the transmission, the user name and password information can easily be decoded.

Client-Certificate Authentication

Client-certificate authentication is a more secure method of authentication than either basic or form-based authentication. It uses HTTP over SSL, in which the server and, optionally, the client authenticate each other with Public Key Certificates. Secure Sockets Layer (SSL) provides data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection. You can think of a public key certificate as the digital equivalent of a passport. It is issued by a trusted organization, which is called a certificate authority (CA), and provides identification for the bearer. If you specify client-certificate authentication, the Web server will authenticate the client using an X.509 certificate, a public key certificate that conforms to a standard that is defined by X.509 Public Key Infrastructure (PKI). Prior to running an application that uses SSL, you must configure SSL support on the server (see Installing and Configuring SSL Support on Tomcat).

Digest Authentication

Digested password authentication supports the concept of digesting user passwords. This causes the stored version of the passwords to be encoded (in a form that is not easily reversible), but that the Tomcat server can still utilize for authentication.

From a user perspective, digest authentication acts almost identically to basic authentication in that it triggers a login dialog. The difference between basic and digest authentication is that on the network connection between the browser and the server, the password is encrypted, even on a non-SSL connection. In the server, the password can be stored in cleartext or encrypted text, which is true for all login methods and is independent of the choice that the application deployer makes.

Configuring Web Resources' Authentication Mechanism

To configure the authentication mechanism that the Web resources in a WAR will use:

Select the WAR containing the Web application.
Select the Security tab.
Choose one of the following authentication mechanisms from the User Authentication Method pulldown menu:

None
Basic
Form Based
Client-Certificate
Digest
If you choose form-based authentication, you must select Settings and fill in the Login Page and Error Page fields in the Settings dialog. The error page is displayed when the user cannot be logged in.
If you choose basic or digest authentication, you can select Settings and enter the WAR display name in the Application Label field, displayed as part of the pop-up dialog box. In the deployment descriptor, this value maps to realm name. By default, this is set to the field WAR Display Name, as shown on the General tab of deploytool.

Using SSL to Enhance the Confidentiality of HTTP Basic and Form-Based Authentication

Passwords are not protected for confidentiality with HTTP basic or form-based authentication. To overcome this limitation, you can run these authentication protocols over an SSL-protected session and ensure that all message content is protected for confidentiality.

The default configuration of Tomcat does not support SSL. You must configure Tomcat, or whatever Web server you are using, with an SSL connector to make this work. See Installing and Configuring SSL Support on Tomcat for more information.

To configure HTTP basic or form-based authentication over SSL:

Select the Web component.
From the Security tabbed pane, make sure that Basic or Form Based have been selected in the User Authentication Method menu pulldown.
Click on the Add button in the Security constraint section.
Click on the Security constraint that was added.
Select CONFIDENTIAL in the Network Security Requirement menu pulldown.

If you select CONFIDENTIAL or INTEGRAL on a security constraint, that type of security constraint applies to all requests that match the URL patterns in the Web resource collection, not just to the login dialog.

Note: Good Security Practice: If you are using sessions, once you switch to SSL you should never accept any further requests for that session that are non-SSL. For example, a shopping site might not use SSL until the checkout page, then it may switch to using SSL in order to accept your card number. After switching to SSL, you should stop listening to non-SSL requests for this session. The reason for this practice is that the session ID itself was non-encrypted on the earlier communications, which is not so bad when you're just doing your shopping, but once the credit card information is stored in the session, you don't want a bad guy trying to fake the purchase transaction against your credit card. This practice could be easily implemented using a filter.

Using Programmatic Security in the Web Tier

Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of the following methods of the HttpServletRequest interface:

getRemoteUser
isUserInRole
getUserPrincipal

You can use the getRemoteUser method to determine the user name with which the client authenticated. The isUserInRole method is used to determine if a user is in a specific security role. The getUserPrincipal method returns a java.security.Principal object.

These APIs allow servlets to make business logic decisions based on the logical role of the remote user. They also allow the servlet to determine the principal name of the current user.

Unprotected Web Resources

Many applications feature unprotected Web content, which any caller can access without authentication. In the Web tier, unrestricted access is provided simply by not configuring a security constraint for that particular request URI. It is common to have some unprotected resources and some protected resources. In this case, you will have security constraints and a login method defined, but it will not be used to control access to the unprotected resources. The user won't be asked to log on until the first time they enter a protected request URI.

A Universal Resource Identifier (URI), is a globally unique identifier for a resource. A Universal Resource Locator (URL) is a kind of URI that specifies the retrieval protocol (http or https for Web applications) and physical location of a resource (host name and host-relative path).

In the Java Servlet specification, the request URI is the part of a URL after the host name and port. For example, in the URL http://localhost:8080/myapp/jsp/hello.jsp, the request URI would be /jsp/hello.jsp. The request URI is further subdivided into the context path (which decides which Web application should process the request) and the rest of the path that is used to select the target servlet.

For example, let's say you have an e-commerce site with a browsable catalog you would want anyone to be able to access and a shopping cart area for customers only. You could set up the paths for your Web application so that the pattern /cart/* is protected, but nothing else is protected. Assuming the application is installed at context path /myapp,

http://localhost:8080/myapp/index.jsp is not protected
http://localhost:8080/myapp/cart/index.jsp is protected

A user will not be prompted to log in until the first time that user accesses a resource in the cart subdirectory.

Home
TOC
Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.