Validate XML Schema Assertion (Message Validation/Transformation)

gateway
The 
Validate XML Schema 
assertion allows you to specify a schema for validating a web service or XML application request or response messages. This assertion can be used to protect backend web services against the following threats:
  • XML Parameter Tampering:
     All XML parameters in the request are validated to ensure conformance with the XML schema specifications. This is to prevent injection of malicious scripts or content into the request parameters.
  • XDoS Attacks:
     The message structure and content are examined to ensure that they are correct.
A message schema is provided by the CA API Gateway administrator. If the service's WSDL contains a schema, then that schema can be extracted to serve as the starting point for the schema used in the Validate XML Schema assertion. This WSDL schema can be extracted in whole or in request or response message-specific parts. If the schema contains import statements that refer to external schemas, the Policy Manager will attempt to fetch all unresolved schemas in an import tree (for example, a schema referencing another schema) and add them to the global schema table. You can view these imported schemas using the Manage Global Resources task. If the Policy Manager is unable to resolve a schema (for example, because of a bad URL or URI), you will be prompted to manually add the schema.
The format of the import statement can affect how it is received by the CA API Gateway. A full URL path is most preferable and is always resolvable (e.g., "http://schema.example.com/test.xsd"). Just the file name is acceptable, provided that the exact name can be located in the Global Schemas stored in the CA API Gateway (e.g., "test.xsd"). Not acceptable are paths containing a specific drive letter (e.g., "f:\test.xsd"), or relative paths such as "../test.xsd". 
A policy can contain multiple Validate XML Schema assertions. The runtime application of a schema is determined by its placement in the policy path. If routing has already occurred when the Validate XML Schema assertion initiates, then the schema will be applied to the response message. If routing has not yet occurred, then the schema will be applied to the request message.To learn about selecting the target message for this assertion, see Select a Target Message.
Schema Failure in Context Variable
When a schema validation fails, an audit record is created and the reason for failure is placed in the context variable 
${schema.failure}
. This makes it possible to reference the failure later in the policy (for example, inclusion in the Return Template Response to Requestor assertion).
Schemas with Circular References
A "circular reference" occurs when a schema references other schemas that ultimately point back to the original schema. The Policy Manager will fetch all schemas from a destination, circular or not, and add them to the global schemas table.
CA API Gateway does not support Circular References.
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. When adding the assertion, the Schema Validation Properties automatically appear; when modifying the assertion, right-click 
    <target>:
     Validate XML Schema 
    in the policy window and select 
    XML Schema Validation Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Specify the target message to be validated:
    • Request:
       Select this to validate the request message. This is the default setting if the assertion is positioned before the routing assertion in the policy.
    • Response:
       Select this to validate the response message. This is the default setting if the assertion is positioned after the routing assertion in the policy.
    • Other Message Variable:
       Select this to validate a message stored in a context variable of type 'Message'. This variable must be predefined or has been set in the policy prior to the Validate XML Schema assertion. For more information on Message variables, see Context Variables. 
      The message target can also be set outside of the assertion properties. For more information, see Select a Target Message.
  4. For SOAP messages, specify the portion of the message that will be validated by the schema. For non-SOAP messages, the schema will be applied to the entire message.
    • Entire SOAP Message
       Schema validation is performed on the entire SOAP envelope. The schema configured by the policy author in this case should be based on the SOAP envelope schema. It may optionally include definitions that cover the payload of the SOAP headers and/or the SOAP body. If you need to validate a schema against the SOAP message including any security elements in the header (for example, signature element), you should additionally import the WS-Security schema in your custom schema (for example, 
      htp://schemas.xmlsoap.org/ws/2002/04/secext/secext.xsd
      ). 
    • SOAP Message Body
       Apply the schema to each element under the 
      soap:Body
       element in a SOAP message. This setting is the default.
      When importing an RPC/literal-style WSDL using this option, the system will prompt you with: 
      "The WSDL style seems to indicate that the schema validation should be applied to the body 'arguments' rather than the entire body. Would you like to change the setting accordingly?"
       Answer 'Yes' only if you are certain that the web service is RPC/literal-style.
    • SOAP Message Arguments
       Apply the schema to the children elements under the first child element under the 
      soap:Body
      . This is typically used in RPC/literal-style web services where the argument elements themselves are not declared in the schema.
  5. From the 
    Schema location
     drop-down list, specify where the schema is coming from:
    Setting
    Description
    Configure in advance
    Select this option to define a root schema and all dependencies directly.
    a. Specify the schema using any of the following methods:
    • Manually type the code into the 
      Validation Schema 
      box or copy and paste the code from another source.
    • If the CA API Gateway can detect a schema in the WSDL document, you can click [
      Extract Schema from WSDL
      ] to import the schema from the WSDL document. A WSDL-based schema is typically only included in document-style web services. Complete the Extract Schema from WSDL dialog in step 6 below.
    • Load the schema from a URL by clicking [
      Read URL
      ] and then specifying the URL.
      To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [
      HTTP Options
      ] to open the Manage HTTP Options dialog.
    • Load the schema from a local file by clicking [
      Read File
      ] and then browsing to the appropriate file. The 
      System ID
       field is automatically populated when opening a resource (from the WSDL, a URL, or a file).
      (1) The schema maximum size is controlled by the 
      schemacache.maxSchemaSize 
      cluster property. (2) If the cluster property 
      schema.allowDoctype
       is set to "true", then the "Configure in advance" XML schema may contain a document type definition (DTD); otherwise, DTDs are not permitted (default
      b. Review the content of the 
      Validation Schema 
      box and edit if necessary. You can right-click within the box for some useful tools to help you edit. For more information, see Using the XML Editor.
    Monitor URL for latest value
    Select this option to specify a URL for the root schema. The CA API Gateway loads all the dependencies and then monitors the external resources for changes over time.
    Type the address in the 
    URL to monitor
     field. The URL may contain context variables that will be resolved at run time. By default, CA API Gateway will issue an 
    If-Modified-Since:
     HTTP request for this URL approximately every minute while the schema is in use.
    To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [
    HTTP Options
    ] to open the Manage HTTP Options dialog.
    The schema maximum size is controlled by the 
    schemacache.maxSchemaSize
     
    cluster property.
    Pick XML Schema from global resources
    Select this option to pick the validation schema from the global resources table. Choose the global schema to use from the 
    Selected schema
     drop-down list. If the schema you require is not listed, click [
    Manage Global Resources
    ] to define it, or to modify or remove other global resources defined in the system. For more information, see Manage Global Resources.
  6. If you chose to extract the schema from a WSDL document, the following dialog appears. Configure the dialog as follows and then click [
    OK
    ] when done.
    Setting
    Description
    Select the WSDL Schema to Extract
    If the WSDL document contains more than one schema, select the schema to use from the drop-down list. The schema code is displayed in the box below.
    The Validate XML Schema assertion only takes a single schema as input. If the WSDL contains multiple schemas, it may be necessary to reorganize those schemas into one root schema that references other schemas through import statements. The Policy Manager attempts to retrieve the schemas referenced by the import statements and add them to the global schema table. To view these schemas, see Manage Global Resources.
    Import Entire Schema
    Extract the entire schema. This setting is the default.
    Import Request-Specific Elements Only
    Extract only the schema elements particular to request messages.
    Import Response-Specific Elements Only
    Extract only the schema elements particular to response messages.
  7. When a resource with dependencies is opened, you are prompted to confirm whether to import the schema's dependencies as global resources. Select [
    Import
    ] to import the dependencies or [
    Skip
    ] to exclude the dependencies. Select [
    Cancel
    ] to cancel the loading of the resource (whether from the WSDL, a URL, or a file).
  8. If you chose [
    Import
    ] in the previous step, all the schema dependencies that will be processed and potentially added as global resources are listed. Review the list carefully and note the 
    Action
     column for each resource:
    • Ignore:
       The resource will not be imported.
    • Update:
       The resource will update an existing global resource.
    • Create:
       A new global resource will be created for the resource.
    Select [
    Import
    ] to update the global resources or [
    Skip
    ] to not update the global resources. Select [
    Cancel
    ] to cancel the import.   
  9. During import, if there are issues that require manual intervention, you will be prompted to select a resolution:
    • [
      This Time Only
      ]: Use the selected action only for this occurrence of the conflict. When another similar conflict occurs, you will be asked again how to resolve it.
    • [
      Always
      ]: Use the selected action for all the conflicts of this type. You will not be prompted for a resolution if another similar conflict occurs during this import.
  10. On the XML Schema Validate Properties, click [
    OK
    ] when done. If the dependencies of a configured in advance XML Schema are found then the assertion is added to the policy development window. If the Policy Manager is unable to validate the dependencies, you are prompted to manually add the unresolved schema(s).