Contact usRequest a demo

Reverse proxy and web application firewall (WAF) configuration hints

If your Unblu installation is behind a reverse proxy or web application firewall (WAF), you may have to make some changes to the latter’s configuration to ensure that Unblu is fully functional.

  • Requests from Unblu clients such as the Agent Desk, the Unblu visitor UI, or the Unblu mobile SDKs must be forwarded to the Unblu server:

    • If you are running Unblu in a cross-origin installation, make sure that the domain or subdomain that Unblu is running on is accessible.

    • If your Unblu installation is a site-embedded deployment, create a URI mapping to the Unblu entry path for the PUBLIC entry path.

  • If a business (as opposed to a purely technical) exception occurs during an HTTP request, Unblu sends the error response code 400 Bad Request or the error code specified in com.unblu.nio.error4xxcode and com.unblu.rest.error4xxcode.

    If the request results in the error code 404 Not Found or 410 Gone, you must also pass these error codes to Unblu clients unchanged. These error codes mustn’t be replaced by or redirected to an error page, or Unblu won’t work correctly.

    As a rule, you should pass all responses from the Unblu server to the Unblu client unchanged, but you can replace error codes except for the ones mentioned above.

  • The request and response headers on the list of required HTTP headers must all be passed through unchanged.

  • The protocol used by clients to access Unblu can influence the server’s behavior. You should therefore add x-forwarded-proto and x-forwarded-host headers to the request headers forwarded to the Unblu Server.

  • Ensure that the x-unblu-device cookie is passed through and not stored in a cookie store (if your WAF has one).

  • If your installation uses CORS, allow the HTTP OPTIONS method. The method is required for CORS preflight requests.

    This is only necessary if your WAF is in front of Unblu (as opposed to the website being instrumented with Unblu).

  • If you want to use WebSockets, your WAF must support them. It must also allow the following headers to reach Unblu:

    • Sec-WebSocket-Extension

    • Sec-WebSocket-Key

    • Sec-WebSocket-Version

    • Upgrade

  • By default, WebSockets are enabled in Unblu. If you don’t want to use them, set com.unblu.nio.useWebSocket to false.

  • If WebSockets don’t work, Unblu automatically falls back to Comet. Conversely, if Comet doesn’t work, Unblu tries to connect with WebSockets. The configuration property com.unblu.nio.maxAttemptsToFallbackToComet specifies how many attempts Unblu makes to establish a WebSocket connection before falling back to Comet.