Terminate TLS Action

The Terminate TLS Traffic Policy action allows you to control how ngrok terminates TLS traffic. This action is useful when you need to specify a custom certificate, control which TLS versions are supported, or enable mutual TLS authentication.

Configuration reference

This is the Traffic Policy configuration reference for this action.

Supported phases

on_tcp_connect

Supported schemes

https
tls

Type

terminate-tls

Configuration fields

Behavior

For HTTPS endpoints, ngrok already terminates TLS connections for you even if you don’t explicitly use this action in your Traffic Policy. If you specify this action in your Traffic Policy without any configuration, you see no change in behavior for your endpoints. For TLS endpoints, ngrok doesn’t terminate the TLS connection by default, and it’s up to you to handle TLS termination in your upstream service.

Changing supported TLS versions

You can use this action to specify the minimum and maximum TLS versions that your endpoint supports for incoming connections. By default, your endpoint supports TLS versions 1.2 and 1.3. To support different versions of TLS, use the min_version and max_version fields in the configuration. Clients using an unsupported version of TLS receive a handshake error.

Non-terminating action

This is a Non-terminating action. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All Cloud Endpoint Traffic Policies must end with a terminating action. This requirement does not apply to Agent Endpoints.

Examples

Minimum and maximum TLS versions

This example sets the minimum and maximum TLS versions that the endpoint supports for incoming connections to TLS version 1.3. Clients can then only connect to the endpoint using TLS version 1.3 and receive a handshake error if they attempt to connect using a different version.

Example Traffic Policy document

on_tcp_connect:
  - actions:
      - type: terminate-tls
        config:
          min_version: '1.3'
          max_version: '1.3'

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "terminate-tls",
          "config": {
            "min_version": "1.3",
            "max_version": "1.3"
          }
        }
      ]
    }
  ]
}

Start an endpoint with Traffic Policy

ngrok http 8080 --url https://terminate-tls-example.ngrok.app --traffic-policy-file /path/to/policy.yml

Make a request

curl https://terminate-tls-example.ngrok.app

If your curl was built with a version of OpenSSL that supports TLS 1.3, the request succeeds. However, you can verify that the endpoint only supports TLS 1.3 by telling curl to use a different version of TLS:

curl https://terminate-tls-example.ngrok.app --tlsv1.2 --tls-max 1.2

You receive an “alert protocol version” error indicating that the endpoint only supports TLS 1.3.

Using a custom certificate

To specify a custom certificate for your endpoints instead of having ngrok manage the certificate for you, use the server_private_key and server_certificate fields in the configuration. This gives you full control over which certificate your endpoint uses.

Generate certificates

Create a new Certificate Authority (CA) to sign the server certificate. This allows you to generate multiple server certificates that the CA trusts if needed.

This generates a self-signed certificate. To use a custom certificate that modern operating systems and browsers trust, you need to use a trusted CA (for example, LetsEncrypt).

Generate CA private key (ca.key)

openssl genpkey -algorithm RSA -out ca.key -pkeyopt rsa_keygen_bits:2048

Generate CA certificate (ca.crt)

openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=ExampleCA"

Generate server private key (server.key)

openssl genpkey -algorithm RSA -out server.key -pkeyopt rsa_keygen_bits:2048

Generate server certificate signing request (CSR) (server.csr)

openssl req -new -key server.key -out server.csr -subj "/CN=terminate-tls-example.ngrok.app"

Change terminate-tls-example.ngrok.app to the domain you’re using with your endpoint.

Generate server certificate (server.crt)

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256

These commands create five new files: ca.key, ca.crt, server.key, server.csr, and server.key.

Example Traffic Policy document

on_tcp_connect:
  - actions:
      - type: terminate-tls
        config:
          server_private_key: |-
            -----BEGIN PRIVATE KEY-----
            ... private key ...
            -----END PRIVATE KEY-----
          server_certificate: |-
            -----BEGIN CERTIFICATE-----
            ... certificate ...
            -----END CERTIFICATE-----

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "terminate-tls",
          "config": {
            "server_private_key": "-----BEGIN PRIVATE KEY-----\n... private key ...\n-----END PRIVATE KEY-----",
            "server_certificate": "-----BEGIN CERTIFICATE-----\n... certificate ...\n-----END CERTIFICATE-----"
          }
        }
      ]
    }
  ]
}

Replace the contents of server_private_key with the contents of server.key and server_certificate with server.crt respectively in the Traffic Policy to enable your custom certificate on your endpoint and ca.crt to trust the certificate when using curl.

Start an endpoint with Traffic Policy

ngrok http 8080 --url https://terminate-tls-example.ngrok.app --traffic-policy-file /path/to/policy.yml

Make a request

Now you can make a request to the endpoint with the --cacert flag to specify the CA certificate you generated.

curl --cacert ca.crt https://terminate-tls-example.ngrok.app

If you have a service running on port 8080, ngrok forwards your request to that service. If you don’t have any service running on that port, ngrok returns an error page, but the certificate setup still works.

Enabling mutual TLS

This example demonstrates how to use mutual TLS (mTLS) with this action. mTLS requires both the client and server to present certificates to each other to establish a secure connection. This example shows you how to generate a custom Certificate Authority (CA) and client certificate to use.

Generate certificates

Create a new CA to sign the client certificate. This allows you to generate multiple client certificates that the CA trusts if needed.

# 1. Generate CA private key (ca.key)
openssl genpkey -algorithm RSA -out ca.key -pkeyopt rsa_keygen_bits:2048

# 2. Generate CA certificate (ca.crt)
openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=ExampleCA"

# 3. Generate client private key (client.key)
openssl genpkey -algorithm RSA -out client.key -pkeyopt rsa_keygen_bits:2048

# 4. Generate client certificate signing request (CSR) (client.csr)
openssl req -new -key client.key -out client.csr -subj "/CN=ExampleClient"

# 5. Generate client certificate (client.crt)
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256

These commands create five new files: ca.key, ca.crt, client.key, client.csr, and client.key. You use the contents of ca.crt in your Traffic Policy to validate requests from curl, which uses client.key and client.crt.

Example Traffic Policy document

Using the CA certificate you generated, you can specify the mutual_tls_certificate_authorities field in the Traffic Policy to trust the CA that issued the client certificate.

on_tcp_connect:
  - actions:
      - type: terminate-tls
        config:
          mutual_tls_certificate_authorities:
            - |-
              -----BEGIN CERTIFICATE-----
              ... certificate ...
              -----END CERTIFICATE-----

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "terminate-tls",
          "config": {
            "mutual_tls_certificate_authorities": [
              "-----BEGIN CERTIFICATE-----\n... certificate ...\n-----END CERTIFICATE-----"
            ]
          }
        }
      ]
    }
  ]
}

You can also upload the CA certificate in the ngrok dashboard and use its ID in the mutual_tls_certificate_authorities array.

Start an endpoint with Traffic Policy

ngrok http 8080 --url terminate-tls-example.ngrok.app --traffic-policy-file /path/to/policy.yml

Make a request

Now you can make a request to the endpoint with the --cert and --key flags to specify the client certificate and private key.

curl --cert client.crt --key client.key https://terminate-tls-example.ngrok.app

Action result variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

Name	Type	Description
`actions.ngrok.terminate_tls.cipher_suite`	`string`	The cipher suite selected during the TLS handshake.
`actions.ngrok.terminate_tls.client.extensions[i].critical`	`bool`	True if the extension is critical.
`actions.ngrok.terminate_tls.client.extensions[i].id`	`string`	The identifier (OID) that specifies the type of extension.
`actions.ngrok.terminate_tls.client.extensions[i].value`	`[]byte`	The data for the extension.
`actions.ngrok.terminate_tls.client.extensions`	`[]Extension`	Additional information added to the certificate.
`actions.ngrok.terminate_tls.client.issuer.common_name`	`string`	Common name of the issuing authority, usually the domain name.
`actions.ngrok.terminate_tls.client.issuer.country`	`[]string`	Country names where the issuing authority is located.
`actions.ngrok.terminate_tls.client.issuer.locality`	`[]string`	Locality or city of the issuing authority.
`actions.ngrok.terminate_tls.client.issuer.organization`	`[]string`	Name of the organization that issued the certificate.
`actions.ngrok.terminate_tls.client.issuer.organizational_unit`	`[]string`	Division of the organization responsible for the certificate.
`actions.ngrok.terminate_tls.client.issuer.postal_code`	`[]string`	Postal code of the issuing authority.
`actions.ngrok.terminate_tls.client.issuer.province`	`[]string`	Province or state of the issuing authority.
`actions.ngrok.terminate_tls.client.issuer.street_address`	`[]string`	Street address of the issuing authority.
`actions.ngrok.terminate_tls.client.issuer`	`string`	The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax.
`actions.ngrok.terminate_tls.client.san.dns_names`	`[]string`	DNS names in the subject alternative names.
`actions.ngrok.terminate_tls.client.san.email_addresses`	`[]string`	Email addresses in the subject alternative names.
`actions.ngrok.terminate_tls.client.san.ip_addresses`	`[]string`	IP addresses in the subject alternative names.
`actions.ngrok.terminate_tls.client.san.uris`	`[]string`	URIs in the subject alternative names.
`actions.ngrok.terminate_tls.client.san`	`string`	Subject alternative names of the client certificate.
`actions.ngrok.terminate_tls.client.serial_number`	`string`	Unique identifier for the certificate.
`actions.ngrok.terminate_tls.client.signature_algorithm`	`string`	Algorithm used to sign the certificate.
`actions.ngrok.terminate_tls.client.subject.common_name`	`string`	Common name of the subject, usually the domain name.
`actions.ngrok.terminate_tls.client.subject.country`	`[]string`	Country names where the subject of the certificate is located.
`actions.ngrok.terminate_tls.client.subject.locality`	`[]string`	Locality or city where the subject is located.
`actions.ngrok.terminate_tls.client.subject.organization`	`[]string`	Name of the organization to which the subject belongs.
`actions.ngrok.terminate_tls.client.subject.organizational_unit`	`[]string`	Division of the organization to which the subject belongs.
`actions.ngrok.terminate_tls.client.subject.postal_code`	`[]string`	Postal code where the subject is located.
`actions.ngrok.terminate_tls.client.subject.province`	`[]string`	Province or state where the subject is located.
`actions.ngrok.terminate_tls.client.subject.street_address`	`[]string`	Street address where the subject is located.
`actions.ngrok.terminate_tls.client.subject`	`string`	The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax.
`actions.ngrok.terminate_tls.client.validity.not_after`	`timestamp`	Expiration date and time when the certificate is no longer valid.
`actions.ngrok.terminate_tls.client.validity.not_before`	`timestamp`	Start date and time when the certificate becomes valid.
`actions.ngrok.terminate_tls.error.code`	`string`	The error code if the action encountered any errors during its execution.
`actions.ngrok.terminate_tls.error.message`	`string`	The error message if the action encountered any errors during its execution.
`actions.ngrok.terminate_tls.server.extensions[i].critical`	`bool`	True if the extension is critical.
`actions.ngrok.terminate_tls.server.extensions[i].id`	`string`	The identifier that specifies the type of extension.
`actions.ngrok.terminate_tls.server.extensions[i].value`	`[]byte`	The data for the extension.
`actions.ngrok.terminate_tls.server.extensions`	`[]Extension`	Additional information added to the certificate.
`actions.ngrok.terminate_tls.server.issuer.common_name`	`string`	Common name of the issuing authority, usually the domain name.
`actions.ngrok.terminate_tls.server.issuer.country`	`[]string`	Country names where the issuing authority is located.
`actions.ngrok.terminate_tls.server.issuer.locality`	`[]string`	Locality or city of the issuing authority.
`actions.ngrok.terminate_tls.server.issuer.organization`	`[]string`	Name of the organization that issued the certificate.
`actions.ngrok.terminate_tls.server.issuer.organizational_unit`	`[]string`	Division of the organization responsible for the certificate.
`actions.ngrok.terminate_tls.server.issuer.postal_code`	`[]string`	Postal code of the issuing authority.
`actions.ngrok.terminate_tls.server.issuer.province`	`[]string`	Province or state of the issuing authority.
`actions.ngrok.terminate_tls.server.issuer.street_address`	`[]string`	Street address of the issuing authority.
`actions.ngrok.terminate_tls.server.issuer`	`string`	The issuing authority of the certificate as a string roughly following the RFC 2253 Distinguished Names syntax.
`actions.ngrok.terminate_tls.server.san.dns_names`	`[]string`	DNS names in the subject alternative names of the ngrok server’s leaf TLS certificate.
`actions.ngrok.terminate_tls.server.san.email_addresses`	`[]string`	Email addresses in the subject alternative names of the ngrok server’s leaf TLS certificate.
`actions.ngrok.terminate_tls.server.san.ip_addresses`	`[]string`	IP addresses in the subject alternative names of the ngrok server’s leaf TLS certificate.
`actions.ngrok.terminate_tls.server.san.uris`	`[]string`	URIs in the subject alternative names of the ngrok server’s leaf TLS certificate.
`actions.ngrok.terminate_tls.server.san`	`string`	Subject alternative names of the ngrok server’s leaf TLS certificate.
`actions.ngrok.terminate_tls.server.serial_number`	`string`	Unique identifier for the certificate.
`actions.ngrok.terminate_tls.server.signature_algorithm`	`string`	Algorithm used to sign the certificate.
`actions.ngrok.terminate_tls.server.subject.common_name`	`string`	Common name of the subject, usually the domain name.
`actions.ngrok.terminate_tls.server.subject.country`	`[]string`	Country names where the subject of the certificate is located.
`actions.ngrok.terminate_tls.server.subject.locality`	`[]string`	Locality or city where the subject is located.
`actions.ngrok.terminate_tls.server.subject.organization`	`[]string`	Name of the organization to which the subject belongs.
`actions.ngrok.terminate_tls.server.subject.organizational_unit`	`[]string`	Division of the organization to which the subject belongs.
`actions.ngrok.terminate_tls.server.subject.postal_code`	`[]string`	Postal code where the subject is located.
`actions.ngrok.terminate_tls.server.subject.province`	`[]string`	Province or state where the subject is located.
`actions.ngrok.terminate_tls.server.subject.street_address`	`[]string`	Street address where the subject is located.
`actions.ngrok.terminate_tls.server.subject`	`string`	The entity to whom the certificate is issued as a string roughly following the RFC 2253 Distinguished Names syntax.
`actions.ngrok.terminate_tls.server.validity.not_after`	`timestamp`	Expiration date and time when the certificate is no longer valid.
`actions.ngrok.terminate_tls.server.validity.not_before`	`timestamp`	Start date and time when the certificate becomes valid.
`actions.ngrok.terminate_tls.sni`	`string`	The hostname included in the `ClientHello` message via the SNI extension.
`actions.ngrok.terminate_tls.version`	`string`	The version of the TLS protocol used between the client and the ngrok edge.
`actions.ngrok.terminate_tls.warnings`	`[]string`	A list of any warnings encountered during the parsing of Certificate Authority IDs.

These variables are also available on the conn object (see HTTP Variables for examples).

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Configuration reference

Supported phases

Supported schemes

Type

Configuration fields

Behavior

Changing supported TLS versions

Non-terminating action

Examples

Minimum and maximum TLS versions

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Using a custom certificate

Generate certificates

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Enabling mutual TLS

Generate certificates

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Action result variables

​Configuration reference

​Supported phases

​Supported schemes

​Type

​Configuration fields

​Behavior

​Changing supported TLS versions

​Non-terminating action

​Examples

​Minimum and maximum TLS versions

​Example Traffic Policy document

​Start an endpoint with Traffic Policy

​Make a request

​Using a custom certificate

​Generate certificates

​Example Traffic Policy document

​Start an endpoint with Traffic Policy

​Make a request

​Enabling mutual TLS

​Generate certificates

​Example Traffic Policy document

​Start an endpoint with Traffic Policy

​Make a request

​Action result variables

Configuration reference

Supported phases

Supported schemes

Type

Configuration fields

Behavior

Changing supported TLS versions

Non-terminating action

Examples

Minimum and maximum TLS versions

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Using a custom certificate

Generate certificates

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Enabling mutual TLS

Generate certificates

Example Traffic Policy document

Start an endpoint with Traffic Policy

Make a request

Action result variables