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

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.secrets in 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.1

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

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: ClusterIssuer

The 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.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"
  • Add the CA to your Helm values:

    gateway:
    tls:
    certificates:
    autoGenerated:
    enabled: false
    automation:
    enabled: true
    issuer:
    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 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 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
  • Create an AppRole for the Gateway. Save the role ID and secret ID that the last two commands print:

    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:

    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: 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

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.certificateRequester on 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: false
    automation:
    enabled: true
    certificate:
    commonName: gateway.int
    issuer:
    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 set tls.certificates.autoGenerated.enabled: false and list a certificate with the IP address first in tls.certificates.secrets.

Last updated