UnbluFilter
The UnbluFilter allows integration of the Unblu Co-Browsing solution with the Nevis Security Suite. The filter acts as a wrapper of the filter library by Unblu distributed with nevisProxy. The filter adds co-browsing-specific code to HTML content sent to the client. It also forwards selected resources from the responses to a co-browsing server as necessary. An Unblu Co-browsing server must be configured for this to work.
A typical configuration is to map the UnbluFilter, the application backend and the Unblu server behind an IdentityCreationFilter. The UnbluFilter and the application backend are mapped to the application URL. The Unblu server is usually mapped to '/unblu'.
Classname
ch::nevis::isiweb4::thirdparty::cobrowsing::unblu::UnbluFilter
Library
libUnbluFilter.so.1
Configuration
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| UnbluCompatMode | integer; optional; default: -1 | Several changes have been made to the UnbluFilter so it is compatible with newer versions of the Unblu server. With the UnbluCompatMode you configure what Unblu-server and UnbluFilter version to use.-1 (default): this will still use the original implementation of theUnbluFilter.It has been set as default so that existing instances using theUnbluFilterwill still work correctly. 4: Set it to 4 if the Unblu server has version 4 or lower. On existing instances, you can set it to 4 if no BaseUrlHeader or BaseUrlPattern is configured. * 5: set it to 5 if the Unblu server has version 5 or higher. |
| UnbluConfigMode | LOCAL or REMOTE; optional default: LOCAL | For UnbluCompatMode > 0 only: - LOCAL: it will be taken from the file configured as 'UnbluConfigFile' - REMOTE: it will download it from the Unblu server behind the UploadServlet |
| UnbluRemoteConfigUrl | string; optional; default: <UnbluSystemPath>/<UnbluServerInterfacePath> | Only valid if UnbluConfigMode is set to REMOTE: the URL where to get the config from. |
| UnbluFilterLibFile | string; optional; default: /var/opt/nevisproxy/<instance_name>/work/WEBINF/lib/libunblufilter.so | Path to the external Unblu filter library. Only needed for UnbluCompatMode==-1. For all other UnbluCompatMode it will be ignored |
| UnbluDefaultCharset | string; optional; default: iso-8859-1 | For UnbluCompatMode > 0 only. Charset to be used by default. |
| UnbluApiKey | string; mandatory if UnbluCompatMode >=5, ignored for all other UnbluCompatMode | The api key for the Unblu server. |
| UnbluConfigFile | string; optional; default: /var/opt/nevisproxy/<instance_name>/conf/unblu.conf | Name of the JSON configuration file for the Unblu filter library. A sample unblu.conf is provided, you may need to customize it for particular applications. |
| UploadServlet | string; required | This is the name of the Http(s)ConnectorServlet used for uploading resources on the Unblu server. |
| UnbluPath | string; required; default: /unblu | The path prefix for Unblu server requests. The configured path on the co-browsing server needs to be reachable by the client. In a typical setup, it should be proxied appropriately. This setting must correspond to com.unblu.identifier.publicPathPrefixPattern on the co-browsing server. |
| UnbluSystemPath | string; optional; default: /sys-unblu | The path prefix for resource uploads on the Unblu server. Resources are only uploaded by UnbluFilter from within nevisProxy. The path should not be reachable by the client, it does not need to be proxied. This setting must correspond to com.unblu.identifier.systemPath-PrefixPattern on the co-browsing server. |
| UnbluServerInterfacePath | string; optional, advanced; default: rest/filterBackend | The path to the interface of the Unblu server where resources are uploaded. This setting complements unbluSystemPath and the configuration of the servlet referred to by UploadServlet. |
| UnbluURL | string; required | URL of the Unblu server as seen by the client. In a typical setup, the co-browsing server is behind a nevisProxy instance. The unbluURL should therefore point to the proxy and an appropriate mapping must be configured. In the usual configuration its the URL to the root of the Unblu server: https://<unblu-server host name>:<port>/ |
| MaxUploadSize | integer; optional; default: 512K | Maximal length (in bytes) of HTTP responses that are uploaded as resources on the Unblu server. |
| MaxInjectionSize | integer; optional; default: 512K | Maximal length (in bytes) of a buffer used when injecting co-browsing code in HTML responses. |
| PropagateUserIdToUploadServlet | string; optional; default: not configured | Name of the HTTP header containing user.auth.UserId to send in uploads via UploadServlet. |
| OriginalUrlPrefix | string; optional, advanced; default: not configured | Configures the base URL that is sent to the UploadServlet instead of the hostname received in the Host header. Accepts conditions and parameters for normalization |
| BaseUrlHeader | string; optional, advanced; default: not configured | Configures the name of a HTTP header the base URL for UploadServlet should be extracted from. If present, this value takes precedence over OriginalUrlPrefix.Only supported for UnbluCompatMode==-1. For all UnbluCompatMode the parameter OriginalUrlPrefix should be used instead. |
| BaseUrlPattern | string; optional, advanced; default: not configured | A regular expression for validating BaseUrlHeader. This parameter should be configured whenever the BaseUrlHeader is defined. A header value that does not match the pattern is ignored. Original-UrlPrefix is used if configured. Otherwise, the Host header is used. Only supported for UnbluCompatMode==-1. For all UnbluCompatMode the parameter OriginalUrlPrefix should be used instead. |
Deprecated
The parameters BaseUrlHeader and BaseUrlPattern are only evaluated for UnbluCompatMode==-1 and will be soon deprecated.
For all UnbluCompatMode, use the parameter OriginalUrlPrefix instead.
See also the following sample configuration:
<init-param>
<param-name>BaseUrlHeader</param-name>
<param-value>TheBaseUrlHeader</param-value>
</init-param>
<init-param>
<param-name>BaseUrlPattern</param-name>
<param-value>.*</param-value>
</init-param>
can be rewritten to:
<init-param>
<param-name>OriginalUrlPrefix</param-name>
<param-value>
Condition:HEADER:TheBaseUrlHeader:.*
HEADER:TheBaseUrlHeader
</param-value>
</init-param>
UnbluFilter example
For a sample filter configuration, check the UnbluFilter.example file in the examples directory.