Security for JAX-RPC

The Java^TM Web Services Tutorial

Security for JAX-RPC

In this section, you'll learn how to create JAX-RPC service applications that use HTTP/SSL for basic or mutual authentication. If the topic of authentication is new to you, please refer to the chapter Web Application Security.

Note: The instructions in this section apply only to version 1.4 of the J2SE SDK.

There are certain steps you take to configure a JAX-RPC Web service endpoint for HTTP/S basic and mutual authentication:

Use keytool, which is part of the J2SE SDK, to generate certificates and keystores.
Add an SSL Connector to Tomcat by running admintool, which is part of the Java WSDP.
Restart Tomcat.
Add security elements to the web.xml deployment descriptor.
Set some properties in the client code.
Build and run the Web service.

Detailed instructions for these steps follow.

Basic Authentication Over SSL

The steps for configuring a Web service for basic authentication over HTTP/S are outlined here. Refer to the section Mutual Authentication Over SSL for the steps for configuring the same service with mutual authentication.

Generating SSL Certificates for Basic Authentication

You use keytool to generate SSL certificates and export them to the appropriate server and client keystores. Keep in mind that the server and client keystores are created in the directory from which you run keytool.
Go to the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory.
Run keytool to generate the server keystore with a default password of changeit.
UNIX:
Specify the server name, such as localhost, and user identity information as arguments to keytool. Enter the following:
$JAVA_HOME/bin/keytool -genkey -alias tomcat-server -dname 
"CN=<server name>, OU=<organizational unit>, O=<organization>, 
L=<locality>, S=<state>, C=<country code>", -keyalg RSA -
keypass changeit -storepass changeit -keystore server.keystore
 
Windows:
The keytool utility prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to the first prompt, which asks for first and last names. Enter the following:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat-server -keyalg 
RSA -keypass changeit -storepass changeit -keystore 
server.keystore
 
Export the generated server certificate.
The keytool command is the same for UNIX and Windows. On UNIX, enter the following:
$JAVA_HOME/bin/keytool -export -alias tomcat-server -storepass 
changeit -file server.cer -keystore server.keystore
 
Generate the client keystore.
UNIX:
$JAVA_HOME/bin/keytool -genkey -alias tomcat-client -dname 
"CN=<client name>, OU=<organizational unit>, O=<organization>, 
L=<locality>, S=<state>, C=<country code>", -keyalg RSA -
keypass changeit -storepass changeit -keystore client.keystore
 
Windows:
The keytool utility prompts you to enter the client's server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to the first prompt, which asks for first and last names. Enter the following:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat-client -keyalg 
RSA -keypass changeit -storepass changeit -keystore 
client.keystore
 
Import the server certificate into the client's keystore.
For basic authentication, it is only necessary to import the server certificate into the client keystore. The keytool command is the same for UNIX and Windows. On UNIX, enter the following:
$JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat-
server -file server.cer -keystore client.keystore -keypass 
changeit -storepass changeit
 
Adding an SSL Connector to Tomcat

In this section you will add the SSL Connector by running admintool, a utility that is included with the Java WSDP. For more information on the tool, see the appendix, Tomcat Administration Tool

Follow the instructions in Adding an SSL Connector in admintool. In the right pane displayed by admintool, enter the values shown in Table 9-3.

Table 9-3 SSL Connector Values for admintool
Field
Value

Type
HTTPS

Port
8443

Keystore
Name
<JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security/server.keystore

Keystore
Password
changeit

Restart Tomcat.
Make sure that the SSL Connector has been added by following the instructions in Verifying SSL Support.

Adding Security Elements to web.xml

The files for this example are in the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory. For authentication over SSL, the web.xml file includes the <security-constraint> and <login-config> elements:
<security-constraint>
  <web-resource-collection>
    <web-resource-name>SecureHello</web-resource-name>
    <url-pattern>/security</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>manager</role-name>
  </auth-constraint>
</security-constraint>
<login-config>
  <auth-method>BASIC</auth-method>
</login-config>
 
Note that the <role-name> element specifies manager, a role that has already been specified in the <JWSDP_HOME>/conf/tomcat-users.xml file. To learn how to update the tomcat-users.xml file with admintool, see Managing Roles.

Setting Security Properties in the Client Code

The source code for the client is in the HelloClient.java file of the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory. For basic authentication over SSL, the client code must set several security-related properties.

trustStore Property

The value of the trustStore property is the fully qualified name of the client.keystore file:
<JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security/client.key
store
 
In a preceding section, Generating SSL Certificates for Basic Authentication, you created the client.keystore file by running the keytool utility. The client specifies the trustStore property as follows:
System.setProperty("javax.net.ssl.trustStore", trustStore);
 
trustStorePassword Property

The trustStorePassword property is the password of the J2SE SDK keystore. In a previous section, you specified the default value of this password (changeit) when running keytool. The client sets the trustStorePassword property in the following line:
System.setProperty("javax.net.ssl.trustStorePassword", 
   trustStorePassword);
 
Username and Password Properties

The username and password values correspond to the manager role, which is specified in the <JWSDP_HOME>/conf/tomcat-users.xml file. (See Managing Roles and Users.) The installer utility of the Java WSDP automatically added the username and password values to the tomcat-users.xml file.

The client sets the username and password properties as follows:
stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, 
    username);
stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, 
    password);
 
Building and Running the Example for Basic Authentication Over SSL

Perform the following steps:
If you haven't already done so, follow the instructions in Setting Up.
Follow the instructions in Generating SSL Certificates for Basic Authentication and in Adding an SSL Connector to Tomcat. Don't forget to restart Tomcat.
Go to the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory.
Type the following commands:
  ant build
  ant deploy
  ant build-static
  ant run-security
 
The client should display the following line:
Hello Duke (secure)
 
Mutual Authentication Over SSL

To configure and create a JAX-RPC service with mutual authentication, follow all of the steps in the preceding section (Basic Authentication Over SSL) up to and including the command ant build-static. Then, follow these steps:
Export the generated client certificate.
The keytool command is the same for UNIX and Windows. On UNIX, enter the following:
$JAVA_HOME/bin/keytool -export -alias tomcat-client -storepass 
changeit -file client.cer -keystore client.keystore
 
Import the client certificate into the server's keystore.
The keytool command is the same for UNIX and Windows. On UNIX, enter the following:
$JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat-
client -file client.cer -keystore server.keystore -keypass 
changeit -storepass changeit
 
Run the application:
ant run-security
 
The client should display the following line:
Hello Duke (secure)
 
Acknowledgement: This section includes material from the "Web Services Security Configuration" white paper, written by Rahul Sharma and Beth Stearns.

**Table 9-3 SSL Connector Values for admintool**
Field	Value
Type	`HTTPS`
Port	`8443`
Keystore Name	<`JWSDP_HOME`>/docs/tutorial/examples/jaxrpc/security/server.keystore
Keystore Password	`changeit`

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.