WS-SecureConversation interoperability between WebSphere V8 and Windows Communication

Foundation using dynamic policy configuration, Part 3:

Configure and test the Windows Communication Foundation Web Services client

Thomas LinkAdvisory Software EngineerWeb Services Interoperability DevelopmentIBM, Research Triangle Park, NC

Hyen-Vui (Henry) ChungSoftware Development EngineerAmazon, Austin, TX

Charles Le VaySenior Software EngineerWebSphere Technical Evangelist – Emerging Technology IBM, Research Triangle Park, NC

Salim ZeitouniAdvisory Software EngineerWebSphere Commerce Development Software Developer IBM, Research Triangle Park, NC

October, 2011

© Copyright International Business Machines Corporation 2011. All rights reserved.

This series of articles describes how to use the IBM WebSphere Application Server Version 8 Endpoint Interface samples to demonstrate interoperability with Microsoft Windows Communication Foundation. It provides step-by-step configurations to show you what you need to do for SOAP message security interoperability using WS-SecureConversation.

The article is intended for web services developers and architects who plan to develop web services across these platforms. You should have a basic understanding of Java™ programming, web services development, WSDL and SOAP.

Table of ContentsIntroduction................................................................................................................................................2Getting started............................................................................................................................................3Import certificates into Windows certificate store.....................................................................................3Prepare WAS for interoperability with WCF.............................................................................................4

Manually enable OnlySignEntireHeadersAndBody..............................................................................4Change derived key size on provider outbound keys.............................................................................5

Configure WCF client communication with the WebSphere Application Server service using dynamic policy..........................................................................................................................................................6

Query the WebSphere Application Server WSDL and prepare it for the WCF consumer.....................7Generate WCF client artifacts using svcutil...........................................................................................7Create a WCF project and import the generated artifacts......................................................................8Update WCF client to include client credentials..................................................................................11

Compile the project..................................................................................................................................20Test the WCF client..................................................................................................................................21Summary..................................................................................................................................................22Resources.................................................................................................................................................22

Specifications...................................................................................................................................22WebSphere Application Server Information Center........................................................................22Feature Pack for Web Services & developerWorks.........................................................................22Windows Communication Foundation.............................................................................................23

About the authors.....................................................................................................................................23

Introduction

WebSphere Application Server Version 8 includes a set of Java API for XML-based Web Services (JAX-WS) samples that demonstrate simple message exchange patterns (MEPs) using both a synchronous and asynchronous programming model. The samples support SOAP 1.1 and SOAP 1.2. Using these MEP samples composed with Web services standards such as WS-Addressing (WS-A), WS-Security, WS-Reliable Messaging (WS-RM), and WS-SecureConversation (WS-SC), you can perform a broad range of interoperability tests. These samples demonstrate the use of JavaBean artifacts, static service endpoints and proxy-based clients.

The purpose of this series of articles is to highlight protocol-level interoperability between WebSphere 8 and Windows Communication Foundation 4.0 (WCF) using dynamic policy to configure WS-SecureConversation. Dynamic policy configuration was first added in WebSphere 7.

In this series of articles you'll learn how to:

1. Statically configure a custom WebSphere WS-SC policy set and binding. 2. Dynamically configure a WebSphere Application Server web services client using the WS-

Security Policy assertions emitted from WebSphere and test it with the WebSphere Application Server service provider.

3. Dynamically configure a Windows Communication Foundation client using the WS-Security Policy assertions emitted from WebSphere and test it with a the WebSphere Application Server

service provider.

Part 3 of this series focuses on dynamically configuring a Windows Communication Foundation client using the WS-Security Policy assertions emitted from WebSphere Application Server and testing it with a WebSphere Application Server V8 service provider.

Getting startedYou must successfully complete and test the WS-SecureConversation policy set and bindings described in Part 1 and Part 2 before beginning the steps in this article.

1. Install Microsoft Visual Studio. You can download a 90-day t rial here . 2. Install Microsoft .NET 4.0 or newer. You can download . NET 4.0 here for free.3. Install the latest Microsoft Windows SDK. You can download Ve rsion 7.1 here for free.4. Download and uncompress the Client_and_keys.zip, provided with this article, if you have not

already done so. The Client_and_keys folder contains the following folders: WCFClient, and mySysKeys.

WCFClient contains: • WSWindowsClient.cs. – The C# code for the client.

mySysKeys.zip contains:• sender.jks – keystore containing client credentials • receiver.jks – keystore containing service credentials• alice-key – Alice’s public key• alice-cert – Alice’s certificate• bob-key – Bob’s public key• bob-cert – Bob’s certificate• myca – certificate authority

Import certificates into Windows certificate store

To import the Bob and Alice X.509 certificates into the certificate store using the Microsoft Management Console (MMC), do the following:

1. On Windows XP, from the Start menu, select Start => Run, enter mmc, and click OK or, on Windows Vista or Windows 7, from the Start menu, type mmc into Search programs and files, and click the search icon.

2. Select File => New.3. Select File => Add/Remove Snap-in.4. On Windows XP, οn the StandAlone tab, click Add.5. Select Certificates, then click Add.6. Select My user account, then click Finish. 7. On Windows XP, click Close.8. Click OK.9. Expand Certificates (Current User) => Personal => Certificates, then right-click

Certificates => All Tasks => Import.10. Browse to and install alice-key.p12 from the unzipped mySysKeys.zip file.11. When prompted for the password, enter sampleapp.12. Expand Certificates => Trusted People => Certificates, then right-click Certificates => All

Tasks =>Import.13. Browse to and install bob-cert.der from the unzipped mySysKeys.zip file.14. Expand Trusted Root Certification Authorites => Certificates, then right-click Certificates

=> All Tasks =>Import.15. Browse to and install myca from the unzipped mySysKeys.zip file.16. Select File => Add/Remove Snapins.17. On Windows XP, οn the StandAlone tab, click Add.18. Select Certificates, then click Add.19. Select Computer account and click Next.20. Select Local computer, then click Finish.21. On Windows XP, click Close.22. Click OK.23. Expand Certificates (Local Computer) => Personal => Certificates, then right-click

Certificates => All Tasks => Import.24. Browse to and install bob-key.p12 from the unzipped mySysKeys.zip file.25. When prompted for the password, enter sampleapp.26. Expand Certificates => Trusted People => Certificates, then right-click Certificates => All

Tasks =>Import.27. Browse to and install alice-cert.der from the unzipped mySysKeys.zip file.28. Expand Trusted Root Certification Authorites => Certificates, then right-click Certificates

=> All Tasks =>Import.29. Browse to and install myca from the unzipped mySysKeys.zip file.

Prepare WAS for interoperability with WCFFor signing SOAP messages, WCF supports only the optional policy assertion <sp:OnlySignEntireHeadersAndBody>. By default, WebSphere is not configured to emit this assertion. Therefore, the first step is to enable the <sp:OnlySignEntireHeadersAndBody> assertion.

Manually enable OnlySignEntireHeadersAndBody

The Integrated Console in WebSphere Application Server V8 does not support enabling the <sp:OnlySignEntireHeadersAndBody> assertion. You need to do this with wsadmin commands, as shown below.

cd “C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\bin”.\wsadmin.bat

wsadmin>$AdminTask setBinding {-policyType WSSecurity -bindingLocation -attributes {{application.onlySignEntireHeadersAndBody true}} -bindingName "MyProviderGeneralBindings"}

wsadmin>$AdminTask setBinding {-policyType WSSecurity -bindingLocation -attributes {{application.onlySignEntireHeadersAndBody true}} -attachmentType

client -bindingName "MyConsumerGeneralBindings"}

wsadmin>$AdminConfig save

wsadmin>exit

The final command saves the changes.

Change derived key size on provider outbound keys

WebSphere and WCF 4.0 use a different key size for the signing key. WebSphere uses a key size of 20 bytes, and WCF allows a maximum key length of 16 bytes. To be interoperable with the WCF custom SC template, the configuration of your client and service key sizes needs to match. In this section, you’ll set up the custom bindings of the WebSphere SecureConversation policy set to have a signing key size of 16 bytes:

For the WebSphere service custom binding, from the WebSphere Integrated Solution Console, set the symmetric signature generator record to sign with a key-size of 16 bytes as follows

1. In the left pane, select Services => Service providers.2. Select EchoService => MyProviderGeneralBindings => WS-Security.3. Select Keys and certificates.4. Select gen_signsctkeyinfo.5. Under the Requires derived keys section, specify 16 for the key length.6. Click OK, then Save.7. Go back under Keys and certificates, and this time select gen_encsctkeyinfo.8. Under the Requires derived keys section, specify 16 for the key length, as shown in Figure 1.9. Click OK, then Save.

Figure 1. Set key length to 16

10. Stop and restart the Application Server.

The IBM WebSphere web services client is able to consume the change you made to the key length on the WebSphere service provider, therefore no updates are needed to the WebSphere client. Note that you would need to update the client side to have a key size of 16 bytes if you were planning to communicate with a WCF service.

Configure WCF client communication with the WebSphere Application Server service using dynamic policy

In this section, you will:1. Request the WebSphere Application Server service provider WSDL.2. Edit the WSDL for WCF consumption.

3. Generate a WCF client from the edited WSDL.4. Complete the configuration of the WCF client.5. Test the WCF client with the WebSphere Application Server service provider.

Query the WebSphere Application Server WSDL and prepare it for the WCF consumer

You will start by getting a copy of the WebSphere service WSDL so that you can generate the WCF artifacts for the WCF client. In c you already enabled the publishing of WS-SecurityPolicy assertions.

1. Using your web browser, retrieve the WSDL from the following URL: http://localhost:9080/WSSampleSei/EchoService?wsdl. Note that the WSDL now has embedded WS-SecurityPolicy assertions you enabled in Part 2.

2. Select File => Save Page As or File => Save As.3. Save the WSDL as WAS-Service-SC.wsdl to the desktop.

You will modify this WSDL and use it to generate the WCF client artifacts.

In our investigation, we found that the WCF svcutil.exe, used to generate the WCF client artifacts, does not support the ExternalUriReference in the WebSphere Application Server-generated WSDL. If you disable the ExternalUriReference on the WebSphere Application Server service side, svcutil.exe is able to consume this new WSDL without this feature, but the WCF runtime fails indicating the ExternalUriReferencee is required. To get around this issue, you need to edit the WebSphere Application Server-generated WSDL to remove ExternalUriReference assertions before you use svcutil.exe.

4. Using a text editor, such as Notepad, remove the following assertions from the WAS-Service-SC.wsdl

<sp:MustSupportRefExternalURI/><sp:RequireExternalUriReference/>

5. Save the updated WSDL.

Generate WCF client artifacts using svcutilUsing the modified WSDL, you can now run svcutil to generate the WCF client artifacts. Note that the Windows SDK contains two copies of this utility. An older one is located in the SDK \bin directory. The updated version you need is located in \bin\NETFX 4.0 Tools\.

1. Open a command window.2. Chage to the directory where you saved the WSDL. For example,

cd c:\Documents and Settings\Administrator\Desktop3. Run the following command:

<full path>svcutil /config:App.config WAS-Service-SC.wsdlwhere <full path> is the full path to the svcutil.exe file in the Windows SDK. For example: c:\Program Files\Microsoft SDKs\Windows\V8.1\bin\NETFX 4.0 Tools\svcutil.exe

4. The svcutil generates two files: EchoService.cs and App.config. The EchoService.cs file contains the contract to be used by the client to communicate with the service. The App.config

file contains the policy and binding information used by the WCF client. These files are generated in the current directory.

Create a WCF project and import the generated artifactsIn this section, you will create a WCF project and import the generated client artifacts.

1. Start Microsoft Visual Studio.2. In Visual Studio, create a project by clicking File => New => Project.3. In the New Project window, select WCF => WCF Service Library as shown in Figure 2.4. Name the project WCF-ClientForWAS-Service.5. For location, specify WCFClient.6. Click OK.

Now you need to update the project to build command line executables.

1. Right-click WCF-ClientForWAS-Service from the Solution Explorer, and select Properties.2. The Properties window is displayed, as shown in Figure 3. On the Application tab, change

Output type to Console Application.3. Click File => Save Selected Items.4. Click the Build tab and notice that the build output will be saved to bin\Debug\. This is where

the client executable and config will be found once you build the WCF client.5. Close the Properties window.

Figure 2. Create a new WCF project

A new WCF Visual Studio project would look like Figure 4. Because you will be importing the already generated configuration file and client service contract file, you can remove the App.config, Service1.cs, and IService1.cs by selecting all three of these files and deleting them.

Figure 4. The new project is created

Figure 3. Change project type to console application

Next you'll import the two generated files and the WSWindowsClient class file:

1. From the Solution Explorer, right-click WCF-ClientForWAS-Service and select Add => Existing item.

2. Navigate to the to the directory where you saved the WSDL (for example, c:\Documents and Settings\Administrator\Desktop), and add the following files: App.config and EchoService.cs.

3. Select Add => Existing item, and add the WSWindowsClient.cs for the EchoService Client. (Specify *.* for Objects of type: to see all files in the selection dialog.)

WSWindowsClient.cs contains the implementation class that will invoke the service via the client contract, as shown in Listing 1.

Listing 1. WCF client implementation code

using System;public partial class WSWindowsClient{

static void Main(string[] args) {

string msg = "HELLO WAS, This is WCF Client Request";

EchoServicePortTypeClient echosv; echosv = new EchoServicePortTypeClient("EchoServicePort"); echoStringInput echoParm = new echoStringInput(); echoParm.echoInput = msg; Console.WriteLine("CLIENT>> Sending message '" + msg + "' ..."); echoStringResponse result = echosv.echoOperation(echoParm); Console.WriteLine("CLIENT>> The answer is '" + result.echoResponse + "'");

}}

Update WCF client to include client credentialsAt this point, the WCF client is correctly configured to consume the WebSphere service using the policy assertions from the WSDL. However, you still need to configure the App.config file with the required client credentials in order to establish the bootstrap channel between the client and the service using the service configuration editor.

1. Right-click App.config and select Edit WCF Configuration to open the Microsoft service configuration editor.

2. To create an endpoint behavior that will list the client credential, select Advanced => Endpoint Behaviors in the left pane, then select New Endpoint Behavior Configuration in the right pane, as shown in Figure 5.

3. Specify Client-Cert-Behavior in the Name field, and click Add as shown in Figure 6.

Figure 5. Select endpoint behavior

4. In the Adding Behavior Element Extension Sections dialog, select clientCredentials and click Add, as showIn the Adding Behavior Element Extension Sections dialog, select clientCredentials and click Add, as shown in Figure 7.

Figure 6. Create Client-Cert-Behavior

5. The results are displayed, as shown in Figure 8. Select Client-Cert-Behavior => clientCredentials => clientCertificate.

Figure 7. Select clientCredentials

6. In the right pane, specify the following values, as shown in Figure 9:

Figure 8. clientCredentials has been added

• FindValue: 12• X509FindType: FindBySerialNumber

Figure 9. Set up clientCertificate

Figure 10. Set serviceCertificate defaultCertificate

7. In the left pane, select serviceCertificate => defaultCertificate.

Figure 11. Modify BehaviorConfiguration

13. Switch to the Identity tab, and set the DNS to Bob, as shown in Figure 12.

Figure 12. Set Dns to Bob

14. By default, the WCF client expects the SOAP response to have a signing key that is referenced using a Key Identifier Reference (KeyID) while the WebSphere Application Server service defaults to Security Token Reference (STRREF). This causes the WCF runtime to fail with “Cannot find a token authenticator.” To enable WCF to consume the WebSphere Application Server service response, you need to update the allowSerializedSigningTokenOnReply to true by selecting Bindings => ECHOSOAP(customBinding) => security => secureConversationBootstrap in the left pane. In the right pane, set AllowSerializedSigningTokenOnReply to True, as shown in Figure 13.

Alternatively, you could update WebSphere Application Server to send a KeyID instead of STRREF.

14. Select File => Save to save the changes to the App.config file.

Figure 13. Set AllowSerializedSigningTokenOnReply to True

Compile the projectTo complete the project, from the Visual Studio main menu, select Build => Rebuild solution. The project will put the results in output\debug under the current workspace for the project. For example: C:\WCFClient\WCF-ClientForWAS-Service\WCF-ClientForWAS-Service\bin\Debug.

Test the WCF clientIn this section, you’ll test that the WCF client can communicate with the WebSphere Application Server service provider.

To run the WCF client, do the following:

1. Select Start => Run => cmd to open a command window. 2. Change to the C:\WCFClient\WCF-ClientForWAS-Service\WCF-ClientForWAS-

Service\bin\Debug directory.3. The compile creates two files: WCF-ClientForWAS-Service.exe and WCF-ClientForWAS-

Figure 14. Visual Studio build solution

Service.exe.config.4. Run WCF-ClientForWAS-Service.exe.

The WCF client should initiate a request and succeed in communicating with the WebSphere Application Server service. The WebSphere service prepends JAX-WS==>> to the client request string and responds to the client as shown above.

\bin\Debug>WCF-ClientForWAS-Service.exeCLIENT>> Sending message 'HELLO WAS, This is WCF Client Request'...CLIENT>> The answer is 'JAX-WS==>>HELLO WAS, This is WCF Client Request

SummaryIn this article, you implemented a scenario that leverages WS-SecureConversation to secure SOAP messages exchanged between a Windows Communication Foundation client and a WebSphere Application Server V8 web service. You learned how to dynamically configure a WCF web services client using these policy assertions.

Resources

SpecificationsWeb Services Security: SOAP Message Security 1.0 WS-Security (2004)Web Services Security: SOAP Message Security 1.1Web Services Secure Conversation

WebSphere Application Server Information CenterWebSphere Application Server V8 Information Center: Introduction to web services

Feature Pack for Web Services & developerWorks WS-Secure Conversation interoperability between WebSphere Application Server V8 and Windows Communication Foundation using dynamic policy configuration, Part 1: Configure and test WS-Secure Conversation (developerWorks 2009): Part 1 of this series focuses on statically configuring a custom WebSphere WS-SC policy set and binding.

Achieving Web services interoperability between the WebSphere Web Services Feature Pack and Windows Communication Foundation, Part 1: (developerWorks 2007) Part 1 of this series describes how to use the WebSphere Application Server Version 6.1 Feature Pack for Web Services Service Endpoint Interface samples to demonstrate interoperability with Microsoft Windows Communication Foundation. It provides step-by-step instructions on how to achieve basic Web services interoperability for SOAP 1.1, SOAP 1.2, and WS-Addressing.

Achieving Web services interoperability between the WebSphere Web Services Feature Pack and Windows Communication Foundation, Part 2: Configure and test WS-Security(developerWorks 2007) Part 2 of this series focuses on how to configure a custom WebSphere WS-Security policy set and binding, how to configure WS-Security in a WCF customBinding, and how to

testWS-Security interoperability between WebSphere and WCF.

Achieving Web services interoperability between the WebSphere Web Services Feature Pack and Windows Communication Foundation, Part 3: Configure and test WS-Secure conversation (developerWorks 2008) Part 3 of this series focuses on how to configure a custom WebSphere WS-SecureConversation policy set and binding, how to configure WS-SecureConversation in a WCF customBinding, and how to test WS-SecureConversation interoperability between WebSphere and WCF.

Windows Communication FoundationWeb Services Protocols Interoperability Guide: This topic provides a list of Web Services Protocols implemented by WCF.

Web Services Protocols Supported by System-Provided Interoperability Bindings: This topic lists specifications that are supported by system-provided interoperable bindings.

About the authors

Tom Link works as an advisory software engineer on the IBM WebSphere web services interoperability team. Tom is an active member of the OASIS community, an open industry organization chartered to promote Web interoperability. Prior to joining the web services group, Tom developed the PalmOS user interface for the WebSphere Everyplace product. Since joining IBM in 1977, Tom has worked on many IBM, WebSphere and Lotus software products.

Henry Chung is currently a software development engineer at Amazon. Prior to that, Henry was the architect on the WebSphere Web Services development team, the architect and lead developer of Web services security on the WebSphere platform. Henry has been in middleware development for over 10 years and has developed many security features for the WebSphere platform.

Charles Le Vay is a senior software architect and technical evangelist on the WebSphere Emerging Technologies team. His current focus is on promoting the advantages of elastic data grid technology within the enterprise. Before becoming a technical evangelist, Charles was the Web Service interoperability architect for IBM's WebSphere Application Server. He represented IBM on the Web Service Interoperability Organization (WS-I) Reliable Secure Profile (RSP) Working Group. As an interoperability architect, Charles focused on ensuring IBM products meet industry standard interoperability criteria. He was responsible for identifying and detailing best practices for Web services interoperability. Prior to this position, Charles specialized in mobile application development, wireless technology, and extending enterprise applications securely to mobile devices. Before joining IBM, Charles developed advanced submarine sonar systems for the Navy and specialized in signal processing and underwater acoustics. Charles is a graduate of Duke University with a degree in physics.

Salim Zeitouni works as an Advisory Software Engineer on the IBM WebSphere Web services interoperability team. He is an active member of the WS-I community, an open industry organization chartered to promote Web services interoperability and currently chairs the Sample Applications Work Group. Prior to joining the Web services team, Salim was a team lead on several WebSphere products

that provide integrated client-server environment and application development tools to extend business applications and data to mobile users. Since joining IBM in 1996, Salim has worked on several WebSphere, Tivoli, and Lotus software products.