WS-SecureConversation interoperability between WebSphere V8 and Windows Communication

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 Link
Advisory Software Engineer
Web Services Interoperability Development
IBM, Research Triangle Park, NC
Hyen-Vui (Henry) Chung
Software Development Engineer
Amazon, Austin, TX
Charles Le Vay
Senior Software Engineer
WebSphere Technical Evangelist – Emerging Technology IBM, Research Triangle Park, NC
Salim Zeitouni
Advisory Software Engineer
WebSphere 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 Contents
Introduction................................................................................................................................................2
Getting started............................................................................................................................................3
Import certificates into Windows certificate store.....................................................................................3
Prepare WAS for interoperability with WCF.............................................................................................4
Manually enable OnlySignEntireHeadersAndBody..............................................................................4
Change 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.....................7
Generate WCF client artifacts using svcutil...........................................................................................7
Create a WCF project and import the generated artifacts......................................................................8
Update WCF client to include client credentials..................................................................................11
Compile the project..................................................................................................................................20
Test the WCF client..................................................................................................................................21
Summary..................................................................................................................................................22
Resources.................................................................................................................................................22
Specifications...................................................................................................................................22
WebSphere Application Server Information Center........................................................................22
Feature Pack for Web Services & developerWorks.........................................................................22
Windows 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 WSSecureConversation. 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 WSSecurity 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 started
You 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.
2.
3.
4.
Install Microsoft Visual Studio. You can download a 90-day trial here.
Install Microsoft .NET 4.0 or newer. You can download .NET 4.0 here for free.
Install the latest Microsoft Windows SDK. You can download Version 7.1 here for free.
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 WCF
For 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-ServiceSC.wsdl
<sp:MustSupportRefExternalURI/>
<sp:RequireExternalUriReference/>
5.
Save the updated WSDL.
Generate WCF client artifacts using svcutil
Using 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\Desktop
3. Run the following command:
<full path>svcutil /config:App.config WAS-Service-SC.wsdl
where <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 artifacts
In this section, you will create a WCF project and import the generated client artifacts.
1.
2.
3.
4.
5.
6.
Start Microsoft Visual Studio.
In Visual Studio, create a project by clicking File => New => Project.
In the New Project window, select WCF => WCF Service Library as shown in Figure 2.
Name the project WCF-ClientForWAS-Service.
For location, specify WCFClient.
Click OK.
Figure 2. Create a new WCF project
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 3. Change project type to console application
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
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 credentials
At 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.
2.
Right-click App.config and select Edit WCF Configuration to open the Microsoft service
configuration editor.
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.
Figure 5. Select endpoint behavior
3.
Specify Client-Cert-Behavior in the Name field, and click Add as shown in Figure 6.
Figure 6. Create Client-Cert-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 7. Select clientCredentials
5.
The results are displayed, as shown in Figure 8. Select Client-Cert-Behavior =>
clientCredentials => clientCertificate.
Figure 8. clientCredentials has been added
6.
In the right pane, specify the following values, as shown in Figure 9:
•
•
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.
Figure 13. Set AllowSerializedSigningTokenOnReply to True
14. Select File => Save to save the changes to the App.config file.
Compile the project
To 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.
Figure 14. Visual Studio build solution
Test the WCF client
In 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-ClientForWASService\bin\Debug directory.
3. The compile creates two files: WCF-ClientForWAS-Service.exe and WCF-ClientForWAS-
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.exe
CLIENT>> Sending message 'HELLO WAS, This is WCF Client Request'...
CLIENT>> The answer is 'JAX-WS==>>HELLO WAS, This is WCF Client Request
Summary
In 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
Specifications
Web Services Security: SOAP Message Security 1.0 WS-Security (2004)
Web Services Security: SOAP Message Security 1.1
Web Services Secure Conversation
WebSphere Application Server Information Center
WebSphere 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 WSSecurity 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 WSSecureConversation 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 Foundation
Web 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.