Skip to content

TLS automation

Clement Tee edited this page Oct 2, 2026 · 5 revisions

Overview

The Twingate Client reaches the Gateway over TLS. The Gateway serves a certificate, and the Client validates it against the hostname it dials. Some protocol clients, such as an HTTPS client, also establish a second TLS session with the Gateway inside that connection. See How It Works for how the two layers fit together.

The Gateway serves the TLS certificates from one or both of these configurations:

  • Static certificates: a certificate that the Gateway loads when it starts. The Helm chart can generate one for you, or you can provide your own.
  • On-demand certificates: a certificate that a Certificate Authority (CA) issuer signs for the Gateway during the TLS handshake, one for each new server name (SNI). The issuer can be a local CA or a third-party issuers such as Vault or Google Cloud Private CA.

Using on-demand certificates

On-demand certificates are best suited to cases where you do not know all the domain names in advance. As such, you can let the issuer sign a certificate for each SNI as clients connect. The issued certificate covers only the SNI of the handshake, so a resource reached by both its address and its alias gets one certificate for each name.

When a handshake arrives for an SNI that has no cached certificate, the Gateway holds the handshake while the issuer signs a new certificate. The delay may take a few seconds and depends on the issuer: the local issuer signs inside the Gateway, while third-party issuers may add a network round trip. The subsequent handshakes for the same SNI are faster because they reuse the cached certificate. If the issuer fails to sign, the handshake fails.

The Gateway does not renew certificates in the background. Once a cached certificate is within 5 minutes of expiring, the next handshake for that SNI replaces it with a new certificate, so clients never receive an expired one.

Using static and on-demand certificates together

You can configure static and on-demand certificates together. For each handshake, the Gateway picks a certificate in the following order:

  1. It matches the static certificates in the order they are listed, and serves the first one that is valid for the SNI. The auto-generated certificate comes first, followed by the entries of tls.certificates.secrets in order.
  2. If no static certificate matches and on-demand certificates are configured, it serves the cached on-demand certificate for the SNI, or let the issuer sign a new one.
  3. If no static certificate matches and on-demand certificates are not configured, it serves the first static certificate.

Configuration

This section describes how to configure static and on-demand certificates through the Helm chart values.

Prerequisites

The Gateway needs a Twingate Network and the other Twingate components (Client and Connector) to work. Check out the Quick Start Guide to set things up first.

The examples below install the Gateway through the Twingate Kubernetes Operator Helm chart, which installs the Gateway as a subchart. The TLS settings apply to every protocol the Gateway supports, so you can add the values from each example to the values.yaml of your Kubernetes, SSH, or Web App setup, then upgrade the release:

helm upgrade twop oci://ghcr.io/twingate/helmcharts/twingate-operator --install --wait -f ./values.yaml

Static certificates

To have the chart generate a certificate, list every resource address and alias the Gateway serves in dnsNames, and any IP addresses in ipAddresses:

gateway:
  tls:
    certificates:
      autoGenerated:
        enabled: true
        dnsNames:
          - internal.default.svc.cluster.local
          - app.int
          # Wildcard names work too
          - "*.default.svc.cluster.local"   # addresses such as billing.default.svc.cluster.local
          - "*.acme.int"                    # aliases such as billing.acme.int
        ipAddresses:
          - 10.0.0.1

Note

A wildcard name covers any name that has exactly one label in place of the *: *.svc.cluster.local does not cover billing.default.svc.cluster.local, and *.acme.int does not cover acme.int itself.

To have cert-manager issue the certificate, use an Issuer or ClusterIssuer that already exists in the cluster. The chart creates a cert-manager Certificate resource for the names in dnsNames and ipAddresses:

gateway:
  tls:
    certificates:
      autoGenerated:
        enabled: true
        dnsNames:
          - internal.default.svc.cluster.local
          - app.int
        certManager:
          enabled: true
          issuerRef:
            name: gateway-ca-issuer
            kind: ClusterIssuer

Note

The Twingate Operator registers the CA certificate that cert-manager stores under ca.crt in the certificate Secret.

To use your own certificate, add an entry to secrets with either the name of the Secret that holds it or the certificate content:

gateway:
  tls:
    certificates:
      secrets:
        - name: "tls-secret"
        - cert: "<certificate PEM>"
          key: "<private key PEM>"
          ca: "<CA certificate PEM>"

On-demand certificates

Configure one of the issuers below to have the Gateway issue certificates on demand.

Local CA issuer

The Gateway signs certificates itself, with a CA certificate and private key that you provide.

  1. Create a CA locally with OpenSSL:

    openssl ecparam -genkey -name prime256v1 -noout -out ca.key
    openssl req -new -x509 -key ca.key -out ca.crt -days 3650 \
      -subj "/CN=Twingate Gateway TLS CA" \
      -addext "basicConstraints=critical,CA:TRUE" \
      -addext "keyUsage=critical,keyCertSign,cRLSign"
  2. Configure the Helm chart values with the CA from step 1:

    gateway:
      tls:
        certificates:
          autoGenerated:
            enabled: false
        automation:
          enabled: true
          issuer:
            local:
              certificate: "<certificate PEM>"
              privateKey: "<private key PEM>"

Note

The Twingate Operator registers this CA with Twingate automatically.

Vault CA issuer

The PKI secrets engine of HashiCorp Vault signs the on-demand certificates. The Gateway authenticates to Vault with AppRole.

  1. Enable a PKI secrets engine and generate its root CA:

    vault secrets enable -max-lease-ttl=87600h pki
    vault write pki/root/generate/internal \
      common_name="Twingate Gateway TLS CA" \
      key_type=ec \
      key_bits=256 \
      ttl=87600h
  2. Create a PKI role that allows every resource address and alias the Gateway serves. The Gateway sends no subject common name unless you set tls.automation.certificate.commonName, so the role needs require_cn=false:

    vault write pki/roles/gateway-tls \
      key_type=any \
      allowed_domains="<list of allowed domains>" \
      allow_subdomains=true \
      require_cn=false \
      max_ttl=72h
  3. Create an AppRole for the Gateway to authenticate with. Keep the role ID and secret ID that the last two commands print for use later:

    vault auth enable approle
    vault write -f auth/approle/role/gateway
    vault read -field=role_id auth/approle/role/gateway/role-id
    vault write -field=secret_id -f auth/approle/role/gateway/secret-id
  4. Create a policy that allows signing with the PKI role, and attach it to the AppRole:

    vault policy write gateway-tls - <<EOF
    path "pki/sign/gateway-tls" {
      capabilities = ["create", "update"]
    }
    EOF
    vault write auth/approle/role/gateway token_policies=gateway-tls
  5. Fetch the root CA certificate to register with Twingate. Keep the output for use later:

    vault read -field=certificate pki/cert/ca
  6. Configure the Helm chart values with the role ID and secret ID, and the CA certificate:

    gateway:
      twingateOperator:
        gateway:
          certificateAuthority:
            certificate: |
              <the CA certificate from step 5>
      tls:
        certificates:
          autoGenerated:
            enabled: false
        automation:
          enabled: true
          issuer:
            vault:
              address: https://vault.acme.int:8200
              auth:
                appRole:
                  roleId: <role id from step 3>
                  secretId: <secret id from step 3>
              role: gateway-tls

    An inline secretId is for development and testing only. In production, store the secret ID in an existing Secret under the key secretId, and set secretIdSecretName to the name of that Secret instead of setting secretId.

Note

The Gateway sends exclude_cn_from_sans=true with every signing request, so Vault does not copy the subject common name into the SANs of the issued certificate. The Gateway rejects an issued certificate whose SANs differ from the ones it requested.

Google Cloud Private CA issuer

A CA pool in Google Cloud Certificate Authority Service signs the on-demand certificates.

  1. Grant the roles/privateca.certificateRequester role on the CA pool to the identity the Gateway runs as. On Google Kubernetes Engine (GKE), that is the Gateway's Kubernetes service account, through Workload Identity Federation. On Google Compute Engine (GCE), it is the service account attached to the virtual machine.

  2. Fetch the root CA certificates of the CA pool to register with Twingate. Keep the output for use later:

    gcloud privateca pools get-ca-certs <ca pool id> --project <project id> --location <location>
  3. Configure the Helm chart values with the CA certificate. The Google Cloud Private CA issuer requires a subject common name, so set tls.automation.certificate.commonName:

    gateway:
      twingateOperator:
        gateway:
          certificateAuthority:
            certificate: |
              <the CA certificate from step 2>
      tls:
        certificates:
          autoGenerated:
            enabled: false
        automation:
          enabled: true
          certificate:
            commonName: gateway.int
          issuer:
            gcpPrivateCA:
              project: <project id>
              location: <location>
              caPoolId: <ca pool id>

Limitation: connecting by IP address

A client that dials an IP address sends no SNI. When a static certificate is configured, the Gateway always serves the first static certificate, whether or not on-demand certificates are configured. When only on-demand certificates are configured, the Gateway serves an issued certificate with no SANs, which the client rejects.

To work around this limitation, do one of the following:

  • Give the resource an alias, such as cluster.int, and connect through the alias.
  • Serve a static certificate that has the IP address as a SAN, and make it the first static certificate. Either add the IP address to tls.certificates.autoGenerated.ipAddresses, or set tls.certificates.autoGenerated.enabled to false and list that certificate first in tls.certificates.secrets.

Clone this wiki locally