Contact Center administrators must select an appropriate reverse-proxy. Any reverse-proxy that meets the following minimum requirements can be used:

• Supports HTTP2/TLS 1.2 and secure Websockets.

• Has proper logging mechanism for easy debugging of issues

• Supports multiple Unified CCX and Customer Collaboration Platform servers from a single reverse-proxy.

• Supports periodic revalidation of cached content. This is required because any updates or installations on the internal hosts don't require a manual intervention to clear the cached content of the proxy.

• Supports custom authentications or provides alternative mechanisms such as an enterprise login to prevent unauthenticated access of solution components.

  Note

  When you use Cisco-provided reverse-proxy configuration, the requests are authenticated at the proxy before they are forwarded to the upstream servers. When you are configuring a custom reverse-proxy, you must create this authentication layer if they have to be as secure as the Cisco provided configuration. You should consider this configuration step while planning to implement VPN-less access to Finesse using a custom reverse-proxy.

• Enables caching of static resources with support for cache-control header to reduce DoS/DDoS attack vectors and to scale the proxy. Any proxy that needs to support more than a few hundred users and does not provide response caching features should be deployed with a Content Delivery Network (CDN) with support for cache-control headers so that load and security guidelines are met.

  Note	CDN deployment is also recommended with caching proxies such as OpenResty Nginx to eliminate the impact of DDoS attacks.

• Supports X-Forwarded headers. These headers are used by the solution to decide how to handle a request.

Additional Requirements

Some desirable requirements in a reverse-proxy are as follows:

• Consider deploying proxies that are built on non-blocking IO-based technology instead of the traditional thread-per-request architecture, to scale better.

• Consider proxies that provide response substitution capabilities which allow workarounds for custom gadgets as custom gadgets may not work with reverse-proxy directly.

  Note	Finesse Desktop Chat over reverse-proxy requires response substitution capability.

• Support for port-based forwarding can be used to reduce the cost of deployment by avoiding the need for multiple externally resolvable hostnames, public DNS records, and corresponding certificates for each internal server that has to be accessed.

• Support for custom plugin/modules, which can be used to enhance the authentication model and provide a more robust security posture.

Install the host OS and reverse-proxy of your choice. Consider the following points while configuring the reverse-proxy:

• Configure SSL certificates as required.

• Refer to the specific proxy documentation and configure the proxy rules for each service with the same host and port that is configured in the mapping file.

• IdS and IdP trust should be configured before proxy mapping configuration is done. Otherwise, proxy configuration changes will not be processed by IdS.

• For IdS hosts, if proxy configuration is changed, the administrator must re-establish trust on IdP for new IdS proxy hosts after downloading new metadata file from IdS admin.

• For Finesse hosts, if proxy configuration is changed, the administrator must manually add or update the allowed Finesse client redirect URIs from IdS administration interface.

• Whenever SAML certificate is regenerated or IdP metadata is uploaded, proxy configurations are generated afresh.

To secure the reverse-proxy, refer to the Security Guidelines section in the Solution Design Guide for Cisco Unified Contact Center Express available at https://www.cisco.com/c/en/us/support/customer-collaboration/unified-contact-center-express/products-implementation-design-guides-list.html.

Contact Center administrators should analyze the hardware required for the reverse-proxy, based on the number of agents and supervisors who may access the Finesse desktop without connecting to VPN. You can use the reference request rates provided for Unified CCX and Customer Collaboration Platform in Reverse-Proxy Configuration.

The type of proxy selected guides the hardware to be used, depending on whether the proxy is shipped as an installable software or is a hardware-based application.

Sizing configurations are pre-tested for OpenResty Nginx proxy. Custom proxy deployments should consult their product documentation or run basic scaling tests to determine the rates that can be supported by the respective proxy and scale their hardware accordingly.

Determining the gadget compatibility is an important activity for planning a VPN-less Finesse deployment.

After deploying the reverse-proxy, all Cisco-provided gadgets (Unified CCX and Customer Collaboration Platform) work seamlessly with their respective servers of Release 12.5(1) SU2 or later. The Webex Experience Management and CCAI gadgets also work seamlessly with VPN-less Finesse deployments.

In some scenarios, depending on the gadget design, custom third-party gadgets require workarounds to enable them to work with the reverse-proxy deployment. Refer to the following sections to determine if any of your gadgets require workarounds.

Note

Gadgets that are loaded from servers other than Finesse server should use exclude-url feature in the gadget XML specification to load the Finesse resources such as Finesse.js. For more information, refer to the Use Gadget URI Exclude Feature to Refer to Finesse Resources section. If you use two different URLs, one internal and one external, in Enterprise Chat and Email (ECE), you must update the Finesse desktop layout to use only the external URL. If you use an internal-only ECE (for integrations that support only ECE email routing), you must change the ECE web server to ensure that the ECE services are accessible externally.

Gadget Types and VPN-less Compatibility

Finesse gadgets are classified into the following types based on how they are designed operationally:

• Gadgets that are self-contained within the desktop. These gadgets do not have to make any additional network requests, or are restricted to invoking Finesse APIs and APIs on the internet.

• Gadgets that provide their functionality by communicating with an accompanying server that is deployed in the DMZ and is reachable directly from the internet and LAN.

  Note	To enable the same desktop layout to be used by both LAN-based and internet-based clients, the server installed in a DMZ should also be reachable from servers such as Finesse in LAN, and from clients that are running within the LAN.

• Gadgets that need to communicate with an accompanying server deployed in LAN, but uses desktop-provided makeRequest API to communicate to the server. The makeRequest API routes all the requests through the Finesse server and does not directly reach the server that is deployed in the LAN.

  Note	These requests succeed in a reverse-proxy deployment only if the requests are made using the hostname and port. The hostname and the port must be reachable from LAN because the requests are executed by Finesse server which runs on LAN.

• Gadgets that have to communicate directly with any one of the following types of accompanying server:

  • Server deployed within the LAN and is not reachable directly from the internet.

  • Server that communicates with an additional port apart from the HTTP port used to load the gadget.

The last two types of gadgets have to be modified to be used in a reverse-proxy deployment. The steps required to enable these gadgets to be accessed from internet clients are as follows:

• Enable VPN-less access for custom gadgets

• Send hostname and port information to gadgets

• Use gadget's URI Exclude feature to refer to Finesse resources

Enable VPN-less Access for Custom Gadgets

Gadgets that communicate directly with accompanying servers that are deployed in LAN must handle the following aspects to work correctly in a reverse-proxy deployment:

• Use the right hostname and port for communicating with its accompanying server.

  A gadget can find the correct hostname and port corresponding to the server from which the gadget was loaded, by using the gadgets.util.getUrlParameters().up_urlPrefs API provided by the Finesse Javascript API.

  To find additional ports or hostnames that are required, data can be passed in as gadget preference such that the additional host and port information can be sent to the gadget. For more information, refer to the Send Hostname and Port Information to Gadgets section.

• Ensure that the communications are forwarded correctly by the reverse-proxy.

  After the gadget starts communicating with the correct host and port information, the hostname and port number have to be forwarded to the server deployed in the LAN. This can be done by opening the appropriate ports in the DMZ firewall. Also, ensure that the appropriate ports and rules are added to the reverse-proxy rules to forward the traffic to the correct server in the LAN.

• Best Practice: If requests to external servers are made using Finesse authentication headers, a common validation is enabled to authenticate the requests at the proxy. Gadgets that do not use Finesse authentication should plan to implement their own custom authentication schemes to ensure that the requests are validated at the proxy before sending to the Finesse server.

Send Hostname and Port Information to Gadgets

Gadgets that send host and port information corresponding to a server deployed within the LAN can use the UserPreferences feature supported by Finessse gadgets. This feature allows a configurable, named information to be passed to the gadget. The information can be referenced within the gadget XML or programmatically by using a Javascript.

For more information on how to use UserPreferences method, refer to https://developer.cisco.com/docs/finesse/#!gadget-preferences.

The UserPreferences that are created for this purpose should start with the keyword externalServerHostAndPort in its name. This enables Finesse to substitute the host and port that are provided with the corresponding entry from the proxyMap file. For example:

<UserPref name="externalServerHostAndPort_chat” display_name="Chat_externalServerHostAndPort" default_value="SMHostName:7443" datatype ="hidden"/>

Note	The default_value parameter is not case sensitive.

When accessed from the LAN, the UserPreferences continues to have the default value that is configured in the XML. However, when accessed through the reverse-proxy, the UserPreferences receives the value from the proxyMap file. For example:

SMHostName:7443=external-proxy-host:4043

When accessed through the reverse-proxy, the gadget receives the port 4043 and host name as external-proxy-host.

Use Gadget URI Exclude Feature to Refer to Finesse Resources

Add the following content within the ModulePrefs tag of the gadget XML to ensure that the resources that are loaded from Finesse server are excluded from concatenation. This step is mandatory for gadgets that load their XML from custom servers.

<Optional feature="content-rewrite">
<!-- these files will be directly served by Finesse, not through shindig -->
<Param name="exclude-url">finesse.min.js</Param></Optional>

The following are the mandatory HTTP headers that reverse-proxy has to set along with the actual headers set by the client before forwarding the headers to the Finesse server.

The following are the standard headers manipulated by the proxy:

Agents and supervisors should bookmark two different pairs of URLs (publisher and subscriber) for accessing the Finesse desktop through both the Contact Center network and the reverse-proxy.