The key security issue in any on-premises Unblu installation is the fact that the system spans both the public internet and your organization’s private network:
The public part of the Unblu installation is the visitor interface that appears on your company’s website. Because the interface is part of your website, it’s transmitted to the visitor’s browser and transmits information from the visitor’s browser back to the Unblu server.
Within your organization’s network perimeter, on the other hand, you have the actual Unblu server itself, as well as the agents that interact with the visitors. Because the agents are trusted employees of your firm, they have access to your internal network, through which they access the agent interface with their browsers.
To maintain the separation between these realms, Unblu is designed to leverage your existing secure infrastructure as much as possible. It does so by associating different entry paths with different levels of trust.
Every resource in Unblu is assigned a minimum level of trust required to access it. There are three trust levels, each of which is associated with a different entry path.
From least to most trusted, the levels of trust are:
Requests for a resource on the Unblu server must have a way of demonstrating that they’re entitled to access the resource. In other words, a request must be able to signal to the Unblu server which of level of trust it should be assigned.
To do so, Unblu associates the path prefix of each request’s URL with a certain level of trust. This is referred to as the request’s entry path.
The entry paths associated with the different trust levels are specified in the following configuration properties:
com.unblu.identifier.publicPathPrefix for the
PUBLICpath prefix. The default value is
com.unblu.identifier.internalPathPrefix for the
INTERNALpath prefix. The default value is
com.unblu.identifier.systemPathPrefix for the
SYSTEMpath prefix. The default value is
com.unblu.identifier.webhookPathPrefix for the
WEBHOOKpath prefix. The default value is
The path prefixes must be different. If two or more path prefixes are the same, you can’t launch the Unblu server.
You should also ensure that path prefixes don’t overlap, for example by setting one prefix to
/foo and another to
/foobar. If they do it may result in unexpected behavior.
For a request to succeed against a resource, the request itself must have at least the same trust level as the resource it’s requesting.
PUBLICresource can be accessed by a request using the
INTERNALresource can only be accessed by a request using the
SYSTEMpath prefix but not the
SYSTEMresource can only be accessed by a request using the
SYSTEMpath prefix but not the
Contrast the following two scenarios:
When you integrate the Unblu visitor UI into your public website, a
<script>element similar to the one below will be embedded in your website’s code:
This HTML element loads the bootstrap code that, in turn, loads the Unblu visitor UI. Since this resource is intended for use in the public internet, the level of trust required to access it is
PUBLIC, so the request for it can use the
PUBLICentry path with the path prefix
When an agent at your organization wants to navigate to their Unblu Agent Desk inbox, they point their browser to a URL such as
Access to the Agent Desk requires the
INTERNALlevel of trust. The URL of the request therefore uses the
INTERNALentry path with the path prefix
This pattern of determining the trust level required to fulfil a request based on the path prefix encoded in the request URL is used for all requests sent to the Unblu server.
The ability to determine the level of trust required to complete an HTTP request doesn’t provide security in and of itself. Rather, it enables you to provide security for the Unblu server in the wider context of your company network.
The path prefix used for each entry path is associated with a single level of trust. This neatly partitions the URL space used by the Unblu server along the lines of the levels of trust.
You can make use of this partitioning to restrict access to Unblu’s resources. The Unblu server should be set up behind a reverse proxy that enforces the following rules:
Requests that originate outside your company network will only be passed to the Unblu server if they have the
Requests from within your company network will only be passed to the Unblu server if they have the
If a request is made by other components closely connected to the Unblu server, it will only be passed to the Unblu server if it has the
Since any organization installing Unblu on-premises will almost certainly already have some type of reverse proxy in place, Unblu’s entry path concept can take advantage of your existing security infrastructure.
The diagram below depicts the key elements related to the entry path concept and authentication in a typical on-premises installation:
By default, the
SYSTEM entry path is disabled. However, the SecureFlow Manager and the Rendering Service needed for universal, document co-browsing, and screen sharing both require that it be enabled.
If you need or want to enable the
SYSTEM entry path, set the configuration property com.unblu.systementrypath.enabled to
SYSTEM is enabled, you must restrict access to the
SYSTEM entry path. This can be done by enabling basic authentication configuration properties and com.unblu.systementrypath.basicHTTPAuthenticationPassword, or by implementing protection outside of Unblu (for example in a reverse proxy).
WEBHOOK entry path is intended for webhooks Unblu receives from external call service providers such as LiveKit, Vonage, or MS Teams. By default, it’s disabled. To enable it, set com.unblu.webhookentrypath.enabled to
If you have account ingress enabled and enable the
WEBHOOK entry path, you must also specify:
The allowed origin for requests sent to the path. The origin consists of the base URL, scheme, and authority. Provide the origin in the configuration property com.unblu.ingress.webhook.origin.
The IP address ranges for calls to the
WEBHOOKentry path. Request that don’t originate from one of the specified IP ranges are rejected. If you don’t specify a range, the
WEBHOOKentry path isn’t accessible.
Provide the IP ranges in the configuration property com.unblu.ingress.webhook.allowedIpRanges. For information about the supported formats, refer to the description of the configuration property in the reference.