Repository navigation
TLS automation
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.
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.
You can configure static and on-demand certificates together. For each handshake, the Gateway picks a certificate in the following order:
- 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.secretsin order. - 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.
- If no static certificate matches and on-demand certificates are not configured, it serves the first static certificate.
This section describes how to configure static and on-demand certificates through the Helm chart values.
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.yamlTo 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.1Note
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: ClusterIssuerNote
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>"Configure one of the issuers below to have the Gateway issue certificates on demand.
The Gateway signs certificates itself, with a CA certificate and private key that you provide.
-
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"
-
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.
The PKI secrets engine of HashiCorp Vault signs the on-demand certificates. The Gateway authenticates to Vault with AppRole.
-
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
-
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 needsrequire_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 -
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
-
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
-
Fetch the root CA certificate to register with Twingate. Keep the output for use later:
vault read -field=certificate pki/cert/ca -
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
secretIdis for development and testing only. In production, store the secret ID in an existing Secret under the keysecretId, and setsecretIdSecretNameto the name of that Secret instead of settingsecretId.
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.
A CA pool in Google Cloud Certificate Authority Service signs the on-demand certificates.
-
Grant the
roles/privateca.certificateRequesterrole 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. -
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>
-
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>
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 settls.certificates.autoGenerated.enabledtofalseand list that certificate first intls.certificates.secrets.
Copyright © 2025 Twingate.
Kubernetes
SSH
Web App
Operations
Development
Migration