Security for JEUS web services can be applied in the following ways.

The following shows the JEUS Web service security architecture.

[Figure 27.1] 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.

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.

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.

<jeus-webservices-dd>
    <service>
        <webservice-description-name/>
        <port>
            <port-component-name/>
            <security>
                <request-receiver/> 
                <response-sender/>
            </security>
        </port>
    </service>
</jeus-webservices-dd>

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.

<jeus-web-dd>
    <service-ref>
        <service-client>
            <service-ref-name/>
            <port-info>
                <wsdl-port/>
                <security>
                    <request-sender/>
                    <response-receiver/>
                </security>
            </port-info>
            . . .
        </service-client>
        <service-client>
            . . .
        </service-client>
        . . .
    </service-ref>
</jeus-webservices-client-dd>

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.

package jeustest.webservices.wssec.doall;

import com.tmax.ws.security.WSPasswordCallback;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import java.io.IOException;

public class PWCallback implements CallbackHandler {
    public void handle(Callback[] callbacks)
        throws IOException, UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            if (callbacks[i] instanceof WSPasswordCallback) {
                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];
                checkPassword(pc);
            } else {
                throw new UnsupportedCallbackException(
                    callbacks[i], "Unrecognized Callback");
            }
        }
    }

    public void checkPassword(WSPasswordCallback pc) {
        String userId = pc.getIdentifier();
        if (pc.getUsage() == WSPasswordCallback.USERNAME_TOKEN) {
            if (userId.equals("16c73ab6-b892-458f-abf5-2f875f74882e")) {
                pc.setPassword("security2");
            }
            if (userId.equals("key_tmax1")) {
                pc.setPassword("keypass_tmax1");
            }
        } else if (pc.getUsage() == WSPasswordCallback.DECRYPT) {
            if (userId.equals("16c73ab6-b892-458f-abf5-2f875f74882e")) {
                pc.setPassword("security");
            }
            if (userId.equals("key_tmax1")) {
                pc.setPassword("keypass_tmax1");
            } 
        } else if(pc.getUsage() == WSPasswordCallback.SIGNATURE) {
            if (userId.equals("16c73ab6-b892-458f-abf5-2f875f74882e")) {
                pc.setPassword("security");
            }
            if (userId.equals("key_tmax1")) {
                pc.setPassword("keypass_tmax1");
            }
        }
    }
}

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.

This section describes each step.

package ping;

public interface Ping extends java.rmi.Remote {
    public String ping(String arg) throws
        java.rmi.RemoteException;
}

package ping;

public class PingImpl implements Ping {
    public String ping(String arg) throws
        java.rmi.RemoteException {
        return arg;
    }
}

package ping;

import com.tmax.ws.security.WSPasswordCallback;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import java.io.IOException;

public class PingPWCallback implements CallbackHandler {
    public void handle(Callback[] callbacks) throws
        IOException, UnsupportedCallbackException {
        for ( int i = 0 ; i<callbacks.length; i++) {
            if(callbacks[i] instanceof WSPasswordCallback) {
                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i];

                if(pc.getUsage()== WSPasswordCallback.USERNAME_TOKEN) {
                    pc.setPassword("usertoken_password");
                }

                if(pc.getUsage()== WSPasswordCallback.DECRYPT){
                    pc.setPassword("key_password");
                }

                if(pc.getUsage()== WSPasswordCallback.SIGNATURE) {
                    pc.setPassword("key_password");
                }
            }
        }
    }
}

. . .
<security>
    <request-receiver>
        <action-list>
            UsernameToken Signature Encrypt
        </action-list>
        <password-callback-class>
            ping.PingPWCallback
        </password-callback-class>
        <decryption>
            <keystore>
                <key-type>jks</key-type>
                <keystore-password>
                    keystore_password
                </keystore-password>
                <keystore-filename>
                    server-keystore.jks
                </keystore-filename>
            </keystore>
        </decryption>
        <signature-verification>
            <keystore>
                <key-type>jks</key-type>
                <keystore-password>
                    keystore_password
                </keystore-password>
                <keystore-filename>
                    server-keystore.jks
                </keystore-filename>
            </keystore>
        </signature-verification>
    </request-receiver>
    . . .
</security>
. . .

ant

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.

This section describes each step.

. . . 
InitialContext jndiContext = new InitialContext();

Service service = (Service)jndiContext.lookup(
"java:comp/env/service/PingSecurityService");

QName portName = new QName("urn:PingSecurityService","PingPort");
java.rmi.Remote port = service.getPort(portName, Ping.class);

Ping pingPort = (Ping)port;
ret = pingPort.ping(msgToSend);
. . .

. . .
<security>
    <request-sender>
        <action-list>
            UsernameToken Signature Encrypt
        </action-list>
        <password-callback-class>
            ping.PingPWCallback
        </password-callback-class>
        <user>JEUS_CLIENT</user>
        <signature-infos>
            <signature-info>
                <keyIdentifier>DirectReference</keyIdentifier>
                <keystore>
                    <key-type>jks</key-type>
                    <keystore-password>
                        keystore_password
                    </keystore-password>
                    <keystore-filename>
                        client-keystore.jks
                    </keystore-filename>
                </keystore>
            </signature-info>
        </signature-infos>
        <encryption-infos>
            <encryption-info>
                <encryptionUser>JEUS_SERVER</encryptionUser>
                <keyIdentifier>DirectReference</keyIdentifier>
                <keystore>
                    <key-type>jks</key-type>
                    <keystore-password>
                        keystore_password
                    </keystore-password>
                    <keystore-filename>
                        client-keystore.jks
                    </keystore-filename>
                </keystore>
            </encryption-info>
        </encryption-infos>
    </request-sender>
    . . .
</security>
. . .

ant

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.

<%@ 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 "27.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.

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.

<accounts xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <users>
        <user>
            <name>jeus</name>
            <password>{SHA}McbQlyhI3yiOG1HGTg8DQVWkyhg=</password>
        </user>
    </users>
</accounts>

Configuring a DD File

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

<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <docbase>BA_DocLitEchoService</docbase>
    <role-mapping>
        <role-permission>
            <principal>jeus</principal>
            <role>Administrator</role>
        </role-permission>
    </role-mapping>
</jeus-web-dd>

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

<web-app…>
    . . .
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>MySecureBit</web-resource-name>
            <url-pattern>/BA_DocLitEchoService</url-pattern>
            <http-method>POST</http-method>
            <http-method>GET</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>Administrator</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>default</realm-name>
    </login-config>    
</web-app>

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.

<accounts xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <users>
        <user>
            <name>jeus</name>
            <password>{SHA}McbQlyhI3yiOG1HGTg8DQVWkyhg=</password>
        </user>
    </users>
</accounts>

Configuring a DD file

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

<jeus-ejb-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <module-info>        
        <role-permission>
            <principal>jeus</principal>
            <role>Administrator</role>
        </role-permission>
    </module-info>
    <beanlist>
        …
    </beanlist>
</jeus-ejb-dd>

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

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar …>
    <display-name>AddressEjb</display-name>
    <enterprise-beans>
        …
    </enterprise-beans>
    <assembly-descriptor>
        <security-role>
            <role-name>Administrator</role-name>
        </security-role>
        <method-permission>
            <role-name>Administrator</role-name>
            <method>
                <ejb-name>AddressEJB</ejb-name>
                <method-intf>ServiceEndpoint</method-intf>
                <method-name>listAll</method-name>                
            </method>
        </method-permission>
    </assembly-descriptor>
</ejb-jar>

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.

<jeus-webservices-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <ejb-context-path>webservice</ejb-context-path>
    <ejb-login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>default</realm-name>
    </ejb-login-config>
    <service>
        <webservice-description-name>…</webservice-description-name>
        <port>
            <port-component-name>…</port-component-name>
            <ejb-endpoint-url>… </ejb-endpoint-url>
            <ejb-transport-guarantee>
                CONFIDENTIAL
            </ejb-transport-guarantee>
        </port>
    </service>
</jeus-webservices-dd>

In order to invoke a web service that is configured with basic authentication, a stub must be generated based on the information from the WSDL. The stub is used to call the web service, and in case a username and password are required they must also be configured.

Creating a Stub from WSDL

When using a console tool, use the following options.

wsdl2java -gen:client -username jeus -password jeus 
http://localhost:8088/BA_DocLitEchoService/BA_DocLitEchoService?wsdl

Creating Web Service Clients for a Web Service Configured with Basic Authentication

The following two configurations must be included in the client application to allow a JAX-RPC web service client to authenticate itself.

The following example shows how to include the configurations in a client program.

Echo port = // … obtaining SEI
((javax.xml.rpc.Stub) port)._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, 
      "jeus");
((javax.xml.rpc.Stub) port)._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, 
      "jeus");
String s = port.echoString("JEUS");