Sun Java System Application Server 

Samples Index

The SSL-JAXWS-EAR Sample Application

Through a Tax calculation service, this sample demonstrates how to create a secure JAXWS web service endpoint (https) and access it using a Java application client. The service is protected at transport level and accessed by performing SSL server side authentication.

Secure the Web Service Endpoint at Transport Level (https)

To protect the webservice endpoint at transport level, the Java EE web application's runtime xml (sun-web.xml) should include the element <transport-guarantee> . Here, webservice-endpoint should match the above JAX-WS endpoint.

See the snapshot used in the sample.
 

        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_5-0.dtd">
        <sun-web-app error-url="">
            <context-root>ssl-jaxws</context-root>
            <servlet>
                <servlet-name>Tax</servlet-name>
                <webservice-endpoint>
                    <!-- default name is namePort -->
                    <port-component-name>Tax</port-component-name>
                    <!-- default name service_name/name -->
                    <endpoint-address-uri>TaxService</endpoint-address-uri>
                    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
                </webservice-endpoint>
            </servlet>
        </sun-web-app>

Once the endpoint is deployed, you can access the service using https protocol (instead of http) as follows, and see the <soap:address location="https://.."> in the wsdl file with https protocol:

https://localhost:8181/ssl-jaxws-war/TaxService?wsdl

Generation of artifacts when endpoint is secured using https

To compile a client, we need some special files that the Tax web service will give us. This is required so that the client has the web service interfaces and ports available. Use wsimport, an App Server-supplied program, to do this. To accept the server certificate, set the SSL trust store as system property in the environment variable, VMARGS. See the snapshot below:


set VMARGS=-Djavax.net.ssl.trustStore=${javaee.domaindir}/config/cacerts.jks
where cacerts.jks is the default trust store for the application server.

${javaee.home}/bin/wsimport -d ./build http://${javaee.server.name}:${javaee.server.port}/ssl-jaxws-war/TaxService?wsdl"/>

Runtime Environment of the AppClient During  Secured https Access to WS

The appclient runtime environment should have the SSL truststore path to be set in the VMARGS environment variable before running the client. You can run the client like this:

set VMARGS=-Djavax.net.ssl.trustStore=${javaee.domaindir}/config/cacerts.jks
cd ./build
${javaee.home}/bin/appclient webservices.ssl_jaxws_appclient.TaxCalClient income deductions

To debug whether SSL is involved or not, you can add -Djavax.net.debug=SSL,handshake  (JSSE system property) to VMARGS. During runtime you can see all the activities of ssl handshake.


Source Code and Instructions for Building and Running the Sample

The source code can be viewed by clicking these links: jax-ws web service and client.

Follow these instructions to build, deploy, and run this sample application.

  1. Setup your build environment and Configure the application server with which the build system has to work by following the common build instructions.
  2. app_dir is the sample application base directory: samples_install_dir/javaee5/webservices/ssl-jaxws-ear.
  3. Change directory to app_dir.
  4. Build, Deploy and Run the sample application using the target all

    5. app_dir> ant all

    expected output:
    run-client:
    [exec] Invoking TaxService...
    [exec] Income=90000.0
    [exec] Deductions=10000.0
    [exec] Federal tax=16000.0

Building, Deploying, and Running the Application in NetBeans IDE

Working with NetBeans team to make this sample work in NetBeans IDE. Will update this section with the progress.

Troubleshooting

If you have problems when running the application, refer to troubleshooting document.

If you see the following certificate error, make sure that the VMARGS (for appclient) or -Djavax.net.ssl.trustStore (for Java SE client) environment has the trust store path.
javax.xml.ws.WebServiceException: HTTP transport error: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate found