soalicious: OIC - Resolving "SOAP Header Security was not understood" invoking Web Services

Friday, May 9, 2025

OIC - Resolving "SOAP Header Security was not understood" invoking Web Services

Use Case:

In a utility integration scenario using MultiSpeak-compliant web services, a SOAP request fails with the error:
"CASDK-0033: Received a SOAP fault... Fault Code : soap:MustUnderstand – SOAP header Security was not understood."
This typically occurs when integrating Oracle Integration Cloud (OIC) with a third-party endpoint that requires WS-Security headers.

Root Cause:

The SOAP request included a <wsse:Security> block with mustUnderstand="1", but the target endpoint does not understand or support WS-Security headers in that format.
Alternatively, the expected security token or credentials were missing or not compliant with the service’s expected authentication scheme.

Solution Steps:

Step 1: Understand the Error Message

Error:

Fault Code : soap:MustUnderstand  
Fault String : SOAP header Security was not understood.

This indicates that the service could not process the WS-Security headers, often because it does not support them or requires a different security configuration.

Full error details:

CASDK-0033: Received a SOAP fault while invoking endpoint target: https://<host>/CC/WebAPI/MRCB.asmx.

This indicates a processing exception on the service endpoint side. Please check service side logs to further diagnose the problem

<![CDATA[

Fault Code : soap:MustUnderstand

Fault String : SOAP header Security was not understood.

]]>

Step 2: Analyze the SOAP Request

The failing payload included this header:

<wsse:Security env:mustUnderstand="1" ...>
  <wsu:Timestamp ...>
    <wsu:Created>...</wsu:Created>
    <wsu:Expires>...</wsu:Expires>
  </wsu:Timestamp>
</wsse:Security>

This was likely injected by a policy in Oracle Integration Cloud (OIC) or a SOAP client security configuration.

Step 3: Suppress the insertion of timestamp in the request from the soap invoke connection. This will remove the Security Header from the request.

Reason: The target service does not support WS-Security, modify the request to remove the <wsse:Security> block completely.

Connection snap:

Failing payload:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

<env:Header>

<tns:MultiSpeakMsgHeader env:mustUnderstand="0" UserID="xxxx" Pwd="xxxx" xmlns:tns="http://www.multispeak.org/Version_5.0"/>

<wsse:Security env:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

<wsu:Timestamp wsu:Id="TS-84" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsu:Created>2025-05-09T09:07:58.512Z</wsu:Created>

<wsu:Expires>2025-05-09T10:07:58.512Z</wsu:Expires>

</wsu:Timestamp>

</wsse:Security>

</env:Header>

<env:Body>

<tns:MeterAddNotification xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:tns="http://www.multispeak.org/Version_5.0">

<tns:addedMeters>

<tns:meter>

<tns:meterNo>2345</tns:meterNo>

<tns:utilityInfo>

<tns:servLoc>SL#1435</tns:servLoc>

</tns:utilityInfo>

</tns:meter>

</tns:addedMeters>

</tns:MeterAddNotification>

</env:Body>

</env:Envelope>

Updated working payload: