UnbluFilter
The UnbluFilter allows integration of the Unblu Secure Flow Manager (SFM) with the Nevis Security Suite. The filter acts as a wrapper of the SFM distributed with nevisProxy. The SFM can be configured to inject the Unblu JavaScript to the 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.
See as well http://www.unblu.com/en/docs/latest/
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: 5 | The UnbluFilter is compatible with the different versions of the Unblu server. With the UnbluCompatMode, it is possible to select the feature set of the filter matching the Unblu server in use: - 1 (default): this will still use the original implementation of theUnbluFilter.It is 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 (includes Unblu cluster support). |
| 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; optional if UnbluCompatMode >=5, ignored for all other UnbluCompatMode values; default: MZsy5sFESYqU7MawXZgR_w | 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. The path specified in UnbluPath has to start with a / (forward slash). 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 the UnbluFilter from within nevisProxy. The path should not be reachable by the client, it does not need to be proxied. The path specified in UnbluSystemPath has to start with a / (forward slash). 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, an appropriate mapping must be configured. The URL specified in UnbluURL has to start either with http:// or with https://. In the usual configuration, it is 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 | Deprecated The parameters BaseUrlHeader and BaseUrlPattern are deprecated. Use the parameter OriginalUrlPrefix instead. For more information, see the deprecation warning below this table. 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 | Deprecated The parameters BaseUrlHeader and BaseUrlPattern are deprecated. Use the parameter OriginalUrlPrefix instead. For more information, see the deprecation warning below this table. 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 are 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.