Contact usRequest a demo

Entry paths

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.

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:

  • PUBLIC

  • WEBHOOK

  • INTERNAL

  • SYSTEM

Entry paths

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:

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.

Combining levels of trust and entry paths

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.

  • A PUBLIC resource can be accessed by a request using the PUBLIC, INTERNAL or SYSTEM path prefix.

  • An INTERNAL resource can only be accessed by a request using the INTERNAL or SYSTEM path prefix but not the PUBLIC path prefix.

  • A SYSTEM resource can only be accessed by a request using the SYSTEM path prefix but not the PUBLIC or INTERNAL path prefix.

Example

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:

    <script src="https://unblu.example.com/unblu/visitor.js"></script>

    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 PUBLIC entry path with the path prefix /unblu/.

  • When an agent at your organization wants to navigate to their Unblu Agent Desk inbox, they point their browser to a URL such as

    https://unblu.example.com/app/desk/#/inbox

    Access to the Agent Desk requires the INTERNAL level of trust. The URL of the request therefore uses the INTERNAL entry path with the path prefix /app.

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.

Using entry paths to restrict access

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 PUBLIC path prefix /unblu.

  • Requests from within your company network will only be passed to the Unblu server if they have the INTERNAL path prefix /app.

  • 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 SYSTEM path prefix /system.

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:

Entry path
Figure 1. Entry path

The SYSTEM entry path

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 true. Once 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).

The WEBHOOK entry path

The 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 true.

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 WEBHOOK entry path. Request that don’t originate from one of the specified IP ranges are rejected. If you don’t specify a range, the WEBHOOK entry 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.