XML and Web Services Security - The J2EE 1.4 Tutorial

XML and Web Services Security

Security can be applied to web services at both the transport-level and the message-level.

In message security, security information travels along with the web services message. WSS in the SOAP layer is the use of XML Encryption and XML Digital Signatures to secure SOAP messages. WSS profiles the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to achieve this.

Message layer security differs from transport layer security in that message layer security can be used to decouple message protection from message transport so that messages remain protected after transmission, regardless of how many hops they travel on.

Message-level security is discussed in the following documentation:

Configuring Message Security chapter of the Application Server Administration Guide. This chapter is for system administrators or others attempting to set up the Application Server for message security.

Securing Applications chapter of the Application Server Developers' Guide. This chapter is for developers, assemblers, and deployers attempting to implement message security at the application or method level.

Transport-level security is discussed in the following example sections:

Transport-Level Security

Example: Basic Authentication with JAX-RPC

Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC

Transport-Level Security

Authentication 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. There are several ways in which this can happen. The following ways are discussed in this section:

One approach is that a user authentication method can be defined for an application in its deployment descriptor. When a user authentication method is specified for an application, the web container activates the specified authentication mechanism when you attempt to access a protected resource. The options for user authentication methods are discussed in Understanding Login Authentication. The example application discussed in Example: Basic Authentication with JAX-RPC shows how to add basic authentication to a JAX-RPC application. The example discussed in Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC shows how to add client-certificate, or mutual, authentication to a JAX-RPC application.

A second approach is that a transport guarantee can be defined for an application in its deployment descriptor. Use this method to run over an SSL-protected session and ensure that all message content is protected for confidentiality. The options for transport guarantees are discussed in Specifying a Secure Connection. For an example application that demonstrates running over an SSL-protected session, see Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC.

When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data.

SSL technology allows web browsers and web servers to communicate over a secure connection. In this secure connection, the data is encrypted before being sent, and then is decrypted upon receipt and before processing. Both the browser and the server encrypt all traffic before sending any data. For more information, see What Is Secure Socket Layer Technology?.

Digital certificates are necessary when running HTTP over SSL (HTTPS). The HTTPS service of most web servers will not run unless a digital certificate has been installed. Digital certificates have already been created for the Application Server.

Example: Basic Authentication with JAX-RPC

In this section, we discuss how to configure JAX-RPC-based web service applications for HTTP basic authentication. With HTTP basic authentication, the web server authenticates a user by using the user name and password obtained from the web client. If the topic of authentication is new to you, please refer to the section titled Understanding Login Authentication. For an explanation of how basic authentication works, see Figure 32-2.

For this tutorial, we begin with the example application in <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/ and <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/ and add user name and password authentication. The resulting application can be found in the directories <INSTALL>/j2eetutorial14/examples/security/basicauth/ and <INSTALL>/j2eetutorial14/examples/security/basicauthclient/.

In general, the following steps are necessary to add basic authentication to a JAX-RPC application. In the example application included with this tutorial, many of these steps have been completed for you and are listed here to show what needs to be done should you wish to create a similar application.

Complete the JAX-RPC application as described in Creating a Simple Web Service and Client with JAX-RPC.

If the default port value is changed from 8080, see Setting the Port for information on updating the example files to reflect this change. The WAR files mentioned in this tutorial will not work if the port has been changed.

Edit the <INSTALL>/j2eetutorial14/examples/common/build.properties file and the admin-password.txt file. These files need to be modified because the properties in these file are specific to your installation. See Building the Examples for information on which properties need to be set in which files. While you are looking at these files, note the value entered for admin.user and check the file admin-password.txt for the value of the admin password.

Add a user with the name that matches the value set in the build.properties file (admin) for the admin.user property and a password that matches the value set in the admin-password.txt file for the AS_ADMIN_PASSWORD property to the file realm. Refer to the section Managing Users, for instructions for doing this.

Set security properties in the client code. For the example application, this step has been completed. The code for this example is shown in Setting Security Properties in the Client Code.

Add the appropriate security elements using deploytool. For this example, the security elements are added in the packaging and deployment phase. Refer to Adding Basic Authentication Using deploytool for more information.

Build, package, deploy, and run the web service. You will use the asant tool to compile the client and service, and deploytool to package and deploy the service. Instructions for this example can be found in Building, Packaging, Deploying, and Running the Example for Basic Authentication.

Setting Security Properties in the Client Code

The source code for the client is in the HelloClient.java file of the <INSTALL>/j2eetutorial14/examples/security/basicauthclient/src/ directory. For basic authentication, the client code must set username and password properties. The username and password properties correspond to the admin group (which includes the user name and password combination entered during installation) and the role of admin, which is provided in the application deployment descriptor as an authorized role for secure transactions. (See Setting Up Security Roles.)

The client sets the aforementioned security properties as shown in the following code. The code in bold is the code that has been added from the original version of the jaxrpc/staticstub example application.
package basicauthclient;

import javax.xml.rpc.Stub;

public class HelloClient {

    public static void main(String[] args) {
    
        if (args.length !=3) {
          System.out.println("HelloClient Error: Wrong 
           number of runtime arguments!");
          System.exit(1);
        }
        
        String username=args[0];
        String password=args[1];
        String endpointAddress=args[2];

      // print to display for verification purposes
        System.out.println("username: " + username);
        System.out.println("password: " + password);
        System.out.println("Endpoint address = " +
           endpointAddress); 


    try {
      Stub stub = createProxy();
        stub._setProperty(
          javax.xml.rpc.Stub.USERNAME_PROPERTY,
            username);
        stub._setProperty(
          javax.xml.rpc.Stub.PASSWORD_PROPERTY,
            password);
        stub._setProperty
          (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
          endpointAddress);

      HelloIF hello = (HelloIF)stub;
      System.out.println(hello.sayHello("Duke (secure)"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }    

    private static Stub createProxy() {
        // Note: MyHelloService_Impl is implementation-specific.
        return (Stub)(new
          MyHelloService_Impl().getHelloIFPort());
    }
} 
Read Static Stub Client for more information about JAX-RPC static stub clients.

Building, Packaging, Deploying, and Running the Example for Basic Authentication

To build, package, deploy, and run the security/basicauth example using basic authentication, follow these steps.

Building the Basic Authentication Service

Set up your system for running the tutorial examples if you haven't done so already by following the instructions in Building the Examples.

From a terminal window or command prompt, go to the <INSTALL>/j2eetutorial14/examples/security/basicauth/ directory.

Build the JAX-RPC service by entering the following at the terminal window or command prompt in the basicauth/ directory (this and the following steps that use asant assume that you have the executable for asant in your path; if not, you will need to provide the fully qualified path to the executable). This command runs the target named build in the build.xml file.

asant build

Packaging the Basic Authentication Service

You can package the basic authentication example using asant or deploytool, or you can just open the WAR file located in the <INSTALL>/j2eetutorial14/examples/security/provided-wars/basicauth.war file.

To package the example using asant, run the following command from the /basicauth directory:
asant create-war 
To package the example using deploytool, follow the steps described in Packaging and Deploying the Service with deploytool and Specifying the Endpoint Address. When following these steps, replace the following:

The path to the example should be replaced with <INSTALL>/j2eetutorial14/examples/security/basicauth/.

Replace helloservice with basicauth throughout.

Use /basicauth-jaxrpc for the Context Root field.

Adding Basic Authentication Using deploytool

For HTTP basic authentication, the application deployment descriptor, web.xml, includes the information on who is authorized to access the application, which URL patterns and HTTP methods are protected, and what type of user authentication method this application uses. This information is added to the deployment descriptor using deploytool. Its contents are discussed in more detail in Web-Tier Security and in the Java Servlet specification, which can be browsed or downloaded online at http://java.sun.com/products/servlet/.

If you packaged the example using deploytool, select the basic authentication example, BasicAuth, in the deploytool tree. If you packaged the example using asant, open the generated WAR file (basicauth.war) in deploytool and then select the basic authentication example.

Select the Security tabbed pane.

Select Basic in the User Authentication Method field.

Select Add Constraints to add a security constraint.

Select Add Collections to add a web resource collection.

Select the web resource collection from the list, and then select Edit Collections.

Select Add URL Pattern. Enter /hello in the text field. Click OK.

Select the HTTP GET and POST methods.

Click OK to close the Edit Contents dialog box.

Select Edit Roles on the Security tabbed pane to specify an authorized role for this application.

Click Edit Roles in the Authorized Roles dialog box to add an authorized user to this application. Click Add in the Edit Roles dialog box and add the Name of admin. Click OK to close this dialog box.

Select admin under the Roles In field, and then click Add to add it to the list of authorized roles for this application. Click OK to close the dialog box.

Note that the Authorized Roles list specifies admin, a group that was specified during installation. To map this role to a user, follow these steps.

Select the General tabbed pane.

Click the Sun-specific Settings button.

In the Sun-specific Settings dialog box, select User to Role Mappings from the View list.

Select admin from the list of roles.

Click the Edit button under the Users box.

Select admin from the Available Users list, and then click the Add button to map the role of admin (defined for the application) to the user named admin (defined for the Application Server). Click OK.

Note: If you don't see the list of users or groups that you defined using the Admin Console, connect to the Admin Server by double-clicking localhost:4848 in the deploytool tree and entering your admin user name and password. If this is not the current target server, change to this server by selecting it and then selecting FileSet Current Target Server.

Click Close to return to the General tabbed pane.

Select Save from the File menu to save these settings.

Deploying the Basic Authentication Service

To deploy the example using asant, run the following command:
asant deploy-war 
To deploy the example using deploytool, follow these steps:

Select the BasicAuth application in the deploytool tree. Then select ToolsDeploy.

Make sure the server is correct, localhost:4848 by default.

Enter your admin user name and password.

Click OK.

Click the Close button after the messages indicating successful completion are finished.

You can view the WSDL file of the deployed service by requesting the URL http://localhost:8080/basicauth-jaxrpc/hello?WSDL in a web browser.

Building and Running the Basic Authentication Client

To build the JAX-RPC client, do the following:

Enter the following command at the terminal window or command prompt in the basicauthclient/ directory:

asant build

Run the JAX-RPC client by entering the following at the terminal window or command prompt in the basicauthclient/ directory:

asant run

The client should display the following output:
Buildfile: build.xml

run-secure-client:
   [java] username: your_name
   [java] password: your_pwd
   [java] Endpoint address = http://localhost:8080/basicauth-
jaxrpc/hello
   [java] Hello Duke (secure)

BUILD SUCCESSFUL 
Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC

In this section, we discuss how to configure a simple JAX-RPC-based web service application for client-certificate authentication over HTTP/SSL. Client-certificate authentication uses HTTP over SSL, in which the server and, optionally, the client authenticate one another using public key certificates. If the topic of authentication is new to you, please refer to the section titled Understanding Login Authentication. For more information on how client-certificate authentication works, see Figure 32-4.

This example application starts with the example application in <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/ and adds both client and server authentication to the example. In SSL certificate-based basic authentication, the server presents its certificate to the client, and the client authenticates itself to the server by sending its user name and password. This type of authentication is sometimes called server authentication. Mutual authentication adds the dimension of client authentication. For mutual authentication, we need both the client's identity, as contained in a client certificate, and the server's identity, as contained in a server certificate inside a keystore file (keystore.jks). We also need both of these identities to be contained in a mutual trust-store (cacerts.jks) where they can be verified.

To add mutual authentication to a basic JAX-RPC service, complete the following steps. In the example application included with this tutorial, many of these steps have been completed for you and are listed here to show what needs to be done should you wish to create a similar application.

Complete the JAX-RPC application as described in Creating a Simple Web Service and Client with JAX-RPC.

Create the appropriate certificates and keystores. For this example, the certificates and keystores are created for the server as a generic localhost and are included with the Application Server. See the section Keystores and Trust-Stores in the Mutual Authentication Example for a discussion of how to create the client certificates for this example.

If the port value is changed from the default of localhost:8080, see Setting the Port for information on updating the example files to reflect this change. The WAR files mentioned in this tutorial will not work if the port has been changed.

Edit the build.properties files to add the location and password to the trust-store, and other properties, as appropriate. For a discussion of the modifications that need to be made to build.properties, see Modifying the Build Properties. While you are looking at this file, note the value entered for admin.user. Also note the value for the admin password as specified in the file admin-password.txt in the field AS_ADMIN_PASSWORD.

Add a user to the file realm with the name that matches the value set in the build.properties file (admin) for the admin.user property and a password that matches the value set in the admin-password.txt file for the AS_ADMIN_PASSWORD property. Refer to the section Managing Users, for instructions for doing this.

Set security properties in the client code. For the example application, this step has been completed. For a discussion of the security properties that have been set in HelloClient, see Setting Security Properties in the Client Code.

Add the appropriate security elements using deploytool. The security elements are discussed in the section Enabling Client-Certificate Authentication for the Mutual Authentication Example.

Build, package, and deploy the service, deploy the server, and then build and run the client (see Building, Packaging, Deploying, and Running the Mutual Authentication Example). You will use the asant tool to compile the client and service and to run the client. You will use deploytool to package and deploy the service.

Keystores and Trust-Stores in the Mutual Authentication Example

In this example, the keystore file (keystore.jks) and the trust-store file (cacerts.jks) have been created for the server as a generic localhost and are included with the Application Server in the directory <J2EE_HOME>/domains/domain1/config/. You must follow the instructions in Creating a Client Certificate for Mutual Authentication to create a client certificate and add it to the existing trust-store. You must create the client certificates in the directory <J2EE_HOME>/domains/domain1/config/, and you must restart the Application Server for the client certificate to be accessed by the application.

Modifying the Build Properties

To build and run the application with mutual authentication, we have set up the example so that some of the values are passed to the application from various build.properties files.

To run any of the examples, you must modify the build.properties file located in the <INSTALL>/j2eetutorial14/examples/common/ directory to provide your admin password and the location where the Application Server is installed. If you need more information, see Building the Examples.

For this example, the build.properties file that is specific to this application, <INSTALL>/j2eetutorial14/examples/security/common/build.properties, has been modified for you. This file provides specific information about the JAX-RPC examples to the asant targets we will be running later. This information concerns the location of the keystore and trust-store files and their associated passwords.

Make sure that the following properties exist and are correctly defined.
trust.store=${j2ee.home}/domains/domain1/config/cacerts.jks 
trust.store.password=changeit
key.store=${j2ee.home}/domains/domain1/config/keystore.jks
key.store.password=changeit 
Setting Security Properties in the Client Code

The source code for the client is in the HelloClient.java file of the <INSTALL>/j2eetutorial14/examples/security/mutualauthclient/src/ directory. For mutual authentication, the client code must set several security-related properties. These values are passed into the client code when the asant build and run tasks are executed.

trustStore: The value of the trustStore property is the fully qualified name of the trust-store file: <J2EE_HOME>/domains/domain1/config/cacerts.jks.

trustStorePassword: The trustStorePassword property is the password of the trust-store. The default value of this password is changeit.

keyStore: The value of the keyStore property is the fully qualified name of the keystore file: <J2EE_HOME>/domains/domain1/config/keystore.jks

keyStorePassword: The keyStorePassword property is the password of the keystore. The default value of this password is changeit.

ENDPOINT_ADDRESS_PROPERTY: The ENDPOINT_ADDRESS_PROPERTY property sets the endpoint address that the stub uses to access the service.

The client sets the aforementioned security properties as shown in the following code. The code in bold is the code that has been added from the original version of the jaxrpc/staticstub example application.
package mutualauthclient;

import javax.xml.rpc.Stub;

public class HelloClient {

    public static void main(String[] args) {
    
        if (args.length !=5) {
          System.out.println("HelloClient Error: Need 5
        runtime arguments!");
          System.exit(1);
        }
        
        String keyStore=args[0];
        String keyStorePassword=args[1];
        String trustStore=args[2];
        String trustStorePassword=args[3];
        String endpointAddress=args[4];


      // print to display for verification purposes
        System.out.println("keystore: " + keyStore);
        System.out.println("keystorePassword: " +
        keyStorePassword);
        System.out.println("trustStore: " + trustStore);
        System.out.println("trustStorePassword: " +
        trustStorePassword);
        System.out.println("Endpoint address: " +
        endpointAddress);

    try {
      Stub stub = createProxy();
      System.setProperty("javax.net.ssl.keyStore",
        keyStore);
      System.setProperty("javax.net.ssl.keyStorePassword",
        keyStorePassword);
      System.setProperty("javax.net.ssl.trustStore",
        trustStore);
      System.setProperty("javax.net.ssl.trustStorePassword",
        trustStorePassword);
      stub._setProperty(
          javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
            endpointAddress);

      HelloIF hello = (HelloIF)stub;
      System.out.println(hello.sayHello("Duke! (        secure!"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }    

    private static Stub createProxy() {
        // Note: MyHelloService_Impl is implementation-specific.
        return (Stub)(new
          MySecureHelloService_Impl().getHelloIFPort());
    }
} 
Enabling Client-Certificate Authentication for the Mutual Authentication Example

The two ways of implementing client authentication are discussed in Enabling Mutual Authentication over SSL. You can set client authentication for all applications (by specifying this in the deployment descriptor for the server) or for only a single application (by specifying this in the deployment descriptor for the application). For this example, we are enabling client authentication for this application only, so we specify the login authentication method as being Client-Certificate. The steps for adding client-certificate authentication are shown in Adding Client-Certificate Authentication Using deploytool.

For more information on login configuration options, read Understanding Login Authentication.

The user authentication method specifies a client-certificate method of authentication in this example. For this authentication to run over SSL, you must also specify which type of transport guarantee to use. For this example, we have chosen CONFIDENTIAL, which is specified in the Network Security Requirement field on the Security tabbed pane in deploytool.

For more information on this type of constraint, read Specifying a Secure Connection.

Building, Packaging, Deploying, and Running the Mutual Authentication Example

To build, deploy, and run the JAX-RPC service example with mutual authentication, follow these steps.

Building the Mutual Authentication Example

To compile the application files and copy them to the correct directories, run the asant build task. More information on what happens when the build task is called can be found in Building the Service.

If you haven't already done so, follow these steps for setting up the example.

Using SSL

Building the Examples

Go to the <INSTALL>/j2eetutorial14/examples/security/mutualauth/ directory.

Build the JAX-RPC service by entering the following at the terminal window or command prompt in the mutualauth/ directory (this and the following steps that use asant assume that you have the executable for asant in your path; if not, you will need to provide the fully qualified path to the asant executable):

asant build

Change to the directory <INSTALL>/j2eetutorial14/examples/security/mutualauthclient/.

Build the JAX-RPC client by entering the following at the terminal window or command prompt:

asant build

Packaging the Mutual Authentication Example

You can package the mutual authentication example using asant or deploytool, or you can open the WAR file located in the <INSTALL>/j2eetutorial14/examples/security/provided-wars/mutualauth.war file.

To package the example using asant, run the following command and then skip to the section titled Deploying the Mutual Authentication Example:
asant create-war 
To package the example using deploytool, follow the steps described in Packaging and Deploying the Service with deploytool and Specifying the Endpoint Address. When following these steps, replace the following:

The path to the example should be replaced with <INSTALL>/j2eetutorial14/examples/security/mutualauth/.

Replace helloservice with mutualauth throughout.

Use /mutualauth-jaxrpc for the Context Root field.

Adding Client-Certificate Authentication Using deploytool

For HTTP client-certificate authentication, the application deployment descriptor, web.xml, includes the information on who is authorized to access the application, which URL patterns and HTTP methods are protected, and what type of user authentication method this application uses. This information is added to the deployment descriptor using deploytool, and its contents are discussed in more detail in Web-Tier Security and in the Java Servlet specification, which can be browsed or downloaded online at http://java.sun.com/products/servlet/.

If you packaged the example using deploytool, select the MutualAuth example in the deploytool tree. If you packaged the example using asant, you can ignore this section as these steps were completed by the asant task.

Select the Security tabbed pane.

Select Client Certificate in the User Authentication Method field.

Select Add Constraints to add a security constraint.

Select Add Collections to add a web resource collection.

Select the web resource collection from the list, and then select Edit Collections.

Select Add URL Pattern. Enter /hello in the text field. Click OK.

Select the HTTP GET and POST methods.

Click OK to close the Edit Contents dialog box.

Select CONFIDENTIAL under Network Security Requirement so that the application requires HTTP/SSL.

Select Save from the File menu to save these settings.

Deploying the Mutual Authentication Example

To deploy the example using asant, run the following command:
asant deploy-war 
To deploy the application using deploytool, follow these steps:

Deploy the JAX-RPC service by selecting the MutualAuth example in the deploytool tree. Then select ToolsDeploy.

Make sure the server is correct. By default, this will be localhost:4848.

Enter your admin user name and password.

Click OK.

Click the Close button after the messages indicating successful completion are finished.

Running the Mutual Authentication Example

Enter the following command from the mutualauthclient/ directory at the terminal window or command prompt to run the JAX-RPC client:
   asant run 
The client should display the following output:
Buildfile: build.xml

run-mutualauth-client:
     [java] keystore: <J2EE_HOME>/domains/domain1/config/
keystore.jks
     [java] keystorePassword: changeit
     [java] trustStore: <J2EE_HOME>/domains/domain1/config/
cacerts.jks
     [java] trustStorePassword: changeit
     [java] Endpoint address = https://localhost:8181/
mutualauth-jaxrpc/hello

     [java] Hello Duke (secure)

run:

BUILD SUCCESSFUL 
For information on verifying that mutual authentication is running, see Verifying That Mutual Authentication Is Running.