Twingate

Client Connection Flow

With at least one Connector and Client registered with your Twingate network, secure and private connections can now be established with Resources. Users are authorized to access Resources based on rules that an admin user sets in the Admin console. These rules are stored in the Controller and delivered as a minimal whitelist ACL to Clients when they successfully register with the Controller and on any subsequent updates.

The Client connection flow ties together everything we have covered so far in this guide. It may be helpful to consult the Architecture Overview diagram and descriptions as you follow the steps below.

Summary

In order to access a Resource, the Client must:

  1. Detect a network connection request to a Resource in the Client's whitelist ACL. This list is signed by the Controller and stored by the Client.
  2. Obtain a signed token from the Controller that authorizes the Client to connect to a Connector with access to the Resource. Before any Client is authorized to connect to a Resource, it must obtain a time-bound token with current details on how to reach the relevant Connector for the Resource.
  3. Establish a certificate-pinned direct TLS connection to the Connector. This is facilitated by a Relay, which allows a single cert-pinned TLS tunnel to be established from the Client to the Connector.
  4. Obtain a new Controller-signed token that allows the Connector to verify the ACL presented by the Client. This time-bound token is bound to the Client's private key and signed by the Controller, which allows the Connector to derive sufficient proof that the connection request is valid and originates from the same Twingate network it is connected to.
  5. Begin securely proxying traffic to the destination Resource. At this point the Client can begin securely forwarding proxied traffic to the Resource via the Connector, which uses its local address on the Remote network.

These steps are covered in more detail, below.

Detecting a connection request to a Resource

When the Client starts the user authentication process, it also establishes a full VPN tunnel to localhost (127.0.0.1) allowing the Client to detect network connection requests for Resources in its whitelist ACL. (Note: Despite this local tunnel being established and any OS-level notification the user may see, as described in detail below, Twingate is not a VPN, and no VPN connection is established with any remote destination.)

The purpose of this tunnel is to:

  • Detect connection requests to private Resources on your Twingate network (determined by the whitelist ACL obtained from the Controller) based on the destination address in the connection request. This destination address does not have to be routable from the Client host device.
  • Allow connection requests for private Resources to be transparently proxied by the Client. The Client is able to transparently proxy any TCP or UDP traffic, regardless of port or protocol. (Administrators may wish to configure port restrictions if desired via the Admin Console.)
  • Route any connection requests that do not match the whitelist ACL via bypass, which sends this traffic to the pre-existing routing table on the Client host device. These connections will proceed as if the Client is not running on the device.

The following steps only apply to connection requests to Resources configured as part of your Twingate network. For these intercepted connections to private Resources, the transparent proxy in the Client will hold the connection request until the security checks below are completed. The implication of this is that network requests for private Resources will not leave the Client host device unless the user is authorized for access.

Obtaining authorization to connect to a Connector

Once a connection request to a Resource has been detected and intercepted by the relevant Client proxy, it must obtain authorization and connection information for a Connector that can forward traffic to the Resource.

This authorization is obtained from the Controller for the relevant Resource, and it contains all the information needed to initiate the connection. Amongst other information, this includes the FQDN of the Relay that the Connector is connected to and a digest of the Connector's certificate. This digest is important to allow TLS certificate pinning for the tunnel that will be established between the Client and Connector.

Establishing a certificate-pinned TLS connection to the Connector

Before any private traffic is forwarded to the Connector, the Client first ensures that it can establish an end-to-end TLS connection to the Connector identified by the certificate digest provided by the Controller.

The process starts by the Relay and Client each verifying the other's identity. The Client validates the Relay's FQDN-based public certificate, and the Relay validates that the token presented by the Client was signed by a known Controller. Once this verification is complete, the Relay allows the Client to connect directly to the Connector, and the Client and Connector then establish an end-to-end TLS tunnel. This TLS connection is pinned based on the Connector's certificate digest obtained from the Controller in the previous step.

Presenting Controller-signed authorization to access the Resource

With a TLS tunnel now established with the Connector, the Client must now present proof that it is entitled to access the requested Resource. This starts with a second authorization request to the Controller, which responds with a signed ACL (specific to the authenticated user) that also includes the Client's public key.

When this new authorization token is presented to the Connector, it is able to verify that the Client has obtained authorization from the same Controller than the Connector obtained authorization from. As an additional protection against MITM attacks, the Client and Connector also use a "proof-of-possession" technique (per RFC 7800) to verify that the TLS tunnel is intact.

With the above verification steps completed, the Connector is now ready to proxy network connections to authorized Resource destination addresses.

Securely proxying traffic to the destination Resource

Now that an encrypted tunnel has been established and the Connector has verified that it is connected to a known Client with a Controller-signed ACL, the Connector can begin connecting proxied network connections to authorized Resources.

In the first step above, we left off where a network connection request for a Resource was held by the Client's transparent proxy while the encrypted tunnel was established. The connection flow now proceeds as follows:

  1. If the Resource is defined by a FQDN, the DNS request is forwarded to the Connector. DNS resolution happens locally at the Connector, which means that local, private DNS can be used for Resources, even if they are being accessed by users off-network.
  2. With a known IP address for the Resource routable from the Connector, the connection request from the Client host device is forwarded to the Resource. This completes the connection from the source on Client host device to the destination Resource. Connection negotiation, including establishing an encrypted channel, takes place as normal between the source application and the destination. The application is not aware that the connection is being proxied through an encrypted TLS tunnel to a remote network.

Updated 17 days ago


Client Connection Flow


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.