Introduction: The importance of Web services interoperability
Service Oriented Architecture (SOA) is a current IT architecture and business style of choice. Web services is a preferred style of SOA implementation. Web services interoperability between vendor technologies, especially between IBM WebSphere® J2EE and Microsoft™ .NET platforms, has become an important business requirement for many companies.
The WebSphere System Verification Test team has been working to improve interoperability between WebSphere Web services clients and .NET services, and between .NET Web services clients and WebSphere services. Web services security functions are exercised in both scenarios (See Figure 1), including the following:
- Basic authentication: Username token with timestamp
- Integrity: Digitally signed message body and username token
- Confidentiality: Encrypted body content and user name token
Figure 1. Overview of .NET/WebSphere interoperability test scenarios
We found a number of Web services security interoperability issues during the tests. The findings that follow provide a single reference for interoperation between Web services security enabled WebSphere J2EE and .NET applications.
To complete the solutions introduced in this document, you will need the following software:
- IBM WebSphere client with .NET service
- The .NET system environment, including Microsoft .NET Framework 1.1, Microsoft VisualStudio.NET 2003, and Microsoft WSE 2.0 Service Pack 3
- IBM Rational® Application Developer Version 6.0* or WebSphere Application Server Toolkit version 6.0*. (NOTE: The asterisk [ * ] designates that this article supports versions 6.0, 6.0.1, and 6.0.2. As of February, 2006, testing is still pending for WebSphere version 6.1 and above.)
- Existing .NET client with WebSphere service
WS-security interoperability issues and solutions
Following are the various issues uncovered in our interoperability test, the causes of those issues, and their solutions.
.NET server validates username token nonce and timestamp by default
Problem: When running WebSphere Web services client against a .NET service configured with username token , the following exception is thrown from the .NET server:
Error message. WSE567: The incoming Username token must contain both a nonce and a creation time for the replay detection feature.
Cause: By default, the Microsoft .NET Web service validates the nonce and the timestamp for the username token. However, this is not required by any specification and it is optional to configure the nonce and timestamp properties for a Web service client that is using WebSphere Application Server.
Solution: Complete the following steps to add the nonce and timestamp properties for a username token on a Web service client for WebSphere Application Server. These steps involve an assembly tool such as Rational Application Developer or the Application Server Toolkit:
- Open Web service client deployment descriptor
- Click WS Extension tab
- Expand Add Timestamp
- Check Use Add Timestamp
- Expand Expires
- Check Use Expires
- Specify an expiration time for the time stamp (See Figure 2):
Figure 2. Add Timestamp configuration for WS Extension
- Save the WS Extension configuration
- Click WS Binding tab
- Expand Security Request Generator Binding Configuration.
- Expand Token Generator (See Figure 3):
Figure 3. Username token in Web service client deployment descriptor
- Click the name of the username token that you already created
- Click Edit.
- In the Properties section of the Token Generator dialog, click Add
- Set Name to
- Set Value to
- In the Properties section of the Token Generator dialog, click Add.
- Set Name to
- Set Value to
- Click OK
- Save the client deployment descriptor (See Figure 4):
Figure 4. Nonce and Timestamp properties are added
.NET does not support relative URI for Actor attribute
Problem: The following exception message displays when you use a Microsoft .NET client that accesses a service within WebSphere Application Server with Web services security enabled and the Actor attribute in use.
Error message. Invalid URI: The format of the URI could not be determined.
Cause. This error occurs because Microsoft .Net Web Services Enhancements (WSE) Version 2.0 does not support a relative Uniform Resource Identifier (URI) value for the Actor attribute. WSE Version 2.0 supports an absolute URI for this attribute only. WebSphere supports both absolute URI and relative URI. An example of an absolute URI is
abc://myWebService. An example of a relative URI is
Solution: You can work around this problem in two ways. First, you can remove the Actor attribute. The SOAP Actor attribute is only needed if you have an intermediate hop between the client and target destination. You can also configure the SOAP Actor attribute as an absolute URI in the WebSphere service. To configure Actor attribute for use with WebSphere Application Server, use either the Rational Application Developer (RAD) or the Application Server Toolkit (AST) to complete the following steps:
- Open the Web Service Editor, click the Extensions tab
- Expand Server Service Configuration
- Enter the full absolute URI in the Actor field (See Figure 5):
Figure 5. Enter absolute URI for Actor in Web Services Editor
- Expand Response Generator Service Configuration Details
- Expand Details
- Enter the full absolute URI in the Actor field (See Figure 6):
Figure 6. Enter absolute URI in Actor field under Details
.NET cannot consume SOAP Actor without WS-Addressing headers
Problem: The following exception message displays if your WebSphere client and .NET service have Actor attribute configured with the same value:
Error message. Microsoft.Web.Services2.Addressing.AddressingFault: Destination Unreachable ---> System.Exception: WSE817: The <To> header must match the Actor attribute on this receiver.
Cause: This will occur if you have a SOAP Actor attribute configured on the client. This is a .NET WSE2.0 limitation. The problem is that the .NET server looks for the WS-Addressing header <was:To> when the SOAP Actor attribute is configured on the client. But this is not required by any specification.
Solution: You can work around this in one of the two following ways:
- Remove the Actor attribute, since the SOAP Actor attribute is only needed if you have an intermediate hop between the client and target destination.
- As an alternative, you can enable WS-Addressing in the WebSphere client. The public API for WS-Addressing is not available in WAS 6.0*, so you will need to move to WebSphere Version 6.1. Use the WebSphere 6.1 public API for WS-Addressing to add the <was:To> WS-Addressing header.
.NET doesn't understand Java-based key file formats
Problem: If your WebSphere service uses a Java-based key file format such as .JCEKS and .KS for signing or encryption, and you try to import the same key file in Windows using Certificate Import Wizard for the .NET client, you will see the following exception message from the import (See Figure 7):
Error message. The file type is not recognizable. Select another file.
Figure 7. Windows does not understand Java-based key file format
Cause: Windows doesn't support Java-based key file formats. It only supports .P12, .PFX, .P7B, .SST format key files.
Solution: You have two ways to work around this, as follows:
- Convert the Java-based key file to a file format understood by Windows, such as .P12 format, and then import this key file into the Windows system. You can use key tools from different vendors to perform this task. By using this workaround, WebSphere and .NET use different key file format for the same keys, meaning that the WebSphere side can keep the Java-based key file format unchanged and only the .NET side uses the converted key file format.
- Use a single key file format understood by both Windows and WebSphere, such as .P12 format, on both .NET and WebSphere.
.NET default key identifier doesn't match WebSphere KEYID
Problem: If your WebSphere service uses KEYID as the key informaton type for signing or encryption, when running a .NET client you might receive the following exception message from WebSphere:
Error message. WSEC6099E: key information about [null] is not found.
Cause: The default .NET key identifier is Windows Key Identifier, which does not match the WebSphere RFC3280 key identifier.
Solution: Override the .NET default key identifier to RFC3280 key identifier by adding the following section in the
Listing 1. Overwrite .NET default key identifier
<!-- Modify the following section in web.config or app.config file--> <security> ... <x509 storeLocation="CurrentUser" useRFC3280="true" /> </security>
.NET service system ASP.NET default worker process account must be granted permission to access private key
Problem: If your WebSphere Web services client is trying to talk to the .NET service with encryption constraint enabled, when the .NET server tries to decrypt the message, you might encounter the following exception message:
Error message. Server unavailable, please try later.
Cause: The exception message is misleading since it does not state the real cause. The problem is that when the WebSphere client uses a public key to encrypt the request message and the .NET server tries to use the paired private key to decrypt the message, the ASP.NET worker process account is not granted permission to access the private key.
Solution: Grant the ASP.NET worker process account private key access by following these steps:
- In the .NET Web service system, Start > All Programs > Microsoft WSE 2.0 > X509 Certificate Tool
- On the WSEX.509 Certificate Tool. (See Figure 8):
Figure 8. X509 Certificate Tool
- Certificate Location should be set to
- Store Name should be set to
- Click Open Certificate
- Select the certificate containing the private key, for example SoapProvider (See Figure 9):
Figure 9. Select Certificate
- Click OK
- Click the View Private Key File Properties... button (See Figure 10):
Figure 10. View Private Key File Properties
- Click the Security tab
- Click Add (See Figure 11):
Figure 11. Add ASPNET account to access the private key on XP Professional system
network servicefor a 2003 server system, or Enter
aspnetfor XP Professional and Windows 2000 systems
- Click OK > OK
.NET default encryption algorithm is aes128
Problem: If your WebSphere service uses an encryption algorithm other than aes128, say, tripledes, you'll see the following exception message from .NET when running encryption WS-Security constraint:
Error message. WSEC5363E: Unauthorized data encryption method: http://www.w3.org/2001/04/xmlenc#aes128-cbc.
Cause: The .NET client default encryption algorithm aes128 does not match the service encryption algorithm.
Solution: Override the .NET default encryption algorithm by adding the
sessionKeyAlgorithm name field in the
binarySecurityTokenManager element in the
web.config files in the .NET client project. For example, if your server side encryption algorithm is tripledes, the portion of the
web.config files looks like the code shown in Listing 2.
Listing 2. Overwrite .NET default encryption algorithm
<!-- Add the following section in web.config or app.config file--> <security> ... <binarySecurityTokenManager valueType= "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"> <sessionKeyAlgorithm name="TripleDES" /> </binarySecurityTokenManager> </security>
Solving interoperability issues key to SOA success
Web services interoperability is a key factor to the success of SOA. But there have always been interoperability issues between technologies from different vendors, caused by different understandings and implementations of industry standards. Discovering these issues and solutions to them will be very helpful to the customers encountering problems with Web services interoperability. This article focused on Web services security interoperability issues between IBM WebSphere J2EE and Microsoft .NET platforms, and provided quick solutions or step-by-step instructions on how to work around or resolve them. The readers should now have a basic understanding about the possible issues they might face in running WS-Security-enabled applications across these two platforms.
- The WebSphere Application Server Version 6.0 Information Center offers more information about Web service security configurations on WebSphere Application Server version 6.0.
- SOA and Web services -- hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
- Architecture: Build for the future -- visit the Architecture area on developerWorks and get the resources you need to advance your skills in the architecture arena.
Get products and technologies
- See Microsoft MSDN for details about Microsoft .NET technologies.
- See Microsoft Web Services Enhancements (WSE) 2.0 SP3 download page to learn more about and WSE 2.0 SP3 for .NET.
- Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
- developerWorks blogs -- get involved in the developerWorks community.