Security for JAX-RPC

In this section, you'll learn how to configure JAX-RPC-based Web service applications for basic and mutual authentication over HTTP/SSL. If the topic of authentication is new to you, please refer to the section titled Authenticating Users of Web Resources.

For this tutorial, we are going to modify the example application in <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/hello to add HTTP/S basic and mutual authentication. The resulting application can be found in the directory <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security. The following steps are necessary to add basic authentication to the hello example:

Create the appropriate certificates and keystores (see Step 1: Creating SSL Certificates for Basic Authentication).

Make sure that your server is configured for an SSL Connector. The Tomcat server is not configured with an SSL Connector, so you need to add the SSL Connector (see Configuring the SSL Connector) and add information on the generated keystore files (see Step 2: Configuring the SSL Connector).

Add security elements to the web.xml deployment descriptor. See Step 3: Adding Security Elements to web.xml for information on how to do this.

Modify the endpoint address in the build.properties file for the application, and add other properties needed to run this example. See Step 4: Editing the Build Properties.

Set security properties in the client code. See Step 5: Setting Security Properties in the Client Code for information on how to do this.

Build and run the Web service. See Step 6: Create a New Ant Target for Running this Example for information on how to do this for the example application.

The steps for configuring a Web service for basic authentication over HTTP/S are outlined here. For mutual authentication, follow these steps, then add client authentication as discussed in Enabling Mutual Authentication Over SSL.

Step 1: Creating SSL Certificates for Basic Authentication

Note: This information is discussed in more detail in Setting Up Digital Certificates. This section provides a summary of the steps needed to create the SSL Certificates for this example.

We will use the tool 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. Since we are adding security to the hello Web service, we will run keytool from the directory where the modified example application resides, which is the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory. In so doing, the keystores are created in the same directory as the code for the security Web service.

Run keytool to generate the server and client keystores. For basic authentication, it is only necessary to import the server certificate into the client keystore. Generate the server keystore with a default password of changeit.

To generate the server keystore, enter the following in a terminal window. Be sure that you are in the directory <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security before proceeding.

Note that when you press Enter, keytool 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 keytool's first prompt in which it asks for first and last names. For testing purposes, this may be localhost. This host must match the host identified in the endpoint address specified in Step 4: Editing the Build Properties.

<J2SE_HOME>\bin\keytool -genkey -alias tomcat-server -keyalg RSA -keypass changeit -storepass changeit -keystore server.keystore

Export the generated server certificate.

<J2SE_HOME>\bin\keytool -export -alias tomcat-server -storepass changeit -file server.cer -keystore server.keystore

Generate the client keystore.

To generate the client keystore, enter the following at a terminal window:

Note that when you press Enter, keytool 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 keytool's first prompt in which it asks for first and last names. In most cases, for testing purposes, this will be localhost. This host must match the host identified in the endpoint address specified in Step 4: Editing the Build Properties.

<J2SE_HOME>\bin\keytool -genkey -alias jwsdp-client -keyalg RSA -keypass changeit -storepass changeit -keystore client.keystore

Import the server certificate into the client's keystore.

<J2SE_HOME>\bin\keytool -import -v -trustcacerts -alias tomcat-server -file server.cer -keystore client.keystore -keypass changeit -storepass changeit

Step 2: Configuring the SSL Connector

Note: The steps for configuring an SSL Connector are provided in more detail in the section Configuring the SSL Connector. The steps in this section are provided for your convenience.

You need to configure an SSL Connector for Tomcat. If you are using a different server, see Configuring the SSL Connector for general information on configuring an SSL Connector. In addition to configuring the server for an SSL Connector, you must also add information on the keystore file and its password in the same place where you've added the SSL connector. For example, in the Java WSDP, you first need to remove the comment tags () from around the SSL Connector and then add the information in bold to this section in the file <JWSDP_HOME>/conf/server.xml.

Step 3: 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>, <login-config>, and <security-role> elements. Code in bold has been added from the basic <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/hello example.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
    2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
  <display-name>Hello World Application (secure)</display-name>
  <description>HTTPS example using JAX-RPC </description>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
  <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>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-method>BASIC</auth-method>
  </login-config>
  <security-role>
    <role-name>manager</role-name>
  </security-role>
</web-app>

Note that the <role-name> element specifies manager, a role that has already been specified in a deployment descriptor for Tomcat (<JWSDP_HOME>/conf/tomcat-users.xml). For more information on defining and linking roles, see Security Roles.

Step 4: Editing the Build Properties

To run the application with basic authentication over HTTP/SSL, we have added some properties related to the keystore file and its password to the build.properties file, which is located in the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory. The following example assumes you are running on Java WSDP 1.1. The items marked in bold have been be added to the file. The items that have been added will be passed as arguments to the client application when it is run in a later section.

Step 5: 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.

trust-store Property - The value of the trust-store property is the fully qualified name of the client keystore file: <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security/client.keystore

trust-store-password Property - The trust-store-password property is the password of the keystore. The default value of this password is changeit.

username and password Properties - The username and password properties correspond to the manager role. (See Security Roles.)

The client sets the aforementioned security properties as follows. The code in bold is the code that had been added from the original version of the jaxrpc/hello example application.

package security;

import javax.xml.rpc.Stub;

public class HelloClient {

    public static void main(String[] args) {
    
        if (args.length !=4) {
          System.out.println("Usage: ant run-security");
          System.exit(1);
        }
        
        String trustStore=args[0];
        String trustStorePassword=args[1];
        String username=args[2];
        String password=args[3];

        System.out.println("trustStore: " + trustStore);
        System.out.println("trustStorePassword: " +
        trustStorePassword);
        System.out.println("username: " + username);
        System.out.println("password: " + password);

    try {
      Stub stub = createProxy();
      System.setProperty("javax.net.ssl.trustStore",
        trustStore);
      System.setProperty("javax.net.ssl.trustStorePassword",
        trustStorePassword);
    stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY,
        username);
    stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY,
        password); 
      HelloIF hello = (HelloIF)stub;
      System.out.println(hello.sayHello("Duke! I feel
        secure!"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }    

    private static Stub createProxy() {
        // Note: MyHelloService_Impl is implementation-specific.
        return (Stub)(new MyHello_Impl().getHelloIFPort());
    }
}

Step 6: Create a New Ant Target for Running this Example

The existing target for running the hello example application is not sufficient for running the secure version of the application. You need to pass information on the keystore and its password, as well as the user name and its password. The following target has been added to the file <JWSDP_HOME>/docs/examples/jaxrpc/security/build.xml to faciliate running the secure JAX-RPC example:

Step 7: Building and Running this Example

If you haven't already done so, follow the instructions in Setting Up, download the example code for this tutorial, and complete Steps 1-2 before proceeding, as these steps are specific to your machine and implementation.

Make sure that Tomcat is running.

Go to the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security directory.

Type the following commands:

ant build ant package ant deploy ant build-static ant run-security

% ant run-security
Buildfile: build.xml

run-security:
     [echo] Running the security.HelloClient program...
     [java] trustStore: <JWSDP_HOME>/docs/tutorial/examples/
     jaxrpc/security/client.keystore
     [java] trustStorePassword: changeit
     [java] username: your_name
     [java] password: your_password
[java] Hello - secure Duke! I feel secure!

BUILD SUCCESSFUL

Enabling Mutual Authentication Over SSL

The section Security for JAX-RPC discusses setting up server-side authentication. This section discusses setting up client-side authentication. When both server and client-side authentication are enabled, this is called mutual, or two-way, authentication. In client authentication, clients are required to submit certificates that are issued by a certificate authority that you choose to accept. There are at least two ways to enable client authentication.

Configure the SSL Socket Factory to enable client authentication. For example, to configure the SSL Socket Factory for Tomcat, you would set clientAuth="true", as shown in bold in the code sample below. By enabling client authentication in this way, client authentication is required for all the requests going through the specified SSL port. As with all changes to the Web server configuration file, you must stop and restart the Web server for this change to become effective.

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8443" minProcessors="5" maxProcessors="75" enableLookups="false" acceptCount="10" debug="0" scheme="https" secure="true"> <Factory className= "org.apache.coyote.tomcat4.CoyoteServerSocketFactory"> keystoreFile= "<JWSDP_HOME>/docs/tutorial/examples/jaxrpc/security/ server.keystore" keystorePass="changeit" clientAuth="true" protocol="TLS" debug="0" /> </Connector>

Set the method of authentication in the web.xml file to CLIENT-CERT, as shown in bold below. By enabling client authentication in this way, client authentication is enabled for a specific application.

<login-config> <auth-method>CLIENT-CERT</auth-method> </login-config>

When client authentication is enabled in both ways mentioned above, client authentication will be performed twice.

Configuring Mutual Authentication for the JAX-RPC Security Example

To configure and create a JAX-RPC service with mutual authentication, follow all of the steps in the section Security for JAX-RPC up to and including the command ant build-static. Then, follow these steps:

Generate a client certificate, export it, and then import the client certificate into the server's keystore, as discussed in Creating a Client Certificate for Mutual Authentication.

Edit web.xml to change the method of authentication to CLIENT-CERT in the login configuration section of the deployment descriptor.

<login-config> <auth-method>CLIENT-CERT</auth-method> </login-config>

Run the application:

ant run-security

Acknowledgement: This section includes material from the "Web Services Security Configuration" white paper, written by Rahul Sharma and Beth Stearns.