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, a Client must:

• 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.
• 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.
• 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.
• 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.
• 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.

We will cover these steps in 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 will transparently proxy any TCP or UDP traffic, regardless of port or protocol.
• Route any connection requests that do not match the whitelist ACL via bypass, which sends this traffic to the pre-existing routing table and DNS resolvers 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 the following information:

• The FQDN of the Relay that the Connector is connected to. The FQDN allows the Client to both connect to the right Relay and perform certificate validation of the Relay host.
• A hash of the Connector ID. This allows the Client to request a connection to the Connector without revealing any additional information to the Relay. This matches the hash that the Connector provided to the Relay during its initial registration.
• A digest of the Connector’s certificate, which allows TLS certificate pinning for the end-to-end connection established from the Client to the 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 Client connects to the Relay address it received in the Controller authorization, ensuring that the Relay’s certificate matches its FQDN.
• The Relay verifies that the authorization token presented by the Client is signed by a known Controller. This equivalent step was already performed for the Connector during the Connector registration process.
• The Relay verifies that the Connector requested by the Client (referenced by the hash of the Connector ID) is connected to the Relay.
• With the Client-Connector peering request validated, the Relay allows the Client to connect to the Connector.
• The Client and Connector negotiate and establish a TLS-encrypted tunnel. This session can only be established if the Connector’s certificate digest matches what was provided to the Client by the Controller resulting in a certificate-pinned connection.

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 an authorization request to the Controller and proceeds as follows:

• The Client requests a connection-specific token from the Controller. Every Client generates its own public/private key pair, and the request to the Controller includes the public key of the Client. This will subsequently be used by the Connector as additional validation of the source of the connection request.
• The Controller responds with a signed, time-bound token that validates access to the requested Resource. This signed response from the Controller includes the whitelist ACL of Resources that the Client is allowed to access and the Client’s public key.
• The Client signs a secret derived from the established TLS tunnel with the Connector. The Connector is able to derive the same secret from the shared context of the encrypted tunnel, which will allow validation that no intermediary has interfered with the connection.
• The Client sends both the Controller-signed authorization token and the Client-signed secret to the Connector over the established TLS tunnel. With this information, the Connector can validate that:
  • The same Controller that the Connector registered with has also authorized the Client to access certain Resources.
  • The same Client that established an end-to-end TLS tunnel with the Connector is sending the request.
  • No third party or intermediary has interfered with the TLS session via shared “proof-of-possession” per RFC 7800.
• The Connector validates the authorization token and signed secret received from the Client. The Connector verifies that the same Controller it is registered with signed the authorization token. It then uses the Client’s public key, included in the Controller-signed message, to validate the Client-signed secret representing the already-established TLS tunnel between the Client and Connector.

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:

• 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.
• 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.