CA API Gateway 9.1

9.4 9.1

Customize SOAP Fault Response Assertion

The default behavior of the Gateway is to return a generic fault message within a SOAP envelope ("SOAP fault") when a problem occurs in a policy—for example, an assertion failure, authentication failure, routing failure, etc. The Customize SOAP Fault Response assertion lets you configure the SOAP fault response on a policy-by-policy basis. You can configure the level of detail returned and whether the SOAP faults are digitally signed. The following options are available for the SOAP fault detail level:
gateway90
The default behavior of the Gateway is to return a generic fault message within a SOAP envelope ("SOAP fault") when a problem occurs in a policy—for example, an assertion failure, authentication failure, routing failure, etc. The
Customize SOAP Fault Response
assertion lets you configure the SOAP fault response on a policy-by-policy basis. You can configure the level of detail returned and whether the SOAP faults are digitally signed. The following options are available for the SOAP fault detail level:
  • Drop connection:
     When the policy fails, simply drop the connection without providing any response.
  • Generic SOAP fault:
     Return a brief SOAP fault message.
  • Medium detail:
     Return a SOAP message with more details.
  • Full detail:
     Return a comprehensive SOAP fault message.
  • Template:
     Lets you define your own message to be returned.  
The Customize SOAP Fault Response assertion is intended to override the general Gateway SOAP fault response for a particular policy—it does not control whether a SOAP fault is returned but rather how the SOAP fault will appear if a SOAP fault should occur. If you do not need to override the general response, then this assertion is not required. For more information about the general SOAP fault response, see SOAP Faults.
To learn more about selecting a private key for this assertion, see Selecting a Custom Private Key.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click
    Customize SOAP Fault Response as...
    in the policy window and select
    Fault Response Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Select a SOAP fault level to use:
    Setting
    Description
    Drop Connection
    Simply drops the connection when a SOAP fault or any other policy error is encountered; no error is returned.
    Generic SOAP Fault
    Returns a simple SOAP fault which states that a policy violation has occurred.
    Medium Detail
    Takes the "Generic SOAP Fault" setting and adds policy violation details for each assertion violated. Includes any audit detail messages generated by the failed assertions.
    At this setting, all messages of severity level "Info" or higher are included. For more information, see Message Auditing.
    Avoid using this setting if you do not want to reveal the reasons for rejection to the requestor.
    Full Detail
    Takes the "Medium Detail" setting and adds information for each assertion that was evaluated during the request (regardless of whether it succeeded for failed).
    At this setting, messages of all severity levels are included. For more information, see Message Auditing.
    Avoid using this setting if you do not want to reveal the reasons for rejection to the requestor.
    Template Fault
    Allows you to define your own template response. This is the same as using the Return Template Response to Requestor assertion, except the "Response HTTP Status" is hard coded to '500' and the "Response Content Type" is always 'text/xml'. You may reference context variables within the template.
    [
    Include the policy download URL...
    ]
    For all settings except for
    Drop Connection,
     you can specify whether the policy download URL should be included with the SOAP fault in an HTTP header, if it is required. For example, a failure of an XPath assertion would not cause the policy URL to be included, while a credential assertion such as Require HTTP Basic Credentials would include the URL.
    The default is to include this URL.
    [
    Sign SOAP Fault
    ]
    For all settings except for
    Drop Connection,
     you can specify that the SOAP fault be digitally signed. This setting overrides the
    soapfault.sign
     cluster property.
    When the SOAP fault is signed, the Gateway chooses the signing key in the following order of preference (this overrides the
    soapfault.privateKeyAlias
     cluster property):
    1. Custom Private key:
       If a custom private key has been selected for the assertion, it is used for signing. For more information, see Selecting a Custom Private Key.
    2. Session key:
       If a custom private key has
      not
       been selected or if the [
      Use default private key
      ] option was selected on the Private Key Alias dialog, then the session key will be used. A session key exists if the policy uses a security method that relies on a session key (for example, Kerberos token profile, secure conversation, encrypted key).
    3. Default SSL key:
       If no session key exists and no custom private key was selected, then the default SSL key is used. To learn more about the default SSL key, see Private Key Properties.
    If a custom private key was selected and that key is subsequently destroyed or becomes unavailable, then the SOAP faults will
    not
     be signed, regardless of the Sign SOAP Fault check box. The default SSL key will not be used.
    Use SOAP Fault for all errors
    Select this check box to return a SOAP fault regardless of the error. This will display the complete set of audit detail messages, including messages that are not associated with an assertion. For example, this option can help you diagnose errors such as:
    • Non-SOAP and malformed XML errors for SOAP services
    • Errors during WS-Security processing, such as digital signature validation errors
    The Customize SOAP Fault assertion must be placed within a
    "message received"
     or
    "pre security"
     global policy fragment in order for the [
    Use SOAP Fault for all errors
    ] option to have any effect. For more information on these policies, see Working with Global Policy Fragments.
    Use Client Fault code for all errors
    Select this check box to override the fault code with the client's fault code. This will result in
    "<faultcode>soapenv:Client</faultcode>"
     being returned.
    Clear this check box to use the server's fault code. This will result in
    "<faultcode>soapenv:Server</faultcode>"
     being returned. This setting is the default.
  4. Click [
    OK
    ]
    when done. 
    The fault response selected is added to the assertion name in the policy window, along with any custom private key selected. For example: 
    "Customize SOAP Fault Response as Full Detail (Key: XYZ)"
    . 

Content feedback and comments