Gateway TLS Certificates
Configure the certificates the Gateway serves, from a static certificate to on-demand certificates signed by your CA.
The Twingate Client reaches the Gateway over TLS. The Gateway serves a certificate, and the Client accepts the connection only if the certificate is valid for the hostname it dials. For HTTPS web apps, the browser also opens a second TLS session with the Gateway inside that connection.
The certificate must cover every address and alias of every Resource the Gateway serves. A Resource reached by its alias app.int and its address app.default.svc.cluster.local needs both names on the certificate.
The settings on this page apply to every protocol. The examples use the Helm values of the Twingate Kubernetes Operator chart, which installs the Gateway as a subchart under the gateway: key. After changing them, upgrade the release:
helm upgrade twop oci://ghcr.io/twingate/helmcharts/twingate-operator --install --wait -f ./values.yamlGateway 2.0 values
These examples use Gateway 2.0 Helm values. The Twingate Operator chart bundles Gateway 2.0 from Operator v3. In Gateway 1.x, dnsNames and ipAddresses sat directly under tls. See Upgrading the Gateway.
Certificate types
The Gateway serves certificates from one or both of these sources:
- Static certificates: Loaded when the Gateway starts, and reloaded whenever the certificate or key file changes, for example when cert-manager renews it. The Helm chart can generate one, cert-manager can issue one, or you can provide your own.
- On-demand certificates: Signed by a certificate authority (CA) issuer during the TLS handshake, one for each new server name (SNI). Use these when you don’t know every hostname in advance.
How the Gateway picks a certificate
For each TLS handshake, the Gateway picks a certificate in this order:
- The first static certificate valid for the SNI. The auto-generated certificate is checked first, followed by the entries in
tls.certificates.secretsin order. - If no static certificate matches and on-demand certificates are configured, the cached on-demand certificate for the SNI, or a newly signed one.
- If no static certificate matches and on-demand certificates are not configured, the first static certificate.
Static certificates
Auto-generated certificate
List every Resource address and alias in dnsNames, and any IP addresses in ipAddresses:
gateway: tls: certificates: autoGenerated: enabled: true dnsNames: - internal.default.svc.cluster.local - app.int - "*.default.svc.cluster.local" # addresses such as billing.default.svc.cluster.local - "*.acme.int" # aliases such as billing.acme.int ipAddresses: - 10.0.0.1Wildcard names let one certificate cover many Resources, so adding a Resource doesn’t require a new certificate. Give your aliases a shared suffix, such as acme.int, and cover them with one wildcard.
Wildcards match exactly one label
*.svc.cluster.local does not cover billing.default.svc.cluster.local, and *.acme.int does not cover acme.int itself.
Auto-generated certificates with ArgoCD
The chart uses Helm’s lookup function to reuse an existing certificate Secret. lookup returns nothing when rendering has no Kubernetes API access, as with ArgoCD, helm template, or --dry-run=client. Under ArgoCD, the chart generates a new CA and certificate on every sync. Use cert-manager or your own certificate instead.
cert-manager
To have cert-manager issue the certificate, reference an existing Issuer or ClusterIssuer. The chart creates a cert-manager Certificate 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: ClusterIssuerThe Twingate Operator registers the CA certificate that cert-manager stores under ca.crt in the certificate Secret.
Your own certificate
Add an entry to secrets with either the name of a Secret that holds the certificate or the certificate content:
gateway: tls: certificates: secrets: - name: "tls-secret" - cert: "<certificate PEM>" key: "<private key PEM>" ca: "<CA certificate PEM>"Setting secrets does not turn off the auto-generated certificate. To supply every certificate yourself, also set tls.certificates.autoGenerated.enabled: false.
On-demand certificates
When a handshake arrives for an SNI with no cached certificate, the Gateway holds the handshake while the issuer signs a new certificate. This can take a few seconds, depending on the issuer. Later handshakes for the same SNI reuse the cached certificate. If the issuer fails to sign, the handshake fails.
Each certificate covers only the SNI of its handshake, so a Resource reached by both its address and its alias gets two certificates.
The Gateway does not renew certificates in the background. When a cached certificate is within 5 minutes of expiring, the next handshake for that SNI replaces it, so clients never receive an expired certificate.
Configure one of the issuers below.
Local CA issuer
The Gateway signs certificates itself with a CA certificate and private key that you provide.
-
Create a CA with OpenSSL:
openssl ecparam -genkey -name prime256v1 -noout -out ca.keyopenssl 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" -
Add the CA to your Helm values:
gateway:tls:certificates:autoGenerated:enabled: falseautomation:enabled: trueissuer:local:certificate: "<certificate PEM>"privateKey: "<private key PEM>"
The Twingate Operator registers this CA with Twingate.
HashiCorp Vault issuer
The Vault PKI secrets engine signs the 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 pkivault 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. Save the role ID and secret ID that the last two commands print:
vault auth enable approlevault write -f auth/approle/role/gatewayvault read -field=role_id auth/approle/role/gateway/role-idvault 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 - <<EOFpath "pki/sign/gateway-tls" {capabilities = ["create", "update"]}EOFvault write auth/approle/role/gateway token_policies=gateway-tls -
Fetch the root CA certificate to register with Twingate:
vault read -field=certificate pki/cert/ca -
Add the role ID, secret ID, and CA certificate to your Helm values:
gateway:twingateOperator:gateway:certificateAuthority:certificate: |<the CA certificate from step 5>tls:certificates:autoGenerated:enabled: falseautomation:enabled: trueissuer:vault:address: https://vault.acme.int:8200auth:appRole:roleId: <role ID from step 3>secretId: <secret ID from step 3>role: gateway-tls
Store the secret ID in a Secret
An inline secretId is for testing only. In production, store the secret ID in a Kubernetes Secret under the key secretId, and set secretIdSecretName to that Secret’s name instead of secretId.
The Gateway sends exclude_cn_from_sans=true with every signing request, and 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 certificates.
-
Grant
roles/privateca.certificateRequesteron the CA pool to the identity the Gateway runs as. On GKE, that is the Gateway’s Kubernetes service account through Workload Identity Federation. On Compute Engine, it is the service account attached to the VM. -
Fetch the CA pool’s root CA certificates to register with Twingate:
gcloud privateca pools get-ca-certs <ca-pool-id> --project <project-id> --location <location> -
Add the CA certificate to your Helm values. This 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: falseautomation:enabled: truecertificate:commonName: gateway.intissuer:gcpPrivateCA:project: <project-id>location: <location>caPoolId: <ca-pool-id>
Connecting by IP address
A client that dials an IP address sends no SNI:
- With a static certificate configured, the Gateway always serves the first static certificate.
- With only on-demand certificates configured, the Gateway serves a certificate with no SANs, and the client rejects it.
To connect by IP address, do one of the following:
- Give the Resource an alias, such as
cluster.int, and connect through the alias. - Make the first static certificate cover the IP address. Add the IP address to
tls.certificates.autoGenerated.ipAddresses, or settls.certificates.autoGenerated.enabled: falseand list a certificate with the IP address first intls.certificates.secrets.
Last updated