Chapter 26. JAX-RPC Web Service Security

Table of Contents

26.1. Overview
26.2. Transport-Level Security
26.3. Message-Level Security
26.3.1. Applying Web Service Security
26.3.2. Web Service Security Architecture
26.3.3. Configuring JEUS Web Service Security
26.3.4. Creating a Password Callback Class
26.3.5. Example of Server-side JEUS Web Service Security
26.3.6. Example of Client-side JEUS Web Service Security
26.3.7. Creating JEUS Web Service Client Using Web Service Security API
26.4. Configuring Access Control
26.4.1. Configuring Access Control Security for Java Web Services
26.4.2. Configuring Access Control for EJB Web Services
26.4.3. Invoking Web Services Configured with Basic Authentication

This chapter describes how to configure security for JAX-RPC Web services.

There are two main security types for Web services.

Transport-level security of JEUS web services is used to secure the connection between the client application and web server by using the Secure Sockets Layer (SSL) protocol.

The following are the steps for transport-level security.

  1. Configure SSL for JEUS server.

    There are no additional settings required for JEUS web service development. Refer to "JEUS Web Engine Guide" for information about the SSL configuration on a JEUS server.

  2. Configure SSL for a client application using these steps.

    1. Obtain the digital certificates. (Save the certificates to a local directory via the Internet Explorer, etc.)

    2. Store the certificates in the Keystore.

    3. Configure the following system properties in order to create stubs from WSDL by using wsdl2java or execute a client to invoke the web service.

      –Djavax.net.ssl.trustStore=keystore_name
      –Djavax.net.ssl.trustStorePassword=keystore_password
    4. To use the wsdl2java console tool instead of ANT, configure the environment variables as in the following.

      set WSDL2JAVA_OPTS=-Djavax.net.ssl.trustStore=keystore_name 
            -Djavax.net.ssl.trustStorePassword=keystore_password

Message-level security ensures that the SOAP messages between a web service and a client, which calls the service, to be digitally signed or encrypted, or both.

JEUS web services support the following OASIS Standard 1.0 web Services Security.

  • OASIS Standard 1.0

    • SOAP Message Security V1.0

    • Username Token Profile V1.0

    • X.509 Token Profile V1.0

These standards define requirements for authentication, authorization, data integrity, and confidentiality to help resolve many security issues in enterprise applications.

The following shows the JEUS Web service security architecture.


The server keystore is configured in the jeus-webservices-dd.xml file, and the client keystore is configured in the jeus-web-dd.xml file.

Secure Message Communication Between JEUS JavaEE Web Service Client and JEUS Web Service

In order to apply security to a pre-existing web service, you must configure the <security> element of the jeus-webservices-dd.xml file and create a keystore. You must also create a callback class for setting the access password for the keystore or the password to use in a UsernameToken. JEUS server applies security to the web service when the application is redeployed.

Java EE client must also set the <security> element of the jeus-web-dd.xml file, and create a keystore for the client's key. A callback class must be created in order to set a password for the Username Token and one for obtaining a private key from the key store.

When a Java EE client application is executed, the web service client runtime applies security logic according to the value of the <security> element of the jeus-web-dd.xml file. The runtime sends the message to the web service runtime of JEUS Server by encrypting the message with a server-side public key or by signing with the private key from the client key store.

The server runtime performs security logic based on the value of the <security> element in the jeus-webservices-dd.xml file.

  • If the message is signed, the signature is authenticated by using the client-side public key from the key store based on the information about the key used to sign the message.

  • If the message is encrypted, the server runtime decrypts the message by using the client's private key from the server-side keystore.

Similar procedures are used to apply security when the server tries to send a response message back to the client after invoking a web service.

  • A Web service takes a server-side private key or a client-side public key from the key store, using the <security> element value, to sign or encrypt the whole or a part of a response message.

  • A client runtime uses the server-side public key or client-side private key from the client key store, also using the <security> element value, to verify and decrypt the response message.

Interoperability of Message Security between JEUS and Third Party Vendors

Message-level security is used for web services. Interoperability is guaranteed when the security related information included in a secure SOAP message conforms to the OASIS Standard 1.0 Web Service Security.

Since JEUS conforms to the web service security standard 1.0, the latest version of OASIS security standards, it is possible to exchange and process messages between any vendors conforming to the same standard.

To exchange secure messages between a JEUS web service and JEUS web service client, the <security> element of the jeus-webservices-dd.xml file must be configured for the JEUS web service, and the <security> element of the jeus-web-dd.xml file must be configured for the JEUS web service client.

Configuring Server-Side Security

The <security> element in the jeus-webservices-dd.xml file is required for every web service port. For more information, refer to "24. jeus-webservices-dd.xml" of the "JEUS XML Reference".

The following is an example of the server-side security configurations.


The information required for the server to securely process the messages from the client must be set in the <request-receiver> element, a child element of the <security> element. The information required for the client to securely process the messages from the server must be set in the <request-sender> element.

Configuring Client-side Security

The <security> element added to the jeus-web-dd.xml file is required for every <port-info> element. For more information, refer to "19. jeus-web-dd.xml" of the "JEUS XML Reference".

The following is an example of the client-side security configurations.


The <request-sender> element, which is a sub-element of the <security> element, specifies the information necessary for the server to handle secure messages requested by the client. The <response-receiver> element specifies the information necessary for the client to handle secure response messages from the server.

In order to apply security to JEUS web services, you must create a callback class for setting the access password for the keystore or the password for use in a UsernameToken. The Callback class must implement the javax.security.auth.callback.CallbackHandler interface.

The following example shows how to implement a password callback class.


The WSPasswordCallback.getUsage() method returns a value that specifies when to use the callback parameter. If the parameter is used for setting a password in the UsernameToken, it returns the value 'USERNAME_TOKEN'. If it is used for setting a password to decrypt a secure message, it returns the value 'DECRYPT'. These implementations are also required to set a password for obtaining a private key for a signature from the key store or for configuring a session key.

The name of a callback class must be specified in the <password-callback-class> element of the jeus-webservices-dd.xml or jeus-web-dd.xml file.

A secure web service that sends/receives a string message is implemented in the following steps.

  1. Create a keystore that is required for encrypting and applying digital signature to a SOAP message.

  2. Create a Java class.

  3. Configure the DD.

  4. Complete packaging and deployment.

This section describes each step.

A pair of keys are required to encrypt and apply digital signature to a SOAP message. This can be easily implemented by using the keytool provided in Java. There are many other methods besides keytool, but this section uses the keytool as an example. For more information, refer to the help for keytool.

Execute 'keygen' from the directory with the sample files.

  1. Create a keystore file called 'server-keystore.jks' and set the password to 'keystore_password'. Then create a private key (with an alias of 'JEUS_SERVER') by using the RSA algorithm. The password for the private key is 'key_password'. A pair of public keys for the 'JEUS_SERVER' private key is also automatically created.

    keytool -genkey -alias JEUS_SERVER -keyalg rsa -keypass
    key_password -keystore server-keystore.jks -storepass
    keystore_password
  2. Create a keystore file called 'client-keystore.jks' and set the password to 'keystore_password'. Then create a private key (with an alias of 'JEUS_CLIENT') by using the RSA algorithm. The password for the private key is ‘key_password’. A pair of public keys for the 'JEUS_CLIENT' private key is also automatically created.

    keytool -genkey -alias JEUS_CLIENT -keyalg rsa -keypass
    key_password -keystore client-keystore.jks -storepass
    keystore_password
  3. Obtain the 'JEUS_SERVER' public key from the 'server-keystore.jks' file, which will be used as the server-side keystore.

    keytool -export -alias JEUS_SERVER -storepass keystore_password
    -keystore server-keystore.jks -file jeus_server.cert
  4. Save it in the 'client-keystore.jks' file (keystore for web service client) by using the alias, 'JEUS_SERVER'.

    keytool -import -file jeus_server.cert -keystore
    client-keystore.jks -storepass keystore_password -alias JEUS_SERVER
  5. Obtain the 'JEUS_CLIENT' public key from the 'client-keystore.jks' file, which will be used as the client-side keystore.

    keytool -export -alias JEUS_CLIENT -storepass keystore_password
    -keystore client-keystore.jks -file jeus_client.cert
  6. Save it in the 'server-keystore.jks' file (keystore for web service) by using the alias, 'JEUS_CLIENT'.

    keytool -import -file jeus_client.cert -keystore
    server-keystore.jks -storepass keystore_password -alias JEUS_CLIENT

The client example is very similar to the server example. The tasks for the callback class, configuration file, and keystore packaging are required in addition to the normal task of creating a web service client.

A client-side JEUS web service security is implemented in the following steps.

  1. Create a keystore that is required for encrypting and applying digital signature to a SOAP message.

  2. Create a Java class.

  3. Configure the DD.

  4. Complete packaging and deployment.

This section describes each step.

JEUS web services provide the Web Service Security API that enables easy creation of web service clients for both Java EE and Java SE environments.

The following example shows a secure web service client that uses the API.

[Example 26.10] << pingClient.jsp >>

<%@ page language="java" %>
<%@ page import="javax.naming.*" %>
<%@ page import="javax.rmi.*" %>
<%@ page import="java.rmi.RemoteException" %>
<%@ page import="java.util.*" %>

<%@ page import="javax.naming.InitialContext" %>
<%@ page import="javax.xml.rpc.Service" %>
<%@ page import="javax.xml.namespace.QName" %>

<%@ page import="jeus.webservices.wssecurity.SecurityConfiguration"%>
<%@ page import="jeus.webservices.wssecurity.Keystore" %>

<%@ page import="ping.*" %>
<%@ page errorPage="/error.html" %>

<%! String msgToSend = "msg_sent_by_jspClient";
    String ret=null;
    String exceptionString="";
%>

<%
    try {
(1)     Keystore keystore = new Keystore ("JKS", "keystore_password", 
                           "client-keystore.jks");
        Keystore truststore = new Keystore ("JKS","keystore_password", 
                           "client-keystore.jks");

        InitialContext jndiContext = new InitialContext();
            
        Service service = 
          (Service)jndiContext.lookup("java:comp/env/service/PingSecurityService");
        QName portName = new QName("urn:PingSecurityService", "PingPort");

(2)     SecurityConfiguration sconfig = 
            new SecurityConfiguration(service, portName);
(3)     sconfig.setUsername("JEUS_CLIENT");
(4)     sconfig.setRequestPasswordCallbackClass("ping.PingPWCallback");
            
(5)     sconfig.addUTRequest(true, true);
(6)     sconfig.addSignRequest(null, "DirectReference", keystore);
(7)     sconfig.addEncryptRequest(null, "DirectReference", 
            truststore, "JEUS_SERVER", null);

(4)     sconfig.setResponsePasswordCallbackClass("ping.PingPWCallback");
        sconfig.addUTResponse();
        sconfig.addSignResponse(truststore);
        sconfig.addDecryptResponse(keystore);

        java.rmi.Remote port = service.getPort(portName, Ping.class);
        Ping pingPort = (Ping)port;
            
        ((javax.xml.rpc.Stub)pingPort)._setProperty(
            javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
            "http://localhost:8088/PingSecurity" + "/PingSecurityService");
            
        System.out.println("Send : " + msgToSend);
        ret = pingPort.ping(msgToSend);
        System.out.println("You received : " + ret);
    } catch (Exception e) {
        exceptionString = e.toString();
        e.printStackTrace();
    }
%>
<%= "Result is " + ret + "......" 
%>
<%= exceptionString
%>


The text in bold represents the configurations related to the web service security. The jeus.webservices.wssecurity.SecurityConfiguration object must be instantiated for security configurations, and the user name and password callback class must be specified to create a secure request message. For information about instantiating a callback class object, refer to "26.3.4. Creating a Password Callback Class".

The provided API can be used to add any configurations related to the username token, encryption, or digital signature. The jeus.webservices.wssecurity.Keystore class can be instantiated to configure the keystore settings.

[Reference]

The following are additional methods that are available for use but are not used in the examples of this chapter.

  • Processing TimeStamp

    Use the following method to add a TimeStamp element to a secure request message.

    public void addTimeStampRequest()

    Use the following method to set the message expiration period of a secure web service request message. By default, the period is set to 300 seconds.

    public void addTimeStampRequest(int timeToLive)

    Use the following method when the secure response message is expected to include the TimeStamp element.

    public void addTimeStampResponse()

    Only use the following method when the expiration date set in the TimeStamp element for the secure response message is within the time period specified by the argument.

    public void addTimeStampResponse(int timeToLive)

Access control configuration can be set to only allow authorized users to call the web service. The access control configuration varies depending on the web service backends. This section describes how to set the web service access control, and how to call an access-controlled web service.

Web service access can be controlled by applying access control to the URL of the web service. In order to apply access control, security information has to be specified in the deployment descriptor files ('web.xml' and 'jeus-web-dd.xml'). A secure domain configuration is also required.

Configuring Secure Domain

First, a user must be registered to apply access control.

Register the user in the following file.

JEUS_HOME/config/{NODE_NAME}/security/{SECURITY_DOMAIN_NAME}/accounts.xml

The following is an example of registering a user with the username of "jeus" and password of "jeus". The password must be encrypted using Base64 encoding.


Configuring a DD File

Add the following <role-mapping> element to the jeus-web-dd.xml file.


Then add the following security related settings to the web.xml file.


When the previous setting is applied, only the user with the username "jeus" and password "jeus" can access the URL, '/BA_DocLitEchoService'.

Similar to a Java web service, the access to an EJB web service can be controlled by applying access control to the web service URL. In order to apply access control, security information has to be specified in the deployment descriptor files ('ejb-jar.xml' and 'jeus-ejb-dd.xml') and the web service deployment descriptor file ('jeus-webservices-dd.xml'). A secure domain configuration is also required.

Configuring Secure Domain

First, a user must be registered to apply access control.

Register the user in the following file.

JEUS_HOME/config/{NODE_NAME}/security/{SECURITY_DOMAIN_NAME}/accounts.xml

The following is an example of registering a user with the username of "jeus" and password of "jeus". The password must be encrypted using Base64 encoding.


Configuring a DD file

Add the following <role-permission> element to the jeus-ejb-dd.xml file.


Then add the following security related settings to the ejb-jar.xml file.


The following configurations can be additionally set in the web service deployment descriptor. Default values are used if they are not configured. In order to guarantee the data integrity of SSL socket communication, the <ejb-transport-guarantee> must be set to 'INTEGRAL'. If both the confidentiality and data integrity must be guaranteed, set it to 'CONFIDENTIAL'. A separate HTTP listener configuration is also required to enable HTTPS communication.