Build Web services with transport-level security using Rational Application Developer V7, Part 3: Configure HTTPS

Part 1 and Part 2 of this three-part tutorial series showed you how to develop Web services and clients, and configure HTTP basic authentication. In this final installment, you create a self-signed certificate, key store, trust store, and Secure Sockets Layer (SSL) configuration using the IBM® WebSphere® Administrative Console. Then you configure HTTPS for your Web services and Web services client, and test HTTPS Web services from both a Java™ Platform, Enterprise Edition (Java EE) client and a stand-alone Java client.

Henry Cui (henrycui@ca.ibm.com), Software Engineer, IBM

Henry Cui photoHenry Cui works with the Rational Application Developer service and support team at the IBM Toronto Lab. He's the subject matter expert of the support team in the Web services area where he's helped many customers resolve design, development, and migration issues with Web services. Henry coauthored the popular "Rational Application Developer V7 Programming Guide," one of the IBM Redbooks. You can reach Henry at henrycui@ca.ibm.com.



21 February 2008

Also available in Vietnamese Spanish

Before you start

About this series

If you went through Part 1 of this tutorial series, then you've already:

  • Set up the servers.
  • Created a Java bean.
  • Created Web services.
  • Created a Web services Java EE client.
  • Created a Web Services stand-alone Java client.

Part 2 of this tutorial built upon Part 1, showing you how to configure HTTP basic authentication. In Part 2 you:

  • Enabled IBM WebSphere> Application Server security.
  • Configured HTTP basic authentication for the Web services provider.
  • Configured HTTP basic authentication for the Web services client using deployment descriptor.
  • Configured HTTP basic authentication for the Web services client programmatically.
  • Monitored the HTTP basic authentication information using the TCP/IP monitor.

This tutorial, Part 3 of the series, shows you how to configure HTTPS. In it, you learn how to:

  • Create the keystore, trust store, and certificate for the Web services provider.
  • Create an SSL configuration for the Web services provider.
  • Create a new Web container transport chain to use the new SSL configuration for the Web services provider.
  • Configure HTTPS for the Web service client.
  • Test HTTPS Web services from the Java EE client.
  • Test HTTPS Web services from the stand-alone Java client.

Prerequisites

You should have a basic understanding of Java technology and Web services to follow along with this tutorial.

System requirements

You need to install IBM Rational® Application Developer V7 with the latest fixes. (You can download a trial copy of Rational Application Developer from developerWorks if you haven't purchased the license.) If you're not sure if your instance Rational Application Developer V7 is at the latest level, you can go to the IBM Installation Manager and select Update Packages to see if new updates are available. At the time of this writing, the latest version of Rational Application Developer was 7.0.0.5. (Note: IBM generally releases a fix pack approximately every three months. You may see a newer version of Rational Application Developer at the time of installation. Each new version of Rational Application Developer contains large quantities of fixes. We recommend that you install the latest version to avoid encountering problems that have already been fixed.)


SSL basics

The SSL protocol is based on public key cryptography and relies on the existence of digital certificates. A digital certificate contains both public and private keys, and it reveals the information about its owner, including identity. Messages encrypted with one of the keys can be decrypted only with the corresponding key in the key pair. You can extract the public key (called the signer certificate) to a file and import the certificate into the client's trust store. The client requires the signer part of a digital certificate for SSL communication.

IBM WebSphere Application Server supports the concept of two types of key store:

  • Key store file, which contains a collection of certificates and the associated private key for each certificate.
  • Trust store file, which contains a collection of certificates that are considered trustworthy and against which the presented certificate is matched during an SSL connection initiation to assure identity.

This tutorial uses HTTPS with a server-side certificate. In this configuration, the server must present its certificate to the client for the client to determine the server's identity. You'll use a self-signed certificate, because it can be used in a trusted environment in which the two parties don't need a third party to certify them. In real-world applications, you might need to get a real certificate that involves a certificate authority.


Create the keystore, trust store, and certificate for the Web services provider

In previous versions of WebSphere Application Server, managing certificates requires the use of an external utility called iKeyman. Starting in WebSphere Application Server V6.1, you can manage your keystores, trust stores, and certificates from the Administrative Console.

Create the keystore and trust store

  1. Start WAS v6.1 for Web services provider.
  2. In the Servers view, right-click WAS v6.1 for Web services provider, and select Run administrative console.
  3. Enter your user ID and password, then click Log in.
  4. In the left pane, expand Security, then select SSL certificate and key management.
  5. Under Related Items, select Key stores and certificates. This panel shows the default keystores that are created during profile creation, as shown in Figure 1. WebSphere Application Server creates the key.p12 default keystore file and the trust.p12 default trust store file during profile creation. A default, self-signed certificate is also created in the key.p12 file. The signer or public key is extracted from the key.p12 file and added to the trust.p12 file.
    Figure 1. Keystores and certificates
    Keystores and certificates

    The default keystore and trust store files aren't recommended for production use, as the password is well known: WebAS. Instead, you create a new set of keystore and trust store. Click New.

  6. Open Microsoft® Windows® explorer, and create the following directories under your C directory:
    • C:\ServerKeyStore
    • C:\ServerTrustStore
  7. Go back to the WebSphere Administrative Console and enter the following values: (see Figure 2):
    • Name: ServerKeyStore
    • Path: C:\ServerKeyStore\ServerKeyStore.jks
    • Password: sslwebsv
    • Type: JKS
    Figure 2. Create a new keystore
    Create a new keystore
  8. Click OK, then click Save.
  9. Click New to create a trust store, then enter the following values:
    • Name: ServerTrustStore
    • Path: C:\ServerTrustStore\ServerTrustStore.jks
    • Password: sslwebsv
    • Type: JKS
  10. Click OK, then click Save.

Create a personal certificate

  1. Select the ServerKeyStore you just created. Under Additional Properties, click Personal certificates.
  2. Click Create self-signed certificate, and enter the following values (see Figure 3):
    • Alias: WASServerCertificate
    • Common name: Server
    • Organization: IBM
    Figure 3. Create self-signed certificate
    Create self-signed certificate
  3. Click OK.

Create an SSL configuration for the Web services provider

The Java Secure Socket Extension (JSSE) repertoire is for Java-based SSL communications. An SSL configuration is used to encapsulate all the things that are needed by JSSE to build an SSL connection, such as the location of the key files, their type, and the available ciphers.

  1. In the left pane, expand Security, and select SSL certificate and key management.
  2. Under Related Items, select SSL configurations.
  3. Click New to create a new SSL configuration, and enter WebServiceConfigure as the name.
  4. Select ServerTrustStore from the Trust store name drop-down list and ServerKeyStore from the Keystore name drop-down list.
  5. Click Get certificate aliases. The default server and client certificate aliases are automatically populated, as shown in Figure 4.
    Figure 4. New SSL configuration
    New SSL configuration
  6. Click OK, then click Save.

Note: If you want to use the SSL mutual authentication, you need to click Quality of protection (QoP) settings, and set Client authentication as Required. In this case, the client's signer certificate must also be imported into the server's trust store. For this tutorial, you don't use the mutual authentication, so just leave it as default.


Create a new Web container transport chain to use the new SSL configuration for the Web services provider

In this section, you create a Web container transport chain to associate the new SSL configuration you created in the previous section. The new transport chain uses 9449 as the new SSL port, and you'll add port 9449 to the virtual host that hosts your Web application.

  1. In the left pane, select Servers > Application servers, then select server1.
  2. Under Container settings, expand Web Container Settings and click Web container transport chains.
  3. Click New. Enter WebServiceInboundSecure in the Transport chain name field. Make sure you select WebContainer-Secure(templates/chains | webcontainer-chains.xml#Chain_2) from the Transport chain template drop-down list, as shown in Figure 5.
    Figure 5. Select a transport chain template
    Select a transport chain template
  4. Click Next.
  5. In the Select a port page, enter the following values:
    • Port name: SecureWebServicePort
    • Host: *
    • Port: 9449

    Port 9449 is the secured port that you send the Web services request to. This port must not be used by any process.

  6. Click Next, then click Finish.
  7. Click Save. WebServiceInboundSecure is now listed as one of the Web container transport chains. Click WebServiceInboundSecure.
  8. This new transport chain needs to use the new SSL configuration you created previously. So click SSL inbound channel(SSL_4).
  9. Under SSL configuration, select WebServiceConfigure, as shown in Figure 6.
    Figure 6. Select SSL Configuration
    Select SSL Configuration
  10. Click OK, then click Save.
  11. Now you need to add 9449 to the virtual host. In the left pane, expand Environment > Virtual Hosts and click default_host. default_host is the virtual host that hosts your Web applications.
  12. Under Additional Properties, click Host Aliases.
  13. Click New. Enter 9449 as the port, and click OK. Port 9449 is now listed as one of ports of the default_host, as shown in Figure 7.
    Figure 7. Port list of default_host
    Port list of default_host
  14. Click Save.

To confirm that HTTPS is enabled on port 9449:

  1. Restart the WAS v6.1 for Web services provider.
  2. Make sure WAS v6.1 for Web services consumer is started.
  3. In the Project Explorer, expand CalculatorWebClient, WebContent, and sampleCalculatorProxy. Right-click TestClient.jsp, and select Run As > Run on server.
  4. In the sample JSP client page, click the getEndpoint() method, then click Invoke. Your result should be similar to this: http://localhost:9080/Calculator/services/Calculator. Make a copy of this URL.
  5. Click setEndpoint() in the sample JSP client, type https://localhost:9449/Calculator/services/Calculator, and click Invoke.
  6. Because port 9449 is HTTPS secured, you should receive exception at the SSL handshake stage if you try to invoke Web services operations. Click the add(int,int) method, and enter the values to test. You should see the following exception:

    exception: WSWS3713E: Connection to the remote host localhost failed.Received the following error: Handshake terminated SSL engine: CLOSED

Congratulations! You've successfully configured HTTPS for the Web services provider.


Configure HTTPS for the Web service client

In previous releases of WebSphere Application Server, to establish the trust between the client and the server, you must manually obtain the server's certificate and then import it into the client's trust store. WebSphere Application Server V6.1 makes your life easier by connecting to the specified remote SSL host and port and receiving the signer certificate during the handshake using the Retrieve from port option. The signer Secure Hash Algorithm (SHA) digest displays for validation and, if approved by an administrator, is added to the currently selected trust store.

To import the Web services provider's certificate into the client's trust store:

  1. In the Servers view, right-click WAS v6.1 for Web services consumer and select Run administrative console.
  2. In the left pane, expand Security and SSL certificate and key management.
  3. Under Related Items select Key stores and certificates. As discussed in the last section, this panel shows the default keystores that are created during profile creation. key.p12 is the default keystore file, and the trust.p12 is the default trust store file. You could create a new set of keystore and trust store files and a new SSL configuration as you did for the Web services provider. But for simplicity, here you just import the Web services provider's certificate directly into the client's default trust store.
  4. Click NodeDefaultTrustStore.
  5. Under Additional Properties, click Signer certificates. The list of the signer certificates is displayed, as shown in Figure 8.
    Figure 8. Signer certificates
    Signer certificates
  6. Click Retrieve from port, then enter the following values, as shown in Figure 9:
    • Host: localhost
    • Port: 9449
    • Alias: WebServicesProviderCert
    Figure 9. Retrieve certificate from port
    Retrieve certificate from port
  7. Click Retrieve signer information. The retrieved signer information is displayed, as shown in Figure 10.
    Figure 10. Retrieved signer information
    Retrieved signer information
  8. Click OK, then click Save.

Test HTTPS Web services from the Java EE client

Because you've enabled HTTPS at https://localhost:9449/, you can use the sample JSP client to send the SOAP request to this HTTPS secured endpoint.

  1. Restart WAS v6.1 for Web services consumer.
  2. In the Project Explorer, expand the project CalculatorWebClient, WebContent, and sampleCalculatorProxy. Right-click TestClient.jsp, and click Run As > Run on server.
  3. In the sample JSP client page, click the getEndpoint() method, and click Invoke. You should see a result similar to this: http://localhost:9080/Calculator/services/Calculator. Make a copy of this URL.
  4. Click setEndpoint() in the sample JSP client, and type the following URL: https://localhost:9449/Calculator/services/Calculator
  5. Click Invoke.
  6. Test the add, subtract, multiply, and divide methods. You should get the correct results this time.

After enabling HTTPS, all the communication is encrypted, and you shouldn't see the message in clear text any more. The TCP/IP monitor, acting as a third-party snooper, can't decrypt the request and response. To prove it, do the following:

  1. Select Window > Preferences > Run/Debug > TCP/IP Monitor, then click Add. The New Monitor dialog box opens.
  2. In the Local monitoring port field, specify a unique port number on your local machine that's not used by any process, for example, 9550.
  3. In the Host name field, type localhost.
  4. For the port, enter 9449, which is the port that the HTTPS-secured Web services is running on.
  5. For the type, select TCP/IP, as shown in Figure 11. Note: For the TCP/IP monitor to intercept the HTTPS-secured message, you must choose TCP/IP instead of HTTP.
    Figure 11. Set up TCP/IP monitor
    Set up TCP/IP monitor
  6. Click OK, then click Start.
  7. Click OK to exit the Preferences page.
  8. Click setEndpoint() in the sample JSP client, and type the following URL: https://localhost:9550/Calculator/services/Calculator.
  9. Click Invoke.
  10. Click the add(int,int) method, and enter the values to test. The request and response are displayed in the TCP/IP Monitor, as shown in Figure 12. You can see that both the HTTP header and the SOAP envelope are encrypted. The entire HTTP traffic appears as encrypted gunk.
    Figure 12. Request and response
    Request and response

Test HTTPS Web services from a stand-alone Java client

A stand-alone Java client runs outside the Java EE container. To send the SOAP request to the correct HTTPS port, you can invoke the setEndpoint() method of the generated proxy class. You also need to set the Java system properties to tell the run time what keystore and trust store to use.

  1. In the CalculatorJavaClient project, copy the code in Listing 1 and paste it into your TestCalculator.java.

    Note: You need to replace "xxxxxxxx" with your own user name and password for your basic authentication. You also need to use Windows explorer to find the default keystore and trust store files of the profile used by WAS v6.1 for Web services consumer and replace %RAD installation root%, %Your cell name%, and %Your node name% with the actual values in your own system settings. For example, I installed Rational Application Developer in the D:/RAD7 folder. My cell name is localhostNode02Cell, and my node name is localhostNode02. I need to set the javax.net.ssl.trustStore property as D:/RAD7/runtimes/base_v61/profiles/AppSrv02/config/cells/localhostNode02Cell/nodes/localhostNode02/trust.p12.

    Listing 1. TestCalculator.java

    Click to see code listing

    Listing 1. TestCalculator.java

    package com.ibm;
    
    import java.rmi.RemoteException;
    
    public class TestCalculator {
     public static void main(String[] args) {
      try {
      CalculatorProxy proxy = new CalculatorProxy();
      Calculator calculator = proxy.getCalculator();
      ((javax.xml.rpc.Stub)calculator)._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY,
       "xxxxxxxx");
      ((javax.xml.rpc.Stub)calculator)._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY,
       "xxxxxxxx");
        proxy.setEndpoint("https://localhost:9449/Calculator/services/Calculator");System.setProperty("javax.net.ssl.trustStore", "%RAD installation root%/runtimes/base_v61/profiles/AppSrv02/config/cells/%Your cell name%/nodes/%Your node name%/trust.p12");System.setProperty("javax.net.ssl.trustStorePassword", "WebAS");	System.setProperty("javax.net.ssl.keyStore", "%RAD installation root%/runtimes/base_v61/profiles/AppSrv02/config/cells/%Your cell name%/nodes/%Your node name%/key.p12");System.setProperty("javax.net.ssl.keyStorePassword", "WebAS");		System.setProperty("java.protocol.handler.pkgs", "com.ibm.net.ssl.internal.www.protocol");
        System.out.println("2 + 2 = " + proxy.add(2, 2));
        System.out.println("2 - 2 = " + proxy.subtract(2, 2));
        System.out.println("4 * 2 = " + proxy.multiply(4, 2));
        System.out.println("4 / 2 = " + proxy.divide(4, 2));
        System.out.print("4 / 0 = ");
        System.out.print(proxy.divide(4, 0));
    		} catch (DivideByZeroException e) {
          System.out.println("Error: can't divide by zero!");
    		} catch (RemoteException e) {
          e.printStackTrace();
    		}
    	}
    }
  2. Right-click TestCalculator.java, and select Run As > Java Application.
  3. Switch to the Console view, and you'll see that the correct result is displayed:
    Listing 2. Correct result displayed
    12-Nov-2007 10:31:10 PM com.ibm.ws.ssl.config.
      SSLConfigManagerINFO: ssl.disable.url.hostname.verification.CWPKI0027I
    2 + 2 = 4
    2 - 2 = 0
    4 * 2 = 8
    4 / 2 = 2
    4 / 0 = Error: can't divide by zero!

Congratulations, you've completed this tutorial. Great job!


Conclusion

In this three-part tutorial series you learned how to build Web services and clients, and configure HTTP basic authentication and HTTPS using Rational Application Developer V7 and WebSphere Application Server V6.1. Now you can apply these techniques to your real-world applications!


Download

DescriptionNameSize
Solution in project interchange format1Part3Solution.zip59KB

Note

  1. To import the solution, select File > Import > Other > Project Interchange.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services, Rational, WebSphere, XML, DevOps
ArticleID=290863
ArticleTitle=Build Web services with transport-level security using Rational Application Developer V7, Part 3: Configure HTTPS
publish-date=02212008