# Web Service Filter

## Contents
Overview General Settings Routing Validation Message Interception Points WSDL Monitoring

## Overview
The Web Service Filter is used to control and validate requests to the Web Service and responses from the Web Service. Typically, this is automatically generated and populated as a Service Handler when a WSDL file is imported into the Web Services Repository. For example, if you import the WSDL file for a Web Service named `ExampleService`, a Service Handler for ExampleService filter is automatically generated. However, you can also configure a Web Service Filter manually. In cases when the imported WSDL file contains WS-Policy assertions, a number of policies are automatically created to generate the filters required to generate the relevant security tokens (for example, SAML, WS-Security UsernameToken, and WS-Addressing headers). These policies perform the necessary cryptographic operations (for example, signing and encrypting) to meet the security constraints stipulated by the WS-Policy assertions.
## General Settings
Name: Enter an intuitive name for the filter in this field. Web Service Context: Click the browse button to the right of this field to display the hierarchy of Web Services that have been added to the Web Services Repository. Select the checkbox for a Web Service to set the context.
## Routing
When routing to a service, you can specify a direct connection to the Web Service endpoint by using the URL in the WSDL or you can override this URL by entering a URL in the field provided. Alternatively, in cases where the routing behavior is more complex, you can delegate to a custom routing policy, which takes care of the added complexity. The top-level radio buttons on the Routing tab allow for these alternative routing configurations. Direct Connection to Service Endpoint: Select this option to route to either the URL specified in the WSDL or a URL. The radio buttons in the Routing Details group enable you to choose between using the URL in the WSDL and providing an override. When providing an override, you can enter the new URL in the URL field. Alternatively, you can specify the URL as a property so that the URL is built dynamically at runtime from the specified message attributes (for example `${host}:${port}`, or `${http.destination.protocol}://${http.destination.host}:${http.destination.port}`). In both cases, you can configure the connection details, such as SSL and other authentication schemes, for the direct connection using the fields in the Connection Details group. For more details, see the Connection Filter tutorial. Delegate to Routing Policy: If you wish to use a dedicated routing policy to send messages on to the Web Service, you can select this radio button. Click the browse button next to the Routing Policy field. Select the checkbox for the policy that you want to use to route messages, and click the OK button.
## Validation
The WSDL for a Web Service contains information about the SOAP Action, SOAP Operation, and the data types of the message parts used in a particular SOAP operation. The Enterprise Gateway creates the following implicit validation incoming requests for the Web Service: SOAPAction HTTP Header: If a Web Service requires clients to send a certain SOAPAction HTTP header in all requests, the Enterprise Gateway can check the value of this header in the incoming request against the value specified in the WSDL. SOAP Operation and Namespace: The WSDL defines the SOAP Operation and namespace to be used in the SOAP request. The SOAP Operation is defined as the first child element of the SOAP Body element. The Enterprise Gateway can check the value of this element in an incoming SOAP request and its namespace against the values specified in the WSDL. Relative Path: The filter ensures that requests for this Web Service are received on the same URL as that specified in the `<service>` block of the WSDL. It is also common for a WSDL document to contain an XML Schema that defines the format and types of the message parts in the request. This is usually the case for document/literal style SOAP requests, where a complete XML Schema is embedded or imported into the `<wsdl:types>` block of the WSDL. When using a WSDL to import a service into the Web Services Repository, the Policy Studio can extract the XML Schema from the WSDL and configure the Enterprise Gateway to validate incoming requests against it. Select the Use WSDL Schema if you want to validate incoming requests against the Schema in the WSDL. Alternatively, you can create a custom-built policy to validate the contents of incoming requests. To do this, select the Delegate to Validation Policy radio button, and the click the browse button next to the Message Validation Policy field. Select the policy that you want to use to validate requests, and click the OK button.
## Message Interception Points
The configuration settings on the Message Interception Points tab determine how the request and response messages for the service are processed as they pass through the Enterprise Gateway. Several message interception points are exposed to enable you to hook into different stages of the Enterprise Gateway's request processing cycle. At each of these interception points, it is possible to run policies that are specific to that stage of the request processing cycle. For example, you can configure a logging policy to run just before the request has been sent to the Web Service and then again just after the response has been received. Typically, the configuration settings on this screen are automatically configured when importing a service into the Web Services Repository based on information contained in the WSDL. In cases where the WSDL contains WS-Policy assertions, a number of policies are automatically generated and hooked up to perform the relevant security operations on the message. For example, policies are created to insert SAML assertions, WS-Security Username Tokens, WS-Addressing headers, and WS-Security Timestamps into the message. Similarly, filters are created to sign and encrypt the outbound message, if necessary, and to decrypt and validate the signature on the response from the Web Service. Order of Execution: It is important to note the following in terms of the order of execution of the message interception points: The interception points are executed in the following order: 1. Request from Client 2. User-defined Request Hooks 3. Request to Service 4. Response from Service 5. User-defined Response Hooks 6. Response to Client In steps 1, 3, 4, and 6, the execution order is as follows: A) Before Operation-specific Policy B) Operation-specific Policy Shortcuts C) After Operation-specific Policy The overall order of all the message interception points is given in the sequence below. 1. Request from Client: This is the first message interception point, which enables you to run a policy against the request as it is received by the Enterprise Gateway. Typically, this is where authentication and authorization events should occur. 1A) Before Operation-specific Policy: This is usually where authentication policies should be configured because it is the earliest point in the request cycle that you can hook into. To select a policy to run at this point, click the browse button, and select the checkbox next to a previously configured policy. 1B)Operation-specific Policy Shortcuts: If you want to run policies that are specific to the different operations exposed by the Web Service, click the Edit button at the bottom of the table to set this up. For example, you may want to perform different validation on requests for the different operations. On the Policy Shortcut Editor dialog, enter the Operation Namespace and Operation Name in the fields provided. Enter a regular expression used to match the value of the SOAPAction HTTP header in the SOAPAction Regular Expression field. Finally, select the policy to run requests for this operation by clicking the browse button next to the Policy Shortcut field. Select the checkbox next to the policy that you want to run. 1C) After Operation-specific Policy: This enables you to run a policy on the request after all the operation-level policies have been executed on the request. Select the appropriate policy as described earlier by clicking the browse button. 2. User-defined Request Hooks: Users should primarily use this interception point to hook in their own custom-built request processing policies. User-defined Request Policy: Browse to your custom-built request processing policy using the browse button as before. 3. Request to Service: This enables you to alter the message before it is routed to the Web Service. For example, if the service requires the message to be signed and encrypted, you can configure the necessary policies here. 3A) Before Operation-specific Policy: This enables run policies on the message before the operation-level policies are run. Select the policy to run as outlined in the previous sections. 3B) Operation-specific Policy Shortcuts: Operation-level policies on the request to the Web Service can be run here. For example, if the input policy for a particular operation requires the body to be signed and encrypted, a Locate XML Nodes filter can be run here to mark the required nodes. 3C) After Operation-specific Policy: This is the last interception point available before the message is routed on to the Web Service. For example, if certain operation-level policies have been run to mark parts of the message to be signed and encrypted, the signing and encrypting filters should be run here. 4. Response from Service: This is executed on the response returned from the Web Service. 4A) Before Operation-specific Policy: If the response from the Web Service is encrypted, this interception point enables you to decrypt the message before any of the operation-level policies are run on the decrypted message. 4B) Operation-specific Policy Shortcuts: The policies configured at this point run on specific operation-level responses (for example, `getHelloResponse`) from the Web Service. 4C) After Operation-specific Policy: This should be used to run policies after the operation-level policies have been run. For example, this is the appropriate point to place an XML Signature Verification filter. 5. User-defined Response Hooks: You should primarily use this interception point to hook in custom-built response processing policies. User-defined Response Policy: Browse to your custom-built response processing policy using the browse button as before. 6. Response to Client: This enables you to process the response before it is returned to the client. 6A) Before Operation-specific Policy: As before, this enables you to process the message with a policy before the operation-level policies are run on the response. 6B) Operation-specific Policy Shortcuts: The policies listed here are run on each operation response. 6C) After Operation-specific Policy: This is the very last point at which you can run policies to process the response message before it is returned to the client. For example, if you are required to return a signed and encrypted response message to the client, the signing and encrypting should be done at this point.
## WSDL
You can expose an imported WSDL file to clients of the Enterprise Gateway. A client can retrieve a WSDL for a service by appending the `WSDL` name to the query string of the relative path on which the service is accepting requests. For example, if the service is accepting requests at the URL `http://server:8080/services/getHello`, the client can retrieve the WSDL on the following URL: `http://server:8080/services/getHello?WSDL` Important Note: When the Enterprise Gateway returns the WSDL to the client, it dynamically modifies the service URL of the original WSDL to point to the machine on which the Enterprise Gateway is running. For example, the original WSDL contains the following service element, where `www.service.com` resolves to an internal IP address that is not accessible to the public Internet:
    <wsdl:service name="GetHelloService">
      <wsdl:port name="GetHelloServiceSoap" binding="tns:ServiceSoap">
        <soap:address location="http://www.service.com/getHello"/>
      </wsdl:port>
    </wsdl:service>
When the Enterprise Gateway returns this WSDL to the client, it dynamically modifies the value of the `location` attribute to point to the name of the machine hosting the Enterprise Gateway. In the following example, the `location` attribute has been modified to point to the Enterprise Gateway instance running on port 8080 on the Oracle_SERVER host:
    <wsdl:service name="GetHelloService">
      <wsdl:port name="GetHelloServiceSoap" binding="tns:ServiceSoap">
        <soap:address location="http://Oracle_SERVER:8080/getHello"/>
      </wsdl:port>
    </wsdl:service>
When the client receives the WSDL, it can automatically generate the SOAP request for the `getHello` service, which it then sends to the Oracle_SERVER machine on port 8080. Complete the following fields if you wish to expose the WSDL for this service to clients. Advertise WSDL to the Client: Select this option if you wish to publish the WSDL for the selected Web Service. It is important to note that the exposed WSDL represents a virtualized view of the back-end Web Service. In this way, clients can retrieve the WSDL from the Enterprise Gateway, generate SOAP requests, and send these requests to the Enterprise Gateway. The Enterprise Gateway then routes the requests on to the Web Service. WSDL Access Policy: If you want to configure a policy to control or monitor access to the WSDL for this service, you can select the policy by clicking the browse button to the right of this field. Select the policy that you want to use to run on requests to retrieve the WSDL.
## Monitoring
The fields on this tab enable you to configure whether this Web Service stores usage metrics data to a database. This information can then be used by Service Monitor to produce reports showing how and who is calling this Web Service. The following fields are available on this tab: Monitor service usage: Select this option if you want to store message metrics for this Web Service. Monitor service usage per client: Select this option if you want to generate reports monitoring which authenticated clients are calling which Web Services. Monitor client usage: If you want to generate reports on authenticated clients, but are not interested in what Web Services they are calling, select this option, and unselect the Monitoring service usage per client checkbox. Which attribute is used to identify the client?: Enter the message attribute to use to identify authenticated clients. The default is `authentication.subject.id`, which stores the identifier of the authenticated user (for example, the username or user's X.509 Distinguished Name).