Skip to main content
ngrok automatically handles TLS (SSL) certificate management and termination for you. There is typically nothing to set up, configure, or manage. You can manage TLS certificates on your ngrok dashboard or via the ngrok API.

​
Overview

TLS certificates are a tuple of a private key and certificate that are presented by the ngrok cloud service during a TLS handshakes to terminate TLS connections to HTTPS endpoints and TLS endpoints. TLS certificates are attached to domains for termination of TLS connections to endpoints whose URLs match that domain. ngrok can automatically provision certificates for you or you can upload your own. See the TLS Termination documentation for details on how and when ngrok terminates TLS connections.

​
Certificate selection

When TLS connections to an endpoint are terminated, ngrok uses the TLS Certificate attached to the domain matching the endpoint’s URL for termination. Each domain has an attached TLS certificate that is referenced by its certificate_id field. If the domain object does reference any certificate, or if there is no matching domain object for an endpoint’s URL, ngrok selects its own TLS certificate for termination. You may override the certificate used for TLS termination by explicitly terminating TLS yourself with the terminate-tls Traffic Policy action.

​
Certificate provisioning

Whenever you create a domain you choose how a TLS certificate will be provisioned. Either: It is recommended that you choose automatic TLS certificates unless you have special requirements.

​
Automatic provisioning

When you choose automatic TLS certificate management for a domain (this is the default), ngrok automatically provisions and renews TLS certificates from an ACME-compliant certificate authority like Let’s Encrypt. ngrok uses an HTTP01 challenge for TLS certificate provisioning of most domains. When you create a wildcard domain ngrok uses a DNS01 challenge instead. ngrok is a Let’s Encrypt sponsor.

​
Status

TLS certificates are provisioned asynchronously. Depending on DNS propagation and the speed of the ACME certificate authority, provisioning typically takes from a few seconds up to several minutes, and occasionally longer if a DNS challenge is slow to validate. The domain’s certificate_management_status field on the Reserved Domain API Resource contains the status of the provisioning job, including the current job state, the time it started, and when ngrok will next retry if it has hit a recoverable error. You can also see this status on the Domains page of your dashboard.

​
Expected behavior while a certificate is provisioning

While a certificate is still being provisioned, ngrok terminates HTTPS connections to the domain using a default ngrok wildcard certificate. Because that certificate is not issued for your hostname, browsers and other TLS clients will show a certificate warning indicating that the hostname doesn’t match the certificate if they connect to your endpoint before provisioning finishes. This is expected, and clears automatically as soon as the certificate is issued, usually within a few minutes. If the warning persists, check certificate_management_status.provisioning_job on the reserved domain (or the cert status panel on the dashboard) to see whether the job is still in progress or has hit an error that requires action, such as a missing or misconfigured CNAME record.

​
Bring your own domain

When you bring your own domain (such as api.your-domain.com) you must create a CNAME DNS record in your DNS provider. Certificate provisioning will not begin until your create this CNAME DNS record.

​
Wildcard domains

When you bring your own wildcard domain (such as *.app.example.com), ngrok uses a DNS01 challenge for TLS certificate provisioning which means that you must create two CNAME records when creating branded wildcard domains instead of just one. For example, if your domain is *.app.example.com, you will be required to create the following two CNAME records:
  • *.app.example.com
  • _acme-challenge.app.example.com
Certificate provisioning will not begin until you have created both DNS records.

​
Private keys

When using automatic TLS certificates, ngrok generates a private key for your domain and encrypts it at rest with NaCL. When you configure a domain to use automated certificates, you may electively choose whether ngrok will create an ECDSA private key (the default) or RSA private key. If you choose an RSA private key, it is created with a size of 4096 bits.

​
Bring your own certificates

You may upload your own TLS certificates if you don’t want to use the TLS certificates that ngrok automatically provisions for you. Uploading your own certificates may be the right choice if you are issuing certificates from your own certificate authority or if you are using an EV certificate. To bring your own TLS certificate, upload a certificate bundle and a private key. Keep in mind that after you create your TLS certificate, you must attach it to one or more domains before it will be used for termination. When working with the API, this is done by updating the certificate_id property of the Domain API Resource. Unlike automatic TLS certificates, when you are using custom TLS certificates, you are responsible for managing the renewal and rotation of new certificates.

​
Certificate bundles

When uploading your own TLS certificates to ngrok, you are expected to provide a certificate bundle of all certificates necessary to establish a chain of trust to a trusted root certificate authority. Many TLS certificate vendors will provide you with a constructed certificate bundle, but some will return the leaf certificate and the intermediate certificates separately and you must concatenate them to construct the bundle yourself. This is the certificate_pem field in the TLS Certificate Create API. Certificate bundles are a series of PEM-encoded X.509 certificates that have been concatenated together. The order of this bundle is significant. The first certificate in the bundle must be the leaf certificate. The leaf certificate is the one which is signed for your domain and the private key you will upload. After the leaf certificate are the intermediates certificates, if any. Each intermediate certificate signs the certificate preceding it in the bundle. As an example, the first intermediate will sign the leaf, and that signature is part of the leaf certificate itself. The final certificate will be signed by the root certificate authority. You may also included the root certificate in the bundle as well, but it is not necessary or common practice to do so. A certificate bundle will look like the following: 
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

​
Private keys

ngrok accepts the following formats for the private key of an uploaded TLS certificate. This is the private_key_pem field in the TLS Certificate Create API.
  • RSA, in either PKCS#1 or PKCS#8 form.
  • ECDSA, in either SEC 1 or PKCS#8 form.
  • Ed25519, in PKCS#8 form.
Regardless of the format you choose, the private key must be formatted as ASN.1 DER, encoded as PEM. ngrok does not accept any private keys that are encrypted (for example, with DES). ngrok encrypts your uploaded private keys at rest with NaCL.

​
API

TLS certificates are managed programmatically via:

​
TLS certificates pricing

TLS certificates are available on all plans. Bringing your own certificates is available on the Pay-as-you-go plan.