Certain deployments of ICWS may require the ICWS API to be exposed through a gateway or reverse proxy, either as a way of shielding the Interaction Center server from the outside world for security purposes or as a requirement of ICWS-powered web applications. This document discusses the technical details of such deployments, which can easily be applied to a wide variety of proxy technologies.
ICWS-powered web applications rely on a very specific URL scheme for communicating with Interaction Center servers through a reverse proxy. A specific scheme is required because the applications may be used to access several different backend Interaction Center servers. Other ICWS client applications are encouraged to adopt a similar scheme for consistency.
These web applications expect to communicate with an Interaction Center server by adding /api/ to their base URLs, followed by the hostname (or internal IP address) of the Interaction Center server they wish to communicate with. The hostname/address value used will match the value configured in Interaction Administrator for that server.
For example, a web application whose root web page is hosted at:
/apps/client/index.html
will attempt to connect to Interaction Center server icserver1 at the following path:
/apps/client/api/icserver1/icws/connection
This means that any requests to /apps/client/api/icserver1 or any subpath should be routed to the Interaction Center server whose hostname is icserver1.
It is not recommended that reverse proxies be configured to proxy requests to arbitrary hosts based on the value of the hostname URL segment because of the risk of malicious traffic targeting an internal machine. Rather, a "whitelist" approach of mapping request paths to specific internal hostnames is preferred, so that the proxy is only allowed to connect to the right internal servers.
Proxying HTTP requests from an ICWS client application to the corresponding Interaction Center server or Interaction Center Session Manager endpoint involves very little request modification by a reverse proxy. The request body and HTTP headers should remain unmodified. The only part of the request that requires modification is the request path, which must have any leading path segments (occurring before the standard /icws/ path segment) removed.
In order for ICWS to format and return URLs that are usable when a reverse proxy is in place, the reverse proxy must provide the original request URL to ICWS when proxying the request. This is provided by the ININ-ICWS-Original-URL request header. If multiple layers of reverse proxies are in use, only the proxy closest to the client application should specify this header, and subsequent proxies must not modify or override its value.
For example, an ICWS client application communicating directly with the Interaction Center server may send a request with a path similar to this:
GET https://icserver1:8019/icws/8675309/configuration/users HTTP/1.1
This request path needs no modification.
However, if the ICWS client application is communicating through a reverse proxy that exposes the Interaction Center server at a non-root-level path, such as /us/icserver1/, the request path coming from the ICWS client application may look like this:
GET https://proxy/us/icserver1/icws/8675309/configuration/users HTTP/1.1
In this case, the web proxy needs to both forward the request to the corresponding Interaction Center server and rewrite the request path back to the path expected by the internal ICWS server. The ININ-ICWS-Original-URL request header is included so ICWS can return URLs that are usable with the reverse proxy:
GET https://icserver1:8019/icws/8675309/configuration/users HTTP/1.1 ININ-ICWS-Original-URL: https://proxy/us/icserver1/icws/8675309/configuration/users
IIS 7.5 does not support the HTTP Range Header correctly, which will cause issues for APIs that use it for parameterizing requests. Use one of the following as a workaround:
ICWS uses HTTP cookies as a secondary means of client application identity verification. Cookies are set via the Set-Cookie HTTP response header, which directs the ICWS client application to store a cookie value for a specific API path. For ICWS client applications communicating directly with an Interaction Center server, such a Set-Cookie value may look something like this:
Set-Cookie: secret_8675309=45f5a7b0-987c-11e2-9e96-0800200c9a66; HttpOnly; Secure; Path=/icws/8675309
This header needs no modification.
However, if the ICWS client application is communicating through a reverse proxy, the same value will be included for the Set-Cookie header. In this case, the path of the cookie needs to be modified to match the path that the ICWS client application is using to connect the Interaction Center server.
If we use our example above of a web proxy that adds /us/icserver1/ to the beginning of the API URL, the above Set-Cookie would need to be changed to the following:
Set-Cookie: secret_8675309=45f5a7b0-987c-11e2-9e96-0800200c9a66; HttpOnly; Secure; Path=/us/icserver1/icws/8675309
A CIC Web Applications install guide can be found at http://help.inin.com/cic/mergedProjects/wh_tr/desktop/CIC_Web_Applications.htm, and has basic setup procedures for Apache, Internet Information Services (IIS), and NGINX; however, in order for server-sent events to function properly with a reverse proxy, it is necessary to ensure that the reverse proxy is setup in a way that does not buffer responses. Specifically speaking:
For IIS-based reverse proxies (version 7+), it will be necessary to ensure that the Response buffer threshold setting of the Application Request Routing Cache module is set to 0. To do this, select the IIS server in the IIS Management Console. Double-click the Application Request Routing Cache module. On the right side panel, click "Server Proxy Settings...". In that dialog, change the Response buffer threshold (KB) setting under the Buffer Setting section to 0. When done, click Apply.
For NGINX-based reverse proxies, it will be necessary to ensure that the proxy_buffering setting is set to off, and the proxy_http_version setting is set to 1.1 in the "/conf/nging.conf" file, within the server object.