Web App Security

Web App Security

Overview

The Java WSDP defines declarative contracts between those who develop and assemble application components and those who configure applications in operational environments. In the context of application security, application providers are required to declare the security requirements of their applications in such a way that these requirements can be satisfied during application configuration. The declarative security mechanisms used in an application are expressed in a declarative syntax in a document called a deployment descriptor. An application deployer then employs container-specific tools to map the application requirements that are in a deployment descriptor to security mechanisms that are implemented by Web components.

Programmatic security refers to security decisions that are made by security-aware applications. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. For example, an application might make authorization decisions based on the time of day, the parameters of a call, or the internal state of a Web component. Another application might restrict access based on user information stored in a database.

Java Web services applications are made up of components that can be deployed into different containers. These components are used to build a multi-tier application. The goal of the Java WSDP security architecture is to achieve end-to-end security by securing each tier.

The tiers can contain both protected and unprotected resources. Often, you need to protect resources to ensure that only authorized users have access. Authorization provides controlled access to protected resources. However, authorization is based on authentication and access control. Authentication is a process that verifies the identity of a user, device, or other entity in a computer system, usually as a prerequisite to allowing access to resources in a system. Access control is a process that determines whether this authenticated user is entitled to access a particular requested resource.

Authorization is not required to access unprotected resources. Because authorization is built upon authentication, authentication is also not needed to access unprotected resources. Accessing a resource without authentication is referred to as unauthenticated or anonymous access.

Users, Groups, and Roles

A Web services user is similar to an operating system user. Typically, both types of users represent people. However, these two types of users are not the same. The Tomcat server authentication service has no knowledge of the user and password you provide when you log on to the operating system. The Tomcat server authentication service is not connected to the security mechanism of the operating system. The two security services manage users that belong to different realms.

The Tomcat server authentication service includes the following components:

Role - an abstract name for the permission to access a particular set of resources. A role can be compared to a key that can open a lock. Many people might have a copy of the key, and the lock doesn't care who you are, just that you have the right key.
User - an individual (or application program) identity that has been authenticated (authentication was discussed in the previous section). A user can have a set of roles associated with that identity, which entitles them to access all resources protected by those roles.
Group - a set of authenticated users classified by common traits such as job title or customer profile. Groups are also associated with a set of roles, and every user that is a member of a group inherits all of the roles assigned to that group. In most cases, you will map users directly to roles and have no need to define a group.
Realm - a complete database of roles, users, and groups that identify valid users of a webapp (or a set of webapps).

Security Roles

When you design a Web component, you should always think about the kinds of users who will access the component. For example, a webapp for a Human Resources department might have a different request URL for someone who has been assigned the role of admin than for someone who has been assigned the role of director. The admin role may let you view some employee data, but the director role enables you to view salary information. Each of these security roles is an abstract logical grouping of users that is defined by the person who assembles the application. When an application is deployed, the deployer will map the roles to security identities in the operational environment.

To create a role for a Web services application, you first set up the users and roles using admintool, then declare it for the WAR file that is contained in the application.

Managing Roles and Users

To manage the information in the users file, we recommend that you use admintool. To use admintool, start Tomcat, then point your browser to http://localhost:8080/admin and log on with a user name and password combination that has been assigned the admin role, such as the user name and password that you entered during installation.

For security purposes, admintool, the Tomcat Web Server Administration Tool, verifies that you (as defined by the information you provide when you log into the application) are a user who is authorized to install and reload applications (defined as a user with the role of admin in tomcat-users.xml) before granting you access to the server.

The $JWSDP_HOME/conf/tomcat-users.xml file is created by the installer. It contains, in plain text, the user name and password created during installation of the Java WSDP. This user name is initially associated with the predefined roles of admin, manager, and provider. You can edit the users file directly in order to add or remove users or modify roles, or you can use admintool to accomplish these tasks, as described herein.

The tomcat-users.xml file looks like this:
<?xml version='1.0'?>
<tomcat-users>
<role rolename="admin"/>
<role rolename="manager"/>
<role rolename="provider"/>
<user username="your_name" password="your_password"
     roles="admin,manager,provider"/>
</tomcat-users>
The following sections describe how to add roles and users using admintool. The file $JWSDP_HOME/conf/tomcat-users.xml is updated as the changes are made in admintool.

Using the Tomcat Web Server Administration Tool

To use admintool, the Tomcat Web Server Administration Tool, start Tomcat.

Starting Tomcat

To start Tomcat, type the following command in a terminal window.
$JWSDP_HOME/bin/startup.sh        (Unix platform)

$JWSDP_HOME\bin\startup.bat       (Microsoft Windows)
The startup script starts the task in the background and then returns the user to the command line prompt immediately. The startup script does not completely start Tomcat for several minutes.

Note: The startup script for Tomcat can take several minutes to complete. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Tomcat splash screen displays, you may continue. If the splash screen does not load immediately, wait up to several minutes and then retry. If, after several minutes, the Tomcat splash screen does not display, refer to the troubleshooting tips in "Unable to Locate the Server localhost:8080" Error.

Documentation for Tomcat can be found at $JWSDP_HOME/docs/tomcat/index.html.

Starting admintool

Once the Tomcat server is started, follow these steps to start admintool.
Start a Web browser.
In the Web browser, point to the following URL:
  http://localhost:8080/admin
Log in to admintool using a user name and password combination that has been assigned the role of admin.
The admintool utility displays in the Web browser window:
Tomcat Web Server Administration Tool

When you have finished, log out of admintool by selecting Log Out.

The following sections show how to use admintool to do the following:

Display all roles in the default realm
Add a role to the default realm
Remove a role from the default realm
Display all users in the default realm
Add a user to the default realm
Remove a user

This section uses the Getting Started application discussed in Getting Started With Tomcat as an example. These modifications are made to the running Tomcat server--it is not necessary to stop and restart Tomcat.

Managing Roles

To view all existing roles in the realm, select Roles from the User Definition section in the left pane.

The Roles List and Available Actions list display in the right pane. By default, the roles defined during Java WSDP installation are displayed. These roles include admin, manager, and provider.

Use the following procedure to add a new role to the default realm.

From the Roles List, select Create New Role.
Enter user for the name of the role to add.
Enter Getting Started App Security Role as the description of the role.
Select Save when done. The newly defined role displays in the list.

Use the following procedure to remove a role from the default realm.

From the Roles List, select Delete Existing Roles from the Available Actions list.
From the Roles window, select the role to remove by checking the box to its left.
Select Save.

Managing Users

To view all existing users in the realm, select Users from the User Definition section in the left pane.

The User List and Available Actions list display in the right pane. By default, the user name defined during Java WSDP installation is displayed.

Use the following procedure to edit a user's profile.

Select Users from the User Definition section in the left pane.
Select the user profile to edit in the right pane.
Edit the existing user properties.

Use the following procedure to add a new user to the default realm.

From the Users List, select Create New User.
Enter Duke as the name of the user to add.
Enter javarocks as the password for that user.
Enter Duke the Java programming wiz as the full name of the user.
Select the user role for this user.
Select Save when done. The newly defined user displays in the list.

Use the following procedure to remove a user from the default realm.

From the Users List, select Delete Existing Users from the Available Actions list.
From the Delete Existing Users window, select the user to remove by checking the box to its left.
Select Save.

The addition of a new role and user as described in the previous section are reflected in the updated tomcat-users.xml. It now contains the following data:
<?xml version='1.0'?>
<tomcat-users>
   <role rolename="admin"/>
   <role rolename="user" description="Getting Started
     App Security Role"/>
   <role rolename="manager"/>
   <role rolename="provider"/>
   <user username="your_name" password="your_password"
      roles="admin,manager,provider"/>
   <user username="Duke" password="javarocks"
      fullName="Duke the Java Programming wiz"
      roles="user"/>
</tomcat-users>
Considerations When Changing a User Profile

When you add a user or change a user name or password using admintool, the changes are written to the file tomcat-users.xml, as discussed in Managing Users. When Tomcat is started, it reads the information in tomcat-users.xml. When you make changes to a user or add a user using admintool, then save the changes, the changes are made to the running Tomcat server - no need to shut down and restart Tomcat.

However, if you add a new user or modify the default user name or password using admintool and want to run deploytool using the new or modified user profile, Tomcat must be stopped and restarted. This is because the deploytool and admintool login requires that the user name and password in the build.properties file match a user name and password with the proper role assignment in tomcat-users.xml. When you want to log in to deploytool using a new or modified user profile, follow these steps:

In admintool, assign the new user the roles of admin and manager. The role of admin is required for admintool and deploytool. The role of manager is required for deploytool.
Log out of admintool.
Shut down Tomcat.
Edit the build.properties file to match the new or modified user name and password. For more about the build.properties file, see Creating the Build Properties File.
Start Tomcat (waiting about 3 minutes for it to fully load).
Start deploytool. Enter a user name and password from tomcat-users.xml that is assigned the roles of admin and manager, and that matches the user name and password from build.properties.

Mapping Application Roles to Realm Roles

When you are developing a Web services application, you will know the roles that you have used in the application, but you probably won't know exactly what roles have been defined for the realm. In the Java WSDP, that is taken care of in the Web services security architecture. After your application has been deployed, the administrator of the Tomcat server will map the roles of the application to the roles of the default realm.

In the Java WSDP, you create a role for a Web services application by first setting up the roles and users using admintool, as discussed in Managing Roles and Users. Then, using deploytool, you import the defined roles and select which are authorized roles for the WAR file that is contained in the application.

An administrator can authorize roles to access this webapp by selecting them in deploytool. However, before you can authorize a role for a webapp, create a security constraint. For more information, refer to the section Controlling Access to Web Resources.

The following example authorizes the role of user set up in Using the Tomcat Web Server Administration Tool for the Getting Started application. This example uses the gs.war created in the Getting Started application, as discussed in Deploying the Application Using deploytool.
Make sure Tomcat is running.
Start deploytool. The deploytool utility is a command line tool that is located in the bin directory of your Java WSDP installation. To start it, open a terminal window or command prompt and enter:
  $JWSDP_HOME/bin/deploytool"
Enter a user name and password that has been assigned the role of admin in the Set Tomcat Server dialog.
Select or open the webapp's WAR file, $JWSDP_HOME/docs/tutorial/examples/gs/gs.war.
Select the Security pane.
Add a Security Constraint by selecting the Add button beside the Security Constraints field.
Select the Edit button below Authorized Roles to add an authorized role to the application.
Select Import Roles to import the roles previously defined using admintool.
Select User, select Add, then select OK to close this dialog.
Web-Tier Security

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 webapp. 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 webapp 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, 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 webapp.
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, 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 webapps) 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 webapp 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 webapp 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.

EIS-Tier Security

In the EIS tier, an application component requests a connection to an EIS resource. As part of this connection, the EIS may require a sign-on to the resource. The application component provider has two choices for the design of the EIS sign-on. The two sign-on approaches are:

With the container-managed sign-on approach, the application component lets the container take the responsibility of configuring and managing the EIS sign-on. The container determines the username and password for establishing a connection to an EIS instance.
With the component-managed sign-on approach, the application component code manages EIS sign-on by including code that performs the sign-on process to an EIS.

The component provider can use deploytool to choose the type of sign-on.

Configuring Sign-On

Use the following procedure in deploytool to configure the type of sign-on.

Select the component.
Select the Resource Refs tab.
Click Add.
In the Authentication combo box, select one of the following:

Container--for container-managed sign-on
Application--for component-managed sign-on

Container-Managed Sign-On

With container-managed sign-on, an application component does not have to pass any security information for signing on to the resource to the getConnection() method. The security information is supplied by the container. You can use a javax.sql.DataSource, which offers two ways to get an actual java.sql.Connection, depending on whether you are using container-managed sign-on or not. Use getConnection() if you are using container-manager sign-on. Use getConnection String(username, String password) if using component-managed sign-on.

Component-Managed Sign-On

With component-managed sign-on, an application component is responsible for passing the security information that is needed for signing on to the resource to the getConnection() method. Security information could be username and password. You can use a javax.sql.DataSource to get a java.sql.Connection with getConnection String(username, String password).

Installing and Configuring SSL Support on Tomcat

Secure Socket Layer (SSL) is a technology that allows Web browsers and Web servers to communicate over a secured connection. In this secure connection, the data that is being sent is encrypted before being sent, then decrypted upon receipt and prior to processing. Both the browser and the server encrypt all traffic before sending any data.

Another important aspect of the SSL protocol is authentication. During your initial attempt to communicate with a Web server over a secure connection, that server will present your Web browser with a set of credentials in the form of a server certificate. The purpose of the certificate is to verify that the site is who and what it claims to be. In some cases, the server may request a certificate that the client is who and what it claims to be (which is known as client authentication).

You only need to configure Tomcat to take advantage of SSL support when you are planning on running it as a stand-alone Web server. When you are planning to run Tomcat primarily as a JSP and Java Servlet container behind another Web server, such as Apache or Microsoft IIS, it is usually necessary to configure the primary Web server to handle the SSL connections from users. The communications between the primary Web server and Tomcat do not need to be encrypted.

To install and configure SSL support on Tomcat, you need

Java Secure Socket Extension (JSSE), see Using JSSE.
A server certificate keystore, see Setting Up a Server Certificate.
An HTTPS connector, see Configuring the SSL Connector.

To verify that SSL support is enabled, see Verifying SSL Support.

Using JSSE

You need to have Java Secure Socket Extension (JSSE) installed in order for Tomcat to use SSL. JSSE is integrated into the Java WSDP 1.0. JSSE is a set of Java packages that enable secure Internet communications. These packages implement a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols and include functionality for data encryption, server authentication, message integrity, and optional client authentication. Using JSSE, developers can provide for the secure passage of data between a client and a server running any application protocol (such as HTTP, Telnet, NNTP, and FTP) over TCP/IP.

By default, the location of the jsse.jar file is $JWSDP_HOME/common/lib/jsse.jar. For more information on JSSE, see its Web site at http://java.sun.com/products/jsse/index-102.html.

Setting Up a Server Certificate

In order to implement SSL, a Web server must have an associated certificate for each external interface, or IP address, that accepts secure connections. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information. It may be useful to think of a certificate as a "digital driver's license" for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.

The certificate is cryptographically signed by its owner and is difficult for anyone else to forge. For sites involved in e-commerce, or any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known Certificate Authority (CA) such as Verisign or Thawte.

If authentication is not really a concern, such as if an administrator simply wants to ensure that data being transmitted and received by the server is private and cannot be snooped by anyone eavesdropping on the connection, you can simply save the time and expense involved in obtaining a CA certificate and simply use a self-signed certificate.

Certificates are used with the HTTPS protocol to authenticate Web clients. The HTTPS service of the Tomcat server will not run unless a server certificate has been installed. Use the procedure outlined below to set up a server certificate that can be used by Tomcat to enable SSL.

One tool that can be used to set up a Tomcat server certificate is keytool, a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.

A certificate is a digitally-signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.

The keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password. For more information on keytool, read its documentation at http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/keytool.html.
Generate a key pair and a self-signed certificate.
The keytool utility enables you to create the certificate. The keytool utility that ships with the J2SE SDK version programmatically adds a Java Cryptographic Extension provider that has implementations of RSA algorithms. This provider enables you to import RSA-signed certificates.
To generate the certificate, run the keytool utility as follows, <keystore_filename> with the name of your keystore file:
   keytool -genkey -keyalg RSA -alias tomcat
    -keystore <keystore_filename>
Note: Tomcat is looking for the keystore to have the name .keystore in the home directory of the machine on which Tomcat is running.

The keytool utility prompts you for the following information:

Keystore password--Enter a password. (You may want to use changeit to be consistent with the default password of the J2SE SDK keystore.)
First and last name--Enter the fully-qualified name of your server. This fully-qualified name includes the host name and the domain name. For testing purposes on a single machine, this will be localhost.
Organizational unit--Enter the appropriate value.
Organization--Enter the appropriate value.
City or locality--Enter the appropriate value.
State or province--Enter the unabbreviated name.
Two-letter country code--For the USA, the two-letter country code is US.
Review the information you've entered so far, enter Yes if it is correct.
Key password for Tomcat--Do not enter a password. Press Return.

A self-signed certificate is acceptable for most SSL communication. If you are using a self-signed certificate, skip to Configuring the SSL Connector. If you'd like to have your certificate digitally signed by a CA, continue with Obtaining a Digitally-Signed Certificate.

Obtaining a Digitally-Signed Certificate
Get your certificate digitally signed by a CA. To do this,
Generate a Certificate Signing Request (CSR).
     keytool -certreq -alias tomcat -keyalg RSA
      -file <csr_filename> -keystore <keystore_filename>
Send the contents of the <csr_filename> for signing.
If you are using Verisign CA, go to http://digitalid.verisign.com/. Verisign will send the signed certificate in email. Store this certificate in a file.
Import the signed certificate that you received in email into the server:
     keytool -import -alias root -trustcacerts -file 
      <signed_cert_file> -keystore <keystore_filename>
Import the certificate (if using a CA-signed certificate).

If your certificate will be signed by a Certification Authority (CA), import the CA certificate. You may skip this step if you are using only the self-signed certificate. If you are using a self-signed certificate or a certificate signed by a CA that your browser does not recognize, a dialog will be triggered the first time a user tries to access the server. The user can then choose to trust the certificate for this session only or permanently.
To import the certificate, perform these tasks:
Request the CA certificate from your CA. Store the certificate in a file.
To install the CA certificate in the Java 2 Platform, Standard Edition, run the keytool utility as follows. (You must have the required permissions to modify the $JAVA_HOME/jre/lib/security/cacerts file.)
     keytool -import -trustcacerts -alias tomcat 
      -file <ca-cert-filename> -keystore <keystore-filename>
Configuring the SSL Connector

By default, an SSL HTTPS Connector is not enabled. You can enable and configure an SSL HTTPS Connector on port 8443 using either of the following methods:

Add the connector using admintool. See Adding an SSL Connector in admintool.
Uncomment the SSL Connector in the file $JWSDP_HOME/conf/server.xml. See Configuring the SSL Connector in server.xml.

Adding an SSL Connector in admintool

To configure an SSL Connector using admintool, first have created a keystore as described in Setting Up a Server Certificate. Tomcat will be looking for a keystore file named .keystore in the home directory of the machine on which Tomcat is running. When you have verified that you have created the keystore file, follow these steps.

Start Tomcat, if you haven't already done so.
Start admintool by entering http://localhost:8080/admin in a Web browser.
Enter a user name and password combination that is assigned the role of admin.
Select Service (Java Web Services Developer Pack) in the left pane.
Select Create New Connector from the drop-down list in the right pane.
In the Type field, select HTTPS.
In the Port field, enter 8443 (or whatever port you require). This defines the TCP/IP port number on which Tomcat will listen for secure connections.
Enter the Keystore Name and Keystore Password if you have created a keystore named something other than .keystore, if .keystore is located in a directory other than the home directory of the machine on which Tomcat is running, or if the password is something other than the default value of changeit. If you have used the expected values, you can leave these fields blank.

The home directory is generally /home/user_name on Unix and Linux systems, and C:\Documents and Settings\user_name on Microsoft Windows systems.

Select Save to save the new Connector for this session.
Select Commit Changes to write the new Connector information to the server.xml file so that it is available the next time Tomcat is started.

To view and/or edit the newly-created Connector, expand the Service (Java Web Services Developer Pack) node, and select Connector (8443).

Configuring the SSL Connector in server.xml

An example Connector element for an SSL connector is included in the default server.xml. This Connector element is commented out by default. To enable the SSL Connector for Tomcat, remove the comment tags around the SSL Connector element. To do this, follow these steps.
Shutdown Tomcat, if it is running. Changes to the file $JWSDP_HOME/conf/server.xml are read by Tomcat when it is started.
Open the file $JWSDP_HOME/conf/server.xml in a text editor.
Find the following section of code in the file (try searching for SSL Connector). Remove comment tags around the Connector entry. The comment tags that are to be removed are shown in bold below.
  
   
  
Save and close the file.
Start Tomcat.
The attributes in this Connector element are outlined in more detail in Tomcat Administration Tool.

Verifying SSL Support

For testing purposes, and to verify that SSL support has been correctly installed on Tomcat, load the default Tomcat introduction page with the following URL:
The https in this URL indicates that the browser should be using the SSL protocol. The port of 8443 is where the SSL Connector was created in the previous step.

The first time a user loads this application, the New Site Certificate dialog displays. Select Next to move through the series of New Site Certificate dialogs, select Finish when you reach the last dialog.

Troubleshooting SSL Connections

When Tomcat starts up, I get an exception like "java.io.FileNotFoundException: {some-directory}/{some-file} not found".

A likely explanation is that Tomcat cannot find the keystore file where it is looking. By default, Tomcat expects the keystore file to be named .keystore, and to be located in the home directory on the system under which Tomcat is running (which may or may not be the same as yours). If the keystore file is anywhere else, you will need to add a keystoreFile attribute to the <Factory> element in the Tomcat configuration file or specify the location of the file on the Connector (8443) node of admintool.

When Tomcat starts up, I get an exception like "java.io.FileNotFoundException: Keystore was tampered with, or password was incorrect".

Assuming that someone has not actually tampered with your keystore file, the most likely cause is that Tomcat is using a different password than the one you used when you created the keystore file. To fix this, you can either go back and recreate the keystore file, or you can add or update the keystorePass attribute on the <Factory> element in the Tomcat configuration file or on the Connector (8443) node of admintool. REMINDER - Passwords are case sensitive!

If you are still having problems,

If you are still having problems, a good source of information is the TOMCAT-USER mailing list. You can find pointers to archives of previous messages on this list, as well as subscription and unsubscription information, at http://jakarta.apache.org/site/mail.html.

General Tips on Running SSL

The SSL protocol is designed to be as efficient as securely possible. However, encryption/decryption is a computationally expensive process from a performance standpoint. It is not strictly necessary to run an entire webapp over SSL, and it is customary for a developer to decide which pages require a secure connection and which do not. Pages that might require a secure connection include login pages, personal information pages, shopping cart checkouts, or any pages where credit card information could possibly be transmitted. Any page within an application can be requested over a secure socket by simply prefixing the address with https: instead of http:. Any pages which absolutely require a secure connection should check the protocol type associated with the page request and take the appropriate action if https: is not specified.
Using name-based virtual hosts on a secured connection can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address. If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts should not interfere with normal SSL operations on the server. Be aware, however, that most client browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers will display a warning to the client. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

Further information on SSL

For more information, please read the Tomcat document SSL Configuration HOW-TO, located at $JWSDP_HOME/docs/tomcat/ssl-howto.html.

Troubleshooting

Server Returned HTTP Response Code: 403

Symptom: When you login to deploytool at startup or by selecting File->Set Tomcat Server from the deploytool menu, you get the following error:
Unable to add Server URL 'http://localhost:8080/manager'

Server returned HTTP response code: 403 for URL: 
Solution: The user name that you used to log in to deploytool has not been assigned the role of manager. Use admintool to edit the user's profile and assign the user the role of manager. Information on using admintool to edit a user's profile can be found at Managing Users.

Further Information

Read the Java Servlet specification, available online at http://java.sun.com/products/servlet/download.html, for a basic understanding of security concepts in JSP and Java Servlet technology.
Read the Tomcat document SSL Configuration HOW-TO, located at $JWSDP_HOME/docs/tomcat/ssl-howto.html for information regarding installing and configuring SSL support on Tomcat.
Read the Tomcat document Realm Configuration HOW-TO, located at $JWSDP_HOME/docs/tomcat/realm-howto.html for information regarding configuring Tomcat to support container-managed security by connecting to an existing database of user names, passwords, and user roles.