Troubleshooting
Problem
One of the following errors occur when invoking a Web service with WS-Security:
WSWS3173E: Error: Did not understand "MustUnderstand"
header(s):{[http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
]}Security
-or-
org.apache.axis2.AxisFault: Must Understand check failed for headers: {[http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
]}Security
[
]
Diagnosing The Problem
A SOAP Security header looks like this:
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sece…; |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wss:Security soapenv:mustUnderstand="1" xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wss:UsernameToken>
<wss:Username>username</wss:Username>
<wss:Password>password</wss:Password>
</wss:UsernameToken>
</wss:Security>
</soapenv:Header>
<soapenv:Body>
<se:Echo xmlns:se="http://webservice.net/Service" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance">
<se:value xsi:nil="true"/>
</se:Echo>
</soapenv:Body>
</soapenv:Envelope>
A must understand error can originate from a client or provider application. One of the following has happened:
|
The JAX-WS and JAX-RPC runtimes emit different error messages for must understand errors:
- JAX-WS
- JAX-RPC
The must understand error emitted by JAX-WS is:
|
The must understand error emitted by JAX-RPC is:
|
The JAX-WS and JAX-RPC runtimes can produce this error for different reasons:
- JAX-WS
- No inbound WS-Security constraints applied to the application
- The policy was not loaded properly
- The inbound bindings were not loaded properly
- JAX-RPC
- When a WebSphere JAX-RPC application emits this error, it can only caused by no inbound WS-Security constraints being applied to the application.
When a WebSphere full profile JAX-WS application emits this error, it is caused by one of the following: |
|
![](/support/pages/system/files/support/swg/swgtech.nsf/0/4db5bdbdde7ea5ef8525717300637fd5/Diagnosis/0.1DF4.gif)
Resolving The Problem
See the section that corresponds to the runtime that you are using:
Finding the origination of the error When you see a must understand error on a client application, you need to determine if the error was received in a SOAP response or if the error originated from the client itself. To see if the error was received in a SOAP response, do the following steps with a WS-Security trace; information on how to obtain a WS-Security trace can be found on MustGather: Web Services Security (WS-Security) problems with WebSphere Application Server:
Checking if the error is because there is no policy or there was an error loading the policy (or binding) If there is no inbound policy attached, you will see an entry like the following in a WS-Security trace:
If you don't see that, search backwards in the trace from the error point for "not loaded properly". If you see this, there was an error loading the policy or bindings for the application. Checking if Security constraints are applied for generating a request on a client When you are expecting a SOAP message to contain a Security header, but it does not, you will most likely see entries like the following in a WS-Security trace. This trace entry means that there is no outbound policy set attached to the application. A trace snip is from a client on the request message:
Checking if Security constraints are applied for consuming a response on a client This trace snip is from a client on the response message:
The WS-Security configuration of the Web service client and Web service provider must match. After completing these steps, you will know if your client is sending a Security header that the provider is not expecting or the other way around. Do one of the following:
|
Identifying the error When a WebSphere JAX-RPC application emits a must understand error, it can only caused by no inbound WS-Security constraints being applied to the application. The WS-Security configuration of the Web service client and Web service provider must match. You will see a stack trace similar to this in a web services provider trace when a provider emits a must understand error:
When a client emits a must understand error, this class will be in the stack instead of invokeServerRequestHandler:
Setting up the trace To setup a WS-Security trace, you can use the information on MustGather: Web Services Security (WS-Security) problems with WebSphere Application Server. Update the trace string to add this entry:
If you do not add this entry, if the must understand error is emitted by a JAX-RPC client, it will not show up in the trace. Finding the origination of the error When you see the must understand error in a JAX-RPC client application, you need to determine if the error was received in a SOAP response or if the error originated from the client itself. To see if the error was received in a SOAP response, do the following steps with a WS-Security trace (as described above):
Checking a JAX-RPC application's WS-Security configuration To check if the Web service provider has the proper WS-Security configuration, examine the ibm-webservices-ext.xmi and ibm-webservices-bnd.xmi files. Client applications use ibm-webservicesclient-ext.xmi and ibm-webservicesclient-bnd.xmi. If WS-Security is configured, you will see something similar to this. This example is configured to use basic authentication with a Username token:
Resolving the problem If the files do not contain any WS-Security information, then two options are available to resolve the problem:
The only supported way to change the WS-Security configuration for a JAX-RPC application is with an assembly tool, such as Rational Application Developer. The WebSphere Version 6 Web Services Handbook Development and Deployment Redbook contains instructions on how to setup WS-Security for clients and providers. See:
|
Identifying the error A web service call of a Service Component Architecture (SCA) import web service binding might lead to a "AxisFault: Must Understand check failed" exception when a SOAP request needs to include some additional SOAP header information. If a web service binding is used as an SCA import module to call an external web service, the following exception might occur during the invocation of this SCA module in the SystemOut.log file:
Cause The cause of the problem is a policy mismatch between the web service client and the web service provider. This error is exclusively caused by an application sending a SOAP Security header, but the receiver not expecting it. One of the following has happened:
In IBM Business Process Manager, WebSphere Process Server, or WebSphere Enterprise Service Bus, SOAP Security header information is not processed by default. If a web service call requires some additional SOAP header information, the web service call needs to be modified properly to match the web service partner expectation. Diagnosis When you see this error on a client application, you need to determine if the error was received in a SOAP response or if the error originated from the client by processing a 'good' SOAP response. To do this, expand the JAX-WS section above and perform the steps under Finding the origination of the error. Resolving the problem You can fix this error in one of the following two ways:
|
Was this topic helpful?
Document Information
Modified date:
22 June 2018
UID
swg21238420