Show Hide

 

Feedback

  • Contents
 

Install and Configure SOAP ISAPI Listener

The components of SOAP follow the client/server model. Some components are installed when Interaction Designer is installed on the CIC Server. Other components are installed on IIS web servers and client PCs. This section explains how to install and configure SOAP Tools, SOAP Tracer, SOAP Listener, and Soap Notifier COM components.

  • SOAP Tools Installation: When Interaction Designer is installed (as part of the CIC Admin setup), new SOAP tools are added to Interaction Designer's tool palette. SOAP tools are implemented in a DLL (SOAPToolsIDA.DLL) that is installed with Interaction Designer. Appendix B in this document also contains a summary of each SOAP Tool.
  • SOAP Tracer Installation: The Soap Tracer Utility (SOAPTracerA.exe) is optionally installed if the "SOAP" option is selected during installation of Interaction Designer.
  • SOAP ISAPI Listener Installation: The Interaction Center SOAP Listener Install installs the SOAP Listener Task on an IIS server. The SOAP Listener task is an ISAPI DLL. Installation requires preplanning on your part to address security and configuration issues, and some post-installation work to customize the default SOAP filter configuration. The SOAP ISAPI DLL must be installed on a server running Microsoft Internet Information Server (IIS), version 5 or later.

Installation and configuration pre-planning

This section describes issues that SOAP implementers must resolve before installing ISAPI SOAP Listener on an IIS server. Security issues are particular important to consider if you plan to pass SOAP requests across the Internet.

  1. Select a server to host SOAP ISAPI Listener.

    The SOAP Listener task is an ISAPI DLL that you must install on a computer running Microsoft's Internet Information Server (IIS) service. SOAP Listener uses IIS (version 5 or later) solely for HTTP operations. It does not consume other IIS services. You can install this task on a dedicated IIS server, or on a CIC server that is running IIS. Before choosing a platform, you should carefully consider security, performance, and capacity issues.

    SOAP Listener will work if it is installed on a CIC server running IIS. Theoretically, this could improve performance by eliminating latency between CIC and a dedicated IIS server. In practice, performance could be degraded if the CIC server becomes too highly tasked, and this configuration could compromise network security. As a rule of thumb, do not install SOAP ISAPI Listener on a CIC server unless:

    Port 80 HTTP traffic is tightly controlled (e.g. SOAP will be used exclusively for interactions between servers inside a firewall). This is appropriate for some corporate Intranets. Use a different port than 80 (e.g. 8080) that is blocked by the firewall. SOAP requests will not be received from the Internet, or use another port. The CIC server has the capacity to run IIS without degrading performance.

    If SOAP requests will be received from the Internet, you should install SOAP ISAPI Listener on an IIS server in a DMZ (Demilitarized Zone) between two firewalls. This can be an existing CIC/web server or a dedicated web server.

  2. Open port 2633 on the firewall between the DMZ and the Intranet on which the CIC server is located, so that Notifier traffic can pass between the CIC server and the SOAP listener. Do not open port 2633 to the Internet.

    What is a Demilitarized Zone?
    In an Internet-connected world, any public access server, such as a web server that connects outside of an internal network is unprotected against hacking. A public access server can expose the rest of a network to potential intrusion.
    Demilitarized zones (DMZ) reduce security risks by using multiple firewalls to delimit an internal network from publicly connected devices, such as web servers. A DMZ configuration protects both public servers and the internal network. The first firewall isolates essential Internet services (web, email, DNS, etc). The second firewall protects the internal network.
    A DMZ is not the only solution that you might employ to protect your network. It is completely acceptable to use different security measures. The exact method is up to you—be reminded that if you connect a server to the outside world, you must manage the risk that your internal network might be penetrated through a public server.

  3. Apply service packs and hotfixes to IIS.

    Network security is a topic outside the scope of this paper. However, we strongly recommend that you keep server operating system and IIS software up-to-date. Apply Microsoft service packs and hot fixes regularly. Hackers frequently exploit known security holes that you can close by applying free software updates. You can automate this process to a limited extent. For example, Microsoft's HFNETCHK is an executable that runs on your server. It retrieves an XML file that contains information about security hot fixes that your system might need. Browse Microsoft's web site (http://www.microsoft.com/security) for security bulletins, upgrades and other information. As a rule of thumb, you should not install services that you do not need. Subscribe to "NTBugtraq" or a similar discussion list. This mailing list discusses security exploits and security bugs in Windows NT, Windows 2000, and Windows XP plus related applications. To sign up, visit http://www.ntbugtraq.com/.

  4. Decide how to configure SOAP Listener to prevent DoS Attacks

    Denial of Service (DoS) Attacks are attempts to flood a server with false requests for information, with the goal of overwhelming the system and ultimately crashing it. Not much can be done to prevent a denial of service attack. However, you can minimize the impact of DoS attacks by supplying the a couple of threshold values at installation time, and by customizing an ISAPI filter after installation is complete.

    Default Request Timeout

    Since DoS attacks can degrade performance of the CIC Server, ISAPI Listener can be configured (at installation time) to return a fault message (Server.RequestTimeout) if the CIC Server fails to respond within a specific time interval.

    Before installing SOAP Listener, decide what value to enter into the Default Request Timeout field. This value sets the maximum amount of time in milliseconds that ISAPI Listener will wait for the CIC Server to respond to a SOAP request. When this interval is exceeded, ISAPI Listener sends a fault message to the requester. The default is 60,000 milliseconds (1 minute). If your IIS server has a fast processor, and is dedicated to IIS, you may be able to reduce the default value.

    This value sets the default timeout for all SOAPActions. Following installation, you can assign timeout values to specific SOAPActions, by editing a configuration file. For details, see Step 2: Set SOAPAction-Specific Timeout Values in the Post-Installation Procedures section of this document.

    Maximum SOAP Payload Size

    SOAP ISAPI Listener uses a threshold setting named Maximum SOAP Payload Size to limit the size of incoming SOAP messages. By default, the maximum SOAP payload Size is 128 KB. Larger messages are not forwarded by the Listener to the CIC Server for processing. Based upon the size of data passed to your handlers, you may be able to reduce this value significantly. This helps minimize the impact of denial of service (DoS) attacks.

    Maximum Pending Requests

    The Maximum Pending Requests threshold limits the maximum number of SOAP requests that the CIC server should process concurrently. It helps to think of this as the maximum number of pending responses that SOAP Listener will wait for at any given time, since SOAP Listener waits for a response to each request that it sends to CIC.

    If Listener finds itself waiting for more responses that are allowed, it stops sending additional inbound request messages to the CIC Server until the number of pending requests falls below the threshold. SOAP ISAPI Listener does not queue unprocessed requests. It fails unprocessed requests with a fault message (Server.TooBusy).

    Process Isolation Level

    There is one last setting that you must consider before installing SOAP ISAPI Listener, and that is the level of process isolation (Low or High) that you wish to assign to the ISAPI Listener DLL. Process isolation protects the main IIS process against application faults—in this case, against potential failure of the ISAPI Listener DLL .

    Process Isolation provides an additional layer of durability for your Web server. Low process isolation provides the best performance. High process isolation offers more protection against possible faults in the Listener application (unlikely). Low is the default.

Install SOAP Listener

If at this point, if you have IIS running with the latest service packs and hot fixes, behind an acceptable firewall configuration, and have formulated threshold values, you are ready to install SOAP Listener. This procedure explains how to run the SOAP Listener Setup to install, register, and configure the SOAP Listener task on an IIS server. The Soap Listener task is an ISAPI DLL that translates HTTP requests into notifications. It acts as a gatekeeper to prevent denial of service attacks. Complete this procedure at your dedicated IIS Server or CIC Server running IIS. Installation requires pre-planning on your part to address security and configuration issues. If you have not read the Installation and configuration pre-planning section, we strongly recommend that you do so before performing this procedure.

  1. Download the CIC 2018 R1 or later .iso file from the Genesys Product Information site at https://my.inin.com/products/Pages/Downloads.aspx.

  2. Copy the .iso file to a file server (non-CIC server) with a high bandwidth connection to the server(s) on which you will be running the CIC 2018 R1 or later installs.

  3. Mount the .iso file and share the contents to make them accessible to the server(s) on which you will be running the CIC 2018 R1 or later installs.

  4. Navigate to the \Installs\Off-ServerComponents directory on the file server.

  5. Copy the SOAP Listener .msi file, for example, SOAPListener_2018_R1.msi, to the server on which you plan to run this install and double-click to launch it.

    The welcome page appears.

  6. Press Next to proceed past the welcome screen. Then press Next a second time to accept installation of default features.

  7. Supply user name, domain password, and domain for a user account with administrative privileges on the CIC server. Then press Next.

  8. Type the name of the CIC server. Then press Next.

  9. Supply values as indicated below:

    Default Request Timeout (in seconds)

    Enter the number of seconds that the ISAPI Listener should wait for the CIC Server to respond (to a SOAP request) before timing out and returning a fault message. The default value is 0 seconds. Press Next to proceed.

    Maximum Pending Requests

    Specify the maximum number of SOAP requests that your CIC server should handle concurrently during peak periods. This helps protect your server from denial of service (DoS) attacks. When this value is exceeded, additional requests will be denied.

    Maximum SOAP Payload Size (in KB)

    Specify the maximum size (in kilobytes) of SOAP payloads sent by the SOAP Listener to the CIC Server. Larger XML payloads will not be forwarded, to minimize the risk of denial of service (DoS) attacks.

  10. Press Next to proceed. The next screen prompts for a location where log files will be stored. Accept the default path, or navigate to a different path. When you are finished, click Next.

  11. Click Install to begin installing files.

  12. Press Finish to exit Setup.

  13. Click Yes to restart.

  14. For the SOAP Listener machine to receive updates from the Interactive Update Provider on the CIC Server, you must run the Interactive Update Client install following the SOAP Listener install. The install will prompt for the Interactive Update Provider Server (CIC Server) name or IP address.

Post-installation procedures

Following installation of ISAPI SOAP Listener, you should complete additional security steps to defend against DoS Attack. Specifically, you should limit requests to known SOAPActions, and to assign timeout values to individual SOAPActions. You will modify the default ISAPI filter configuration file. The relative path to this file is ..\soaplistener\filter\I3SOAPISAPIConfig.xml. The SOAP ISAPI endpoint listener uses I3SOAPISAPIConfig.xml to filter incoming message requests. This file acts as a gatekeeper. It affects whether or not incoming messages are forwarded to the CIC Server by ISAPI Listener. Implementers are strongly encouraged to edit I3SOAPISAPIConfig.xml immediately after SOAP ISAPI Listener is installed, and whenever new handlers implement an additional SOAPAction.

The default configuration indiscriminately forwards all SOAP requests to the Interaction Center server identified in the ISAPI Listener install. You should modify the filter file to make the following modifications:

  1. Add <Rule> elements that identify the specific operations (SOAPActions) that your CIC server should process. Thereafter, SOAP ISAPI Listener will forward only those particular SOAPActions to the CIC server.

  2. Set timeout thresholds for specific SOAPActions used in your environment.

These modifications are particularly important if your SOAP Listener is exposed to the Internet. If you leave the default filter unchanged, your CIC server is more venerable to DoS attacks. Before we discuss the modification procedure steps in detail, it is necessary to introduce the format of the configuration file.

I3SOAPISAPIConfig.xml Filter File Format

The ISAPI filter is just an XML file whose structure can be described as follows. Its root element, <FilterConfig> has three child elements, <ICServers>, <Defaults> and <Rules>.

<ICServers>

The <ICServers> element contains a list of Interaction Center Servers to which to route the messages. <ICServers> can have <ICServer> and <ICServer2> child elements.

<ICServer2> Uses a remote subsystem connection. GenSSLCerts must be run prior to attempting to connect to a notifier with this type of connection. In a switchover situation, use <ICServer>.

To get SOAP LIstener to work in this environment, use <ICServer2>, which can specify multiple hostnames separated by space characters. When establishing a connection, SOAP Listener will try each server in succession until it finds one that it can connect to that is not in backup mode.

The attributes of the <ICServer> child element are:

name

The name of the CIC server, used to identify the server in filter rules.

host

Hostname or IP address of the Notifier (CIC) server.

username

Login name for the Notifier connection.

password

Password for the Notifier session.

The attributes of the <ICServer2> child element are:

name

Name of the server (used to identify it in rule action).

host

Hostname or IP address of the Notifier server. You can specify multiple hostnames separated by space characters. When establishing a connection, SOAP Listener will try each server in succession until it finds one that it can connect to that is not in backup mode.

<Defaults>

The <Defaults> element stipulates default rule actions. It has two child elements. <ForwardRequest> identifies requests that will be forwarded. <HTTPResponse> identifies requests to be rejected.

The attributes of the <ForwardRequest> child element are:

server

Name of the Interaction Center Server configured through the corresponding <ICServer> tag. This attribute is (case-sensitively) matched against the name attributes of the <ICServer> tags.

initiatorEvent

Name of the InitiatorEvent (notification event) as which the request should be forwarded to the Interaction Center server. If not explicitly specified or an empty string, the soapAction from the HTTP header will be used.

soapAction

SOAPAction string to be forwarded to IP. If not defined or "*", use same action that matched the rule.

clientName

Client name value specified in the request notification. Default = "I3SOAPISAPI". This is mainly informational for use as a trace message.

requestTimeout

Timeout value used for the request. Default as specified by ‘DefaultRequestTimeout' registry key. Time in milliseconds

includeTransportInfo

Specifies whether to include the TransportInfo data in the request sent to IP. Possible values: "1", "0", "true", "false". Default = "1".

The attributes of the <HTTPResponse> child element are:

statusCode

HTTP status code. Default = "500".

statusText

HTTP status text. Default = lookup based on statusCode (for "500": "Internal Server Error").

soapFaultcode

Value of the <faultcode> element in the <Fault> element of the response sent back to the client. Default = "Server.SOAPAction".

soapFaultstring

Value of the <faultstring> element in the <Fault> element of the response sent back to the client.. Default = "The SOAPAction is not recognized by the server!"

<Rules>

The <Rules> element contain <Rule> child elements which define the action to be performed when the rule fires. That happens when the request's SOAPAction matches the rule's soapAction attribute. The <Rule>child element has only one attribute:

soapAction

SOAPAction that triggers this rule. SOAPAction matching is case-sensitive.

Sample I3SOAPISAPIConfig File

This sample filter listed below shows how the elements fit together. The numbers are for illustration purposes and do not appear in an actual configuration file. See SOAP ISAPI Filter Schema for the schema used by I3SOAPISAPIConfig.xml.

 1  <FilterConfig xmlns="urn:schemas-inin-com:soapisapi-filter-config">
 2    <ICServers>
 3       <ICServer name="localhost"
 4          host="localhost"
 5          userName=""
 6          password=""/>
 7       <ICServer name="mars"
 8          host="mars"
 9          userName="eic_admin"
 10         password="i3"/>
 11   </ICServers>
 12   <Defaults>
 13      <ForwardRequest server="localhost"
 14         clientName="I3SOAPISAPI"
 15         requestTimeout="20000"
 16         includeTransportInfo="1"/>
 17         <HTTPResponse statusCode="500"
 18            statusText="Internal Server Error"
 19            soapFaultcode="Client.SOAPAction"
 20            soapFaultstring="The specified method is not supported!"/>
 21    </Defaults>
 22   <Rules>
 23      <Rule soapAction="uri:my-calculator#Add">
 24         <ForwardRequest initatorEvent="uri:my-calculator"/>
 25      </Rule>
 26      <Rule soapAction="uri:my-calculator#Subtract">
 27         <ForwardRequest initatorEvent="uri:my-calculator"/>
 28       </Rule>
 29      <Rule soapAction="uri:my-calculator#Multiply">
 30         <ForwardRequest initatorEvent="uri:my-calculator"/>
 31      </Rule>
 32      <Rule soapAction="uri:my-calculator#Divide">
 33         <ForwardRequest initatorEvent="uri:my-calculator"/>
 34      </Rule>
 35      <Rule soapAction="uri:test#foo">
 36         <ForwardRequest server="mars"
 37            soapAction="uri:test#bar"
 38            requestTimeout="120000"/>
 39      </Rule>
 40      <Rule>
 41         <HTTPResponse/>
 42      </Rule>
 43   </Rules>
 44 </FilterConfig>

This sample specifies several SOAPActions that refer to a calculator service. On line 23, the SOAPActions of the calculator are forwarded with the "uri:my-calculator" InitiatorEvent, so all requests trigger the same initiator. All other attributes of that rule are inherited from the default <ForwardRequest> element (line 13). Accordingly, requests for my-calculator are sent to the "localhost" server, even though that was not explicitly defined in the rule. It is easy to specify attributes in a Rule element that override default elements. In line 35, the SOAPAction "uri:test#foo" is forwarded as "uri:test#bar" (both the SOAPAction and InitiatorEvent) to the server "mars". The request timeout for this particular request is set to 2 minutes (120,000 milliseconds).

The last rule simply rejects all other SOAPActions with the default <HTTPResponse> rule action. To forward all SOAPActions indiscriminately, the following rule could be used:

<Rule>
  <ForwardRequest/>
</Rule>

Wildcard Pattern Matching
Currently, we do not support regular expression patterns as the soapAction attribute of a rule, although that may be added in a future release. However, to simplify filters for objects with many methods, a simple wildcard pattern is supported: The soapAction value may end with an asterisk (*), which means that the SOAPAction many be followed by one or more characters, that are ignored in the match. The * wildcard is supported only if it is the last character in a soapAction attribute. For example, this technique could be used to replace all rules for the calculator with a single one, where soapAction attribute has a value of " uri:my-calculator#*". Implement wildcards with care, or not at all, since this opens the possibility for DoS attacks on the Notifier event-ID caches. We thus strongly suggest explicitly adding rules for each SOAPAction that is to be forwarded to the server.

Forward only supported SOAPActions to CIC

  1. Customize the ISAPI filter file to prevent the SOAP Listener task from indiscriminately forwarding all SOAP requests to the Interaction Center Server. Filtering ensures that the CIC Server receives only those requests that match supported SOAPActions.

  2. Set SOAPAction Timeout Values. You can optionally modify this file to assign SOAPAction-specific timeout values, by adding requestTimeout attributes to ForwardRequest elements. The example below shows how to set the timeout value for a SOAPAction named "bar" to 120 seconds.

    <ForwardRequest server="mars" …identifies the CIC server

    soapAction="uri:test#bar" …identifies which SOAPAction

    requestTimeout="120000"/> …action-specific timeout value in milliseconds

  3. Unload the SOAP ISAPI DLL. To put a modified filter configuration into effect, you must unload the ISAPI DLL. The DLL will reload automatically the next time that a SOAP request is received.

    1. From the desktop of your IIS server, press the Start button. Select Settings, then Control Panel.

    2. Double-click the Administrative Tools folder to open it.

    3. Double-click the icon titled Internet Services Manager.

    4. Right-click the name of your virtual directory. Then select Properties.

    5. Select the Virtual Directory tab. Then press the Unload button.

    6. Press OK to close the active dialog.

    7. Close the Internet Services Manager window. Changes made to the SOAP filter configuration will take effect the next time that a request is received.