|Manuals

Configuring Thinfinity Gateway

This article presents the steps to configure the Thinfinity Gateway.

The number of Thinfinity Workspace gateways in a deployment depends on its size. For small and mid-sized installations, a single Gateway (optionally in a load-balanced pair for high availability) handles everything — it serves the portal, authenticates users, routes new connections to the Brokers, and carries the session data plane (WebSocket, file transfers, PDF viewer, virtual channels).

At around 1,000 concurrent users — or in topologies where sessions must reach segments a single gateway cannot — a second role is introduced. One or more Communications Gateways take over the session data plane on dedicated, directly-reachable addresses, while the gateway that continues to serve the portal and web resources is referred to as the Primary Gateway. Both roles use the same binary and the same Thinfinity Configuration Manager tabs; the Set Up as a Communications Gateway step below is where an individual Gateway instance is marked as a Communications Gateway rather than left as a Primary Gateway.

Reference

For the detailed description of each role — including the three jobs a Communications Gateway performs (network topology, load distribution, and latency/geography-based routing) — see the Gateway article in the Thinfinity Workspace Components chapter.

1

Set Thinfinity Workspace Role as Gateway

Launch the Thinfinity Configuration Manager, navigate to the Services tab, select Gateway from the role dropdown, and select Apply.

2

Configure Network Bindings

In the General tab, locate the Bindings section and select Add.

Configure the binding as follows:

  • Select the desired protocol and port number, following best practices (HTTPS is strongly recommended).
  • Set Bind to IP to the address Thinfinity Workspace should listen on.
  • Set Host name to the host name (FQDN) used to reach the Gateway. For an HTTPS binding, this must be a host name the selected certificate is valid for.
  • If HTTPS is selected, a valid certificate must be configured.

Optionally, you may also configure:

  • Require Client Certificate: Indicates whether the server requires a valid SSL/TLS certificate from the client’s browser or device to establish a connection. If enabled, users without a trusted certificate will be denied access at the handshake level.
  • Require AD Mapping: Determines if Thinfinity Workspace should attempt to automatically map the provided client certificate to a specific user account in Active Directory. This allows for Certificate-based Authentication where the user is logged in based on their certificate identity rather than a password.
  • Store: Specifies the local Windows Certificate Store (e.g., MY or ROOT) on the Thinfinity Workspace server used to validate the chain of trust for incoming client certificates.
Note

This does not refer to the location of the certificates on the user’s remote device.

Reference

For additional info, see Client Certificate Authentication with AD Mapping.

Select OK, then Apply to commit the changes.

3

Copy or Edit the Network ID

Still in the General tab, select Network ID and copy or modify the value as needed.

This Network ID is required later to register Brokers, agents, AD Cache, and any other Thinfinity nodes within the Thinfinity Workspace network.

Warning

When configuring a Communications Gateway, its Network ID must exactly match the Network ID configured on the primary Gateway. A Communications Gateway with a different Network ID silently refuses Broker and Agent registrations — the gateway log records an Invalid network ID warning, and sessions fail to reach it with no visible error at the client.

4

Set Up as a Communications Gateway

Skip this step for small and mid-sized deployments.

A Primary Gateway is the default — if you only need the one gateway from step 1, no further configuration is required here. Work through this step only when this instance will act as a Communications Gateway: typically in deployments at around 1,000 concurrent users and above, or in topologies that require session reach into segments the Primary Gateway cannot cover (see the overview above).

Switch to the Gateway tab. It appears in the Configuration Manager once the role is set to Gateway (see Gateway Tab) and holds the two settings that mark this instance as a Communications Gateway:

  • Under Primary gateways, select Add and enter the URL of each Primary Gateway this communications gateway must reach (typically one URL for a small deployment, more when the Primary Gateways are load-balanced). Use Remove to drop an entry.
Order of operations with ACME certificates

If this gateway’s TLS certificate is issued via ACME (for example, Let’s Encrypt) from the gateway itself, obtain the certificate before enabling the This is a communications gateway toggle below. Once the toggle is on, the gateway stops responding to the ACME HTTP-01 challenge and the issuance request will fail. The same ordering applies when editing settings.ini directly.

  • Enable This is a communications gateway to run this instance as a communications gateway (see the overview above); leave the checkbox off for a primary gateway.
Info

In a standard deployment, both Primary gateways and the This is a communications gateway toggle are set at install time from a JSON install parameter (see JSON Parameters Reference). This tab is exposed for inspection and for post-install topology changes.

Reference

For the concept and its interaction with the Broker’s [Broker] DefaultCommGatewayURL / CommGatewayURL_N keys, see Communications Gateway and Registering Communications Gateway URLs.

Alternative: configuring via settings.ini

Both settings are also available as keys in settings.ini, located at:

C:\ProgramData\Cybele Software\Thinfinity\Workspace\DB\settings.ini

Open it with a text editor running as administrator, add the Primary Gateway URLs to the [Broker] section, and add a [Gateway.Lockdown] section with IsCommGateway=true:

[Broker]
GatewayURL_0=https://this-comm-gw.example.com:443/
GatewayURL_1=https://primary-gw-1.example.com:443/
GatewayURL_2=https://primary-gw-2.example.com:443/

[Gateway.Lockdown]
IsCommGateway=true
  • GatewayURL_N — an indexed list where entry _0 is this communications gateway’s own URL and entries _1 and up are the Primary Gateways this instance must reach. Configuration Manager writes the self URL at _0 on every save, and omits that entry from the UI list. If you edit settings.ini directly and leave the self entry out, the service falls back to a local binding, so a missing _0 is tolerated — including it keeps the file consistent with what Configuration Manager would write. Any address that resolves to this machine (hostname, local IP, 127.0.0.1) is accepted as self; the exact form does not need to match a particular binding. Numbering must be contiguous. Each URL follows the same format as the Broker’s [Broker] CommGatewayURL_N keys: scheme + host + explicit port + trailing slash (see URL format in the Primary Broker article).
  • [Gateway.Lockdown] IsCommGateway=true — the settings.ini equivalent of the This is a communications gateway checkbox. Omit the section (or set to false) on a primary gateway.
5

Commit the Changes

If you configured the Gateway from Thinfinity Configuration Manager, select Apply to finalize the configuration.

If you edited settings.ini directly, save and close the file, then restart the Gateway service for the new values to take effect.