Skip to main content

TLS Endpoints

Overview​

TLS endpoints enable you to deliver any network service that runs over a TLS-based protocol. TLS endpoints make no assumptions about the wrapped protocol being transported.

TLS endpoints inspect the Server Name Indication (SNI) data on incoming TLS connections to route connections to the appropriate endpoint.

Because the TLS protocol describes no application-level semantics, ngrok can only offer a limited set of traffic policy actions to handle TLS traffic.

If you are delivering an HTTPS application, prefer to create an HTTP Endpoint.

Quickstart​

Loading…
traffic-policy.yml​
Loading…

URLs​

URLs are validated differently depending on their binding. Consult the following documentation for details on valid URLs for TLS endpoints:

There is no standard scheme for TLS URLs so ngrok renders them as tls://.

Bindings​

TLS endpoints support public and internal bindings. kubernetes binding is not supported.

Traffic Policy​

Attach Traffic Policy to endpoints to route, authenticate and transform the traffic through your TLS endpoints.

Authentication​

When you create public TLS endpoints, you often want to secure them with authentication. You can secure your TLS endpoints with the following Traffic Policy actions. There is a limited set of actions available to authenticate TLS traffic because the TLS protocol is low-level.

TLS​

Termination​

TLS Endpoints provide you with the flexibility to define where TLS termination occurs. You may configure your endpoint to terminate TLS at the ngrok cloud service or you can achieve end-to-end encryption by terminating at the agent or your upstream service. When you use end-to-end encryption, the ngrok cloud service can not see payload that transit through your endpoints.

Consult the documentation on TLS Termination Locations for additional details.

Cloud Service​

Loading…
traffic-policy.yml​
Loading…

Terminate at Agent​

See TLS Termination at the Agent for End-to-End Encryption for additional details.

Loading…

Terminate at Upstream​

Loading…

Certificates​

It is very common to encounter certificate errors when working with TLS endpoints. When terminating TLS at ngrok's cloud service, ngrok will automatically select, provision and manage certs for you. When performing end-to-end encryption by terminating at the agent or upstream service, you become responsible for provisioning, managing and distributing certificates.

Consult the documentation on TLS Certificates for details about certificate selection, provisioning and management.

Agent Forwarding​

Re-encrypt to Upstream​

If you terminate TLS at the ngrok cloud service or ngrok agent, you may want to re-encrypt the connection from the agent to your upstream service. The ngrok agent supports this behavior by using the non-standard tls:// scheme syntax.

Loading…

PROXY Protocol​

Add a PROXY protocol header on connection to your upstream service. This sends connection information like the original client IP address to your upstream service.

Loading…

Compatible Clients​

SNI​

TLS endpoints only work with modern TLS clients that populate the SNI extension. See the documentation on TLS Termination for additional details on compatible clients.

STARTTLS​

Protocols that begin in plain text and upgrade to TLS via a mechanism like STARTTLS in SMTP, IMAP, etc are not supported. If you need to support connections which upgrade to TLS, use a TCP Endpoint.

Observability​

Traffic Inspector​

Traffic Inspector does not support TLS endpoints.

Log Export Events​

You can export logs of traffic to TLS endpoints with ngrok's events system. The following events are published for log exporting:

EventWhen
tcp_connection_closed.v0Published when a TCP connection to a TCP endpoint completes.

Limits & Timeouts​

Contact us if you need to configure limits and timeouts on connections to TLS endpoints.

Connections​

LimitNameNotes
3 secondsClientHello TimeoutTime between connection establishment and ClientHello received
5 minutesClient Idle TimeoutTime since data was last transmitted by the upstream service
5 minutesServer Idle TimeoutTime since data was last transmitted by the upstream service
No limitData transmittedData transmitted by the client or upstream service

TLS​

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

Errors​

If a TLS handshake fails, an appropriate TLS abort code will be sent to the client.

In all other cases, if an error is encountered while handling TLS connections to your endpoints (e.g. no available backends or internal server error), the connection will be closed. The TLS protocol and its implementations are not sufficiently flexible enough to deliver additional rich error information when failures are encountered.

Use the observability features to understand connection handling errors.

API​

TLS Endpoints can be created programatically. Consult the documentation on Endpoint APIs.

Pricing​

TLS endpoints are available on Pay-as-you-go, Pro, and Enterprise plans. Consult the Endpoints Pricing documentation for billing details.

See Domains pricing for details on pricing for custom domains, wildcard domains and more.

Zero-knowledge TLS is available on the Enterprise plan.