Before network traffic can be encrypted and delivered to Resources in Remote networks, both Clients and Connectors need to register themselves with your Twingate network. This process is described for each component, below.

Connector Registration

Connectors can only be deployed by admin users in the Admin console. Connectors run within a headless Docker container behind the firewall of your Remote network. Because Connector authentication is not interactive, the deployment command provided to admins contains two tokens for each Connector that are specifically generated for the Connector that uniquely identify it. These tokens serve to authenticate the Connector and cannot be reused. Before the admin user is provided with the setup command for a Connector, we ask them to re-authenticate themselves as an additional security measure.

Once a new Connector starts up, it goes through the following registration process:

• It authenticates with the Controller by providing the authentication tokens included in its startup command.
• If the Connector’s authentication tokens are valid, the Controller responds with a signed, time-expiring message that includes:
  • A whitelist ACL specifying which Resources the Connector is allowed to forward connections to for any user. This allows the Connector to act as a second check on Client connections by ensuring that connections are only forwarded to configured Resources in the Remote network.
  • The FQDN(s) of one or more Relays that the Connector will establish connectivity to.
  • Token(s) signed by the Controller that authorize the Connector to establish a connection to the list of Relay(s) provided in the Controller’s response.
• The Connector validates the authenticity of the response from the Controller.
• The Connector establishes a connection to the Relay(s) in the Controller’s configuration message, which involves providing the Controller token to the Relay (obtained in step 2), which authorizes the Connector to establish a connection with the Relay. The Relay validates that this token was signed by the same Controller it is associated with. This includes a hash of the Connector’s ID, which avoids leaking any information about the name, location or network address of the Connector.
• Finally, the Connector periodically reports to the Controller the following information:
  • The set of Relay(s) that it is connected to. This provides the Controller with up to date information on which Connectors are accessible by Clients.
  • The digest of the Connector’s current certificate. This digest allows TLS certificate pinning for any future connections from Clients, which establish a TLS connection directly with the Connector. The Relay is never party to this information.

The Connector provides a heartbeat signal to the Controller on an ongoing basis, which allows Clients to connect to available Connectors in redundancy scenarios.

Client Registration

Clients start the registration process with your Twingate network after the end user has successfully authenticated themselves with a third party identity authority such as your configured identity provider or a social identity. Overall, the registration process for Clients is similar to that described for Connectors, above.

• When a user starts the authentication process, the Client connects to the Controller to initiate an authentication request.
• The Client receives a response with the URI for either the configured identity provider for your Twingate network, or a standard social identity sign in page.
• Once the user successfully authenticates with the third party, they receive a redirect to a Controller endpoint that includes a time-expiring access token. (This is the standard OpenID Authentication flow.)
• The Controller verifies that the user’s ID (verified email address) matches a configured and active user in your Twingate network. If there is a match, the user is authorized to connect, and the Controller responds by:
  • Issuing a set of tokens that expire within the expiration period received from the identity authority the user authenticated with. The Controller adheres to the original token expiry, and renewing these Controller tokens requires that the user re-authenticate with the identity authority. This allows the token expiration (and thus, reauthentication) policy to be managed centrally and remain consistent with the rest of the user’s experience.
  • Issuing a signed whitelist ACL that specifies which Resources the user is authorized to access (referencing the Resource address) and what Connector can be used to access each Resource.

From this point onwards, the Client configures itself to listen for any network connection request that matches a Resource address in the whitelist ACL. If a matching connection request is detected, the Client initiates the Client Connection Flow, which we will cover next.