Build Web services with transport-level security using Rational … › developerworks › education › ... · 2010-01-15 · • Created a Web Services stand-alone Java client

Build Web services with transport-level securityusing Rational Application Developer V7, Part 3:Configure HTTPSSkill Level: Intermediate

Henry Cui ([email protected])Software EngineerIBM

21 Feb 2008

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

Section 1. 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.

Configure HTTPS© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 22

mailto:[email protected]

http://www.ibm.com/developerworks/webservices/edu/ws-dw-ws-radsecurity1.html


http://www.ibm.com/developerworks/views/webservices/libraryview.jsp?search_by=Build+Web+services+with+transport-level+security+using+Rational+Application+Developer+V7



http://www.ibm.com/legal/copytrade.shtml

• Created a Web Services stand-alone Java client.

Part 2 of this tutorial built upon Part 1, showing you how to configure HTTP basicauthentication. 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 usingdeployment descriptor.

• Configured HTTP basic authentication for the Web services clientprogrammatically.

• Monitored the HTTP basic authentication information using the TCP/IPmonitor.

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

• Create the keystore, trust store, and certificate for the Web servicesprovider.

• Create an SSL configuration for the Web services provider.

• Create a new Web container transport chain to use the new SSLconfiguration 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 tofollow 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 fromdeveloperWorks if you haven't purchased the license.) If you're not sure if yourinstance Rational Application Developer V7 is at the latest level, you can go to theIBM Installation Manager and select Update Packages to see if new updates are

developerWorks® ibm.com/developerWorks

Configure HTTPSPage 2 of 22 © Copyright IBM Corporation 1994, 2008. All rights reserved.


http://www.ibm.com/developerworks/downloads/r/rad/


available. At the time of this writing, the latest version of Rational ApplicationDeveloper was 7.0.0.5. (Note: IBM generally releases a fix pack approximatelyevery three months. You may see a newer version of Rational Application Developerat the time of installation. Each new version of Rational Application Developercontains large quantities of fixes. We recommend that you install the latest version toavoid encountering problems that have already been fixed.)

Section 2. SSL basics

The SSL protocol is based on public key cryptography and relies on the existence ofdigital certificates. A digital certificate contains both public and private keys, and itreveals the information about its owner, including identity. Messages encrypted withone 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 thecertificate into the client's trust store. The client requires the signer part of a digitalcertificate 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 theassociated private key for each certificate.

• Trust store file, which contains a collection of certificates that areconsidered trustworthy and against which the presented certificate ismatched during an SSL connection initiation to assure identity.

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

Section 3. Create the keystore, trust store, andcertificate for the Web services provider

ibm.com/developerWorks developerWorks®



In previous versions of WebSphere Application Server, managing certificatesrequires the use of an external utility called iKeyman. Starting in WebSphereApplication Server V6.1, you can manage your keystores, trust stores, andcertificates 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 keymanagement.

5. Under Related Items, select Key stores and certificates. This panelshows the default keystores that are created during profile creation, asshown in Figure 1. WebSphere Application Server creates the key.p12default keystore file and the trust.p12 default trust store file during profilecreation. A default, self-signed certificate is also created in the key.p12file. The signer or public key is extracted from the key.p12 file and addedto the trust.p12 file.Figure 1. Keystores and certificates

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

6. Open Microsoft® Windows® explorer, and create the following directories



http://www.ibm.com/developerworks/downloads/ws/was/learn.html



under your C directory:

• C:\ServerKeyStore

• C:\ServerTrustStore

7. Go back to the WebSphere Administrative Console and enter thefollowing values: (see Figure 2):

• Name: ServerKeyStore

• Path: C:\ServerKeyStore\ServerKeyStore.jks

• Password: sslwebsv

• Type: JKSFigure 2. 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


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 (seeFigure 3):

• Alias: WASServerCertificate

• Common name: Server

• Organization: IBMFigure 3. Create self-signed certificate




3. Click OK.

Section 4. Create an SSL configuration for the Webservices provider

The Java Secure Socket Extension (JSSE) repertoire is for Java-based SSLcommunications. An SSL configuration is used to encapsulate all the things that areneeded 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 keymanagement.




2. Under Related Items, select SSL configurations.

3. Click New to create a new SSL configuration, and enterWebServiceConfigure as the name.

4. Select ServerTrustStore from the Trust store name drop-down list andServerKeyStore from the Keystore name drop-down list.

5. Click Get certificate aliases. The default server and client certificatealiases are automatically populated, as shown in Figure 4.Figure 4. New SSL configuration


Note: If you want to use the SSL mutual authentication, you need to click Quality ofprotection (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. Forthis tutorial, you don't use the mutual authentication, so just leave it as default.




Section 5. Create a new Web container transport chainto use the new SSL configuration for the Web servicesprovider

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

1. In the left pane, select Servers > Application servers, then selectserver1.

2. Under Container settings, expand Web Container Settings and clickWeb container transport chains.

3. Click New. Enter WebServiceInboundSecure in the Transport chainname field. Make sure you selectWebContainer-Secure(templates/chains |webcontainer-chains.xml#Chain_2) from the Transport chain templatedrop-down list, as shown in Figure 5.Figure 5. Select a transport chain template

4. Click Next.

5. In the Select a port page, enter the following values:

• Port name: SecureWebServicePort

• Host: *

• Port: 9449Port 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 Webcontainer transport chains. Click WebServiceInboundSecure.

8. This new transport chain needs to use the new SSL configuration youcreated previously. So click SSL inbound channel(SSL_4).

9. Under SSL configuration, select WebServiceConfigure, as shown inFigure 6.Figure 6. Select SSL Configuration


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 thevirtual 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 listedas one of ports of the default_host, as shown in Figure 7.Figure 7. 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, andsampleCalculatorProxy. Right-click TestClient.jsp, and select Run As> Run on server.




4. In the sample JSP client page, click the getEndpoint() method, then clickInvoke. Your result should be similar to this:http://localhost:9080/Calculator/services/Calculator. Make a copy of thisURL.

5. Click setEndpoint() in the sample JSP client, typehttps://localhost:9449/Calculator/services/Calculator,and click Invoke.

6. Because port 9449 is HTTPS secured, you should receive exception atthe SSL handshake stage if you try to invoke Web services operations.Click the add(int,int) method, and enter the values to test. You shouldsee the following exception:exception: WSWS3713E: Connection to the remote hostlocalhost failed.Received the following error:Handshake terminated SSL engine: CLOSED

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

Section 6. Configure HTTPS for the Web service client

In previous releases of WebSphere Application Server, to establish the trustbetween the client and the server, you must manually obtain the server's certificateand then import it into the client's trust store. WebSphere Application Server V6.1makes your life easier by connecting to the specified remote SSL host and port andreceiving the signer certificate during the handshake using the Retrieve from portoption. The signer Secure Hash Algorithm (SHA) digest displays for validation and, ifapproved 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 consumerand select Run administrative console.

2. In the left pane, expand Security and SSL certificate and keymanagement.

3. Under Related Items select Key stores and certificates. As discussed inthe last section, this panel shows the default keystores that are created




during profile creation. key.p12 is the default keystore file, and thetrust.p12 is the default trust store file. You could create a new set ofkeystore and trust store files and a new SSL configuration as you did forthe Web services provider. But for simplicity, here you just import the Webservices provider's certificate directly into the client's default trust store.

4. Click NodeDefaultTrustStore.

5. Under Additional Properties, click Signer certificates. The list of thesigner certificates is displayed, as shown in Figure 8.Figure 8. Signer certificates

6. Click Retrieve from port, then enter the following values, as shown inFigure 9:

• Host: localhost

• Port: 9449

• Alias: WebServicesProviderCertFigure 9. Retrieve certificate from port




7. Click Retrieve signer information. The retrieved signer information isdisplayed, as shown in Figure 10.Figure 10. Retrieved signer information





Section 7. Test HTTPS Web services from the Java EEclient

Because you've enabled HTTPS at https://localhost:9449/, you can use the sampleJSP 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 clickInvoke. You should see a result similar to this:http://localhost:9080/Calculator/services/Calculator. Make a copy of thisURL.

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 getthe correct results this time.

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

1. Select Window > Preferences > Run/Debug > TCP/IP Monitor, thenclick Add. The New Monitor dialog box opens.

2. In the Local monitoring port field, specify a unique port number on yourlocal 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 Webservices is running on.

5. For the type, select TCP/IP, as shown in Figure 11. Note: For the TCP/IPmonitor to intercept the HTTPS-secured message, you must chooseTCP/IP instead of HTTP.Figure 11. 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 requestand 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 areencrypted. The entire HTTP traffic appears as encrypted gunk.Figure 12. Request and response

Section 8. Test HTTPS Web services from a stand-aloneJava client

A stand-alone Java client runs outside the Java EE container. To send the SOAPrequest to the correct HTTPS port, you can invoke the setEndpoint() method ofthe generated proxy class. You also need to set the Java system properties to tellthe 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 andpassword for your basic authentication. You also need to use Windowsexplorer to find the default keystore and trust store files of the profile usedby WAS v6.1 for Web services consumer and replace %RADinstallation root%, %Your cell name%, and %Your nodename% with the actual values in your own system settings. For example, Iinstalled Rational Application Developer in the D:/RAD7 folder. My cellname is localhostNode02Cell, and my node name is localhostNode02. Ineed to set the javax.net.ssl.trustStore property asD:/RAD7/runtimes/base_v61/profiles/AppSrv02/config/cells/localhostNode02Cell/nodes/localhostNode02/trust.p12.

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 isdisplayed:Listing 2. Correct result displayed

12-Nov-2007 10:31:10 PM com.ibm.ws.ssl.config.SSLConfigManagerINFO:

ssl.disable.url.hostname.verification.CWPKI0027I2 + 2 = 42 - 2 = 04 * 2 = 84 / 2 = 24 / 0 = Error: can't divide by zero!

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

Section 9. 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 ApplicationDeveloper V7 and WebSphere Application Server V6.1. Now you can apply thesetechniques to your real-world applications!





Downloads

Description Name Size Download method

Solution in project interchange format1 Part3Solution.zip 59KB HTTP

Information about download methods

Note

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



http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/tutorials/ws-radsecurity3/Part3Solution.zip

http://www.ibm.com/developerworks/library/whichmethod.html


Resources

Learn

• IBM Redbooks®:

• "IBM WebSphere Version 6.1 Web Services Handbook" is a goodresource to learn IBM Web services technologies.

• To get familiar with Rational Application Developer, try the samples in the"Rational Application Developer V7 Programming Guide."

• To get familiar with IBM WebSphere security, read the "WebSphereApplication Server V6.1 Security Handbook."

• The SOA and Web services zone on IBM developerWorks hosts hundreds ofinformative articles and introductory, intermediate, and advanced tutorials onhow to develop Web services applications.

• Play in the IBM SOA Sandbox! Increase your SOA skills through practical,hands-on experience with the IBM SOA entry points.

• The IBM SOA Web site offers an overview of SOA and how IBM can help youget there.

• Stay current with developerWorks technical events and webcasts.

• Browse for books on these and other technical topics at the Safari bookstore.

• Check out a quick Web services on demand demo.

• Get an RSS feed for this series. (Find out more about RSS.)

Get products and technologies

• Download an evaluation version of Rational Application Developer.

• Download an evaluation version of WebSphere Application Server.

• Innovate your next development project with IBM trial software, available fordownload or on DVD.

Discuss

• Get involved in the developerWorks community by participating indeveloperWorks blogs, including the following SOA and Web services-relatedblogs:

• Service Oriented Architecture -- Off the Record with Sandy Carter

• Best Practices in Service-Oriented Architecture with Ali Arsanjani

• WebSphere SOA and J2EE in Practice with Bobby Woolf



http://www.redbooks.ibm.com/abstracts/sg247257.html

http://www.redbooks.ibm.com/redpieces/abstracts/sg247501.html



http://www.ibm.com/developerworks/webservices

http://www.ibm.com/developerworks/downloads/soasandbox/

http://www.ibm.com/software/solutions/soa/

http://www.ibm.com/developerworks/offers/techbriefings

http://safari.bvdep.com/?x=1&portal=bvdep&uicode=&Key=&GUID=D1F1DB57-50AF-4998-99-DA-6D-BB-A5-E0-E4-0B

http://www.ibm.com/developerworks/offers/lp/demos/

fill in here with custom URL

http://www.ibm.com/developerworks/views/rss/customrssatom.jsp?zone_by=Web+services&type_by=Tutorials&search_by=Build+Web+services+with+transport-level+security+using+Rational&day=1&month=01&year=2004&max_entries=10&feed_by=rss&isGUI=true&Submit.x=15&Submit.y=11

http://www.ibm.com/developerworks/downloads/r/rad/


http://www.ibm.com/developerworks/downloads/

http://www.ibm.com/developerworks/blogs/

http://www-03.ibm.com/developerworks/blogs/page/SOA_Off_the_Record

http://www-03.ibm.com/developerworks/blogs/page/AliArsanjani

http://www-03.ibm.com/developerworks/blogs/page/woolf


• Building SOA applications with patterns with Dr. Eoin Lane

• Client Insights, Concerns and Perspectives on SOA with Kerrie Holley

• Service-Oriented Architecture and Business-Level Tooling with SimonJohnston

• SOA, ESB and Beyond with Sanjay Bose

About the author

Henry CuiHenry Cui works with the Rational Application Developer service and support team atthe IBM Toronto Lab. He's the subject matter expert of the support team in the Webservices area where he's helped many customers resolve design, development, andmigration issues with Web services. Henry coauthored the popular "RationalApplication Developer V7 Programming Guide," one of the IBM Redbooks. You canreach Henry at [email protected].

Trademarks

IBM, the IBM logo, Rational, Redbooks, and WebSphere are registered trademarksof IBM in the United States, other countries or both.Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.Microsoft and Windows are trademarks of Microsoft Corporation in the United States,other countries, or both.



http://www-03.ibm.com/developerworks/blogs/page/SOAPatterns

http://www-03.ibm.com/developerworks/blogs/page/ClientSOA

http://www-03.ibm.com/developerworks/blogs/page/johnston

http://www-03.ibm.com/developerworks/blogs/page/sbose




Documents

Build Web services with transport-level security using Rational … › developerworks › education › ... · 2010-01-15 · • Created a Web Services stand-alone Java client