Skip to main content

TLS Termination

ngrok automatically handles TLS (SSL) termination and certificate management for you. There is typically nothing to setup, configure or manage.

Overview​

ngrok's TLS termination behavior is determined by an endpoint's protocol and traffic policy. You may customize each endpoint to choose where TLS is terminated, how it is terminated and even whether it is terminated at all. When ngrok's cloud service terminates TLS, it:

  • Uses latest and most secure version of TLS
  • Uses the TLS Certificate attached to the Domain which matches the Endpoint URL's hostname
  • Accelerates your traffic by using the global load balancer to terminate at its closest point of presence

ngrok supports end-to-end encryption where the ngrok cloud service does not terminate TLS connections and only sees enciphered traffic. When configured this way, you are responsible for configuring TLS termination in your upstream service or at the ngrok agent.

Termination Location​

TLS connections to your ngrok endpoints are terminated at one of three locations.

  • ngrok's cloud service: This is the easiest and most common. All HTTPS endpoints terminate TLS at ngrok's cloud service. When connections are terminated by ngrok's cloud service, they are re-encrypted before they are transmitted over a Secure Tunnel to an agent.
  • ngrok agent: This is a form of end-to-end encryption where the ngrok cloud service does not terminate TLS and you instead configure the ngrok agent to terminate TLS connections for you.
  • your upstream service: This is another form of end-to-end encryption where neither the cloud service nor an agent terminates TLS connections. Instead, your upstream application service is responsible for TLS termination.

An endpoint's protocol determines the ngrok cloud service's default TLS termination behavior.

Endpoint ProtocolTLS Termination
HTTPNone
HTTPSAlways at ngrok's cloud service.
TLSDefault no termination, configurable with terminate-tls
TCPDefault no termination, configurable with terminate-tls

Examples​

Cloud Service​

Loading…
traffic-policy.yml​
Loading…

Terminate at Agent​

See Zero-Knowledge TLS at the Agent for additional details.

Loading…

Terminate at Upstream​

Loading…

terminate-tls​

The terminate-tls Traffic Policy Action enables you to terminate TLS connections at ngrok's cloud service for TCP and TLS endpoints.

You may also use this action on HTTPS endpoints to customize how TLS is terminated. When you use the terminate-tls action on an HTTPS endpoint, ngrok will skip the default TLS termination step that it runs for all HTTPS endpoints so as not to terminate TLS twice.

Acceleration​

The ngrok cloud service improves the performance of your endpoints by accelerating TLS termination using ngrok's global points of presence.

TLS connection set up requires multiple network round-trips. When round-trip times (RTTs) are long, TLS connection establishment slows down. ngrok reduces the latency of these round-trip times between the client and your endpoint by terminating connections at the closest point of presence via its global load balancer.

Certificates​

When the ngrok cloud service terminates TLS connections, it does so with the TLS Certificate attached to the Domain which matches the Endpoint URL's hostname. See the documentation on TLS Certificates for more details on how they are selected, managed, provisioned and renewed.

You may customize which TLS certificate is chosen for termination with the terminate-tls traffic policy action.

Mutual TLS​

Mutual TLS is supported when terminating TLS at ngrok's cloud service via the mutual_tls_certificate_authorities field of the terminate-tls traffic policy action.

Mutual TLS is supported when terminating TLS at the agent via the mutual_tls_certificate_authorities property of the agent_tls_termination section of an endpoint configuration in the agent configuration file.

Handshake​

TLS Version​

ngrok uses TLS 1.3 (the latest version) by default. If a client does not support TLS 1.3, ngrok will use the highest possible version that the client supports, down to TLS 1.1.

You may customize the minimum and maximum supported versions of TLS with the terminate-tls traffic policy action.

ALPN​

https endpoints negotiate the next protocol via ALPN with the following default list in order of preference:

Loading…

SNI​

ngrok endpoints do not support legacy clients which do not set the SNI extension. For example, the following clients (and others) will fail to work with ngrok endpoints:

Encrypted Client Hello​

ngrok endpoints do not yet support the draft implementation of Encrypted Client Hello.

FIPS Compliance​

ngrok does not use a FIPS-compliant TLS implementation by default, but one can be enabled for your endpoints.

Contact us if you require a FIPS-compliant TLS implementation.

End-to-end encryption​

You may choose to terminate TLS at your upstream service or at the ngrok agent to achieve end-to-end encryption (E2EE). When your endpoints operate in this mode, the ngrok cloud service can not see the payloads that transfer through your endpoints.

Creating an endpoint with end-to-end encryption is simple:

  • Create a TLS or TCP endpoint
  • Do not add a terminate-tls action to its traffic policy.

That's it! Read the Agent TLS Termination Guide for a step by step approach to set it up.

To set up the agent to terminate TLS for you, consult the following table because the configuration depends on which kind of agent you are using.

AgentDocumentation
Agent Config Fileagent_tls_termination
Go SDKWithTLSTerminationKeyPair
Other SDKsnot supported
Kubernetes Operatornot supported

Limits and Timeouts​

LimitNameNotes
60 secondsTLS Handshake DurationTime between ClientHello received and handshake completion
64 KBHandshake Message SizeMax size of non-certificate handshake messages
256 KBCertificate Message SizeMax size of certificate handshake messages
16 KBRecord Payload Size