ngrok Link Documentation

ngrok link is a specialized, enhanced version of ngrok specifically designed for running in production environments. Specifically, it is intended for two major use cases:

1. It is a lightweight VPN alternative that provides the automation and security necessary to establish targeted, secure links into customer environments.
2. It enables IoT devices to expose control functionality to customers or administrators at stable, secured endpoints. Remote shell access for debugging and administration can be safely exposed in this manner as well.

ngrok link is tuned for running optimally as part of your infrastructure and exposes a number of additional security features to give fine grained access and authentication control. Most importantly, these features are exposed via APIs so that you can automate your entire workflow with ngrok.

Intended Audience

THIS DOCUMENT ASSUMES YOU HAVE ALREADY READ AND UNDERSTOOD the ngrok documentation. If you have not, you should read the main documentation now. The following content is intended only as a supplement and will not be helpful without the proper context.

Differences

Because ngrok link is specialized for production environments, there are changes in the way it operates compared to a 'standard' ngrok agent. Those differences are enumerated here.

The following changes have been made to ngrok's configuration defaults.

• Request inspection for all tunnels is disabled by default.
• Automatic client updates are disabled by default.
• The console UI is disabled and ngrok logs to stdout by default.

Installing ngrok as a service

ngrok link includes additional functionality that makes it easy to install and manage itself as a native operating system service on Windows, OS X and Linux. This makes it extraordinarily easy to set up ngrok in a production configuration that will cause it to start on machine boot, restart after crashes, and integrate with the native tools system administrators are familiar with to manage and inspect its state.

When running as a service, ngrok configures itself from its configuration file and starts all tunnels defined in the configuration file. When ngrok runs as a service, it executes the equivalent behavior of running ngrok start --all.

Installation

Installing ngrok as a service is the same on all on operating systems. First, create an ngrok.yml configuration file somewhere on your machine. For this example, I'll assume it's in C:\ngrok\ngrok.yml. In your configuration file, make sure you include an authtoken and define all of the tunnels that you want to start. Then run:

ngrok service install -config C:\ngrok\ngrok.yml

This will validate that the configuration file is valid, and if so, install ngrok as a service using the given configuration file. The service installation includes the location of the ngrok binary, so don't move or delete it after you've installed the service.

Management

After your service is installed, you probably want to start it. You can easily do that with:

ngrok service start

ngrok exposes the following commands to make service administration easy. The commands take no arguments and do what you would expect.

• ngrok service start
• ngrok service stop
• ngrok service restart
• ngrok service uninstall

Windows

On Windows, ngrok installs itself as a Windows service. It can be managed via Windows Services and it logs all errors and warnings to the Windows event log.

OS X

On Darwin, ngrok creates an appropriate plist file and installs itself to run via launchd. Warnings and errors are logged via syslog.

Linux

On Linux, only systems with upstart or systemd installed are supported for service installation. If neither is installed, you will need to set up your own management of the ngrok process as a service. Warnings and errors are logged via syslog.

Per-client Authtoken Credentials

For production systems, every client must authenticate with a unique authtoken credential. This allows you to deactivate devices that are old or compromised. Further, it allows you to enforce a separate ACL policy on every connected device that limits what tunnels it is allowed to bind.

Generation

You can create authtokens from the Tunnel Authtokens tab in your ngrok dashboard. Click "Add Tunnel Authtoken" and then enter a human-readable description of the device or location where you intend to install the authtoken for tracking purposes.

In both the UI and API, the full authtoken you generate will only be shown once, immediately after creation!

ACL Enforcement

Credential ACLs describe what a client who connects with a given authtoken is allowed to do. For example, you may want to restrict each client to only have permission to bind a specific set of tunnel endpoints. When you create a credential, specify a list of ACL behaviors are allowed for any client connecting with that authtoken.

Generating credentials with ACLs is only available via the create credential API at the moment.

Endpoint Configurations

Endpoint configurations define reusable pieces of functionality that can be applied to any number of reserved domains or reserved addresses on your account.

Endpoint configurations are comprised of one or more modules. Each module defines a piece of functionality that will be executed on traffic that transits through any domain or address that you attach the endpoint configuration to. Each module defines its own set of configuration options and may be managed independently via its own API resources. Modules can perform authentication, performance optimizations like compression, enrich requests, handle errors, enforce policy and more.

Endpoint Configuration Types

Every endpoint configuration must be defined with a type. The type determines both which modules may be added to the configuration as well as how the configuration may be attached to a reserved domain or reserved address. The documentation for each module will list the configuration types it may be added to.

There are currently three types of endpoint configurations: http, https, and tcp.

Attaching to Reserved Domains and Addresses

Endpoint configurations may be attached to any number of reserved domains or addresses. When the configuration is attached, that domain or address will start applying the configuration's modules to traffic that transits through any tunnels started on those domains or addresses.

Reserved domains have two endpoint configuration references: http_endpoint_configuration_id and https_endpoint_configuration_id. These govern how http and https traffic are handled, respectively. The type of configuration that you attach must be http and https, respectively, for those references.

Reserved addresses have a single endpoint configuration reference endpoint_configuration_id. This configuration reference must be of type tcp.

Changes to HTTP Traffic

Traffic that is handled by endpoint configurations goes through a new codepath in ngrok's edge servers. This new codepath has a few subtle changes to how HTTP traffic is handled that are enumerated below:

Header Casing

HTTP headers the backend sees now have their capitalization canonicalized. The HTTP RFC defines this change as compatible. Previously,

curl --header “foo-BAR: baz” foo.ngrok.io

foo-BAR: baz

Foo-Bar: baz

Header Ordering

HTTP headers now may be reordered whereas ngrok previously never re-ordered headers. The HTTP RFC defines this behavior as compatible.

X-Forwarded-For

If an X-Forwarded-For header was supplied by the caller, ngrok now combines those values in a single header field. The RFC describing X-Forwarded-For describes this as the intended behavior. Previously,

curl --header “X-Forwarded-For: 1.2.3.4” foo.ngrok.io

X-Forwarded-For: 1.2.3.4
X-Forwarded-For: 5.6.7.8

X-Forwarded-For: 1.2.3.4, 5.6.7.8

Stripped Hop-By-Hop Headers

ngrok used to pass through the following hop-by-hop headers. It will now strip them (and set its own values, if necessary).

• Keep-Alive
• Proxy-Connection
• Proxy-Authenticate
• Proxy-Authorization
• Trailer
• Transfer-Encoding
• Te

Endpoint Configuration Modules

Circuit Breaker

Supported on types: http, https

Circuit breakers are used to protect upstream servers by rejecting traffic to them when they become overwhelmed, allowing them time to recover back into a steady operational state. When the upstream server starts to fail requests at too high of a rate, the circuit is "opened".

The circuit breaker is an implementation of Netflix's Hystrix circuit breaker specification.

If the upstream server responds with more than the threshold percentage of requests with 50X status codes, the circuit breaker pre-emptively reject all subsequent requests at the ngrok edge with a 503 until the upstream server's error rate drops below the threshold percentage.

Compression

Supported on types: http, https

If an HTTP request includes an Accept-Encoding header, HTTP responses will be automatically compressed and a Content-Encoding response header will be added.

If the response was already compressed by the upstream server, ngrok takes no action.

gzip and deflate encodings are supported.

IP Policy

Supported on types: http, https, tcp

The IP Policy modules lets you restrict the allowed traffic to tunnel endpoints by explicitly whitelisting a set of IPs that are permitted to access those endpoints.

Allow connections to the tunnel endpoint only if the source IP of the connection matches an IP or IP range in any of the specified IP Policies. If multiple policies are specified, a connection will be allowed if it matches an IP address in any of the policies. Formally, the IP is checked against a union of all the IP policies.

The IP policy module is intended to replace and deprecate the existing IP Whitelist resource. Please read the documentation section about IP policy and IP whitelist interactions carefully.

Mutual TLS Authentication

Supported on type: https

Also known as "TLS client authentication", connections must complete a mutual TLS handshake in which the client presents a valid certificate signed by any of the root certificate authorities that you upload.

The Common Name of the client's TLS certificate is injected into the header X-Tls-Client-Cn that is sent to your application server. This allows you to identify the requesting client for purposes of group membership, permissioning, revocation checks, profile lookup, etc.

Root CAs must be specified in PEM format. You may specify multiple root CAs by concatenating them together.

OAuth

Supported on type: https

The OAuth module enforces an OAuth authentication flow in front of any endpoint it is enabled on. Any HTTP client accessing an OAuth-protected endpoint will be redirected to a chosen identity provider (currently Google, Microsoft, Github or Facebook) for authentication. When they are redirected back to the protected endpoint, ngrok will check a series of authorization constraints that allow you to define who is authorized to access the resource by setting a list of email addresses, email domains and other requirements. If the user is authorized, their request will be forwarded through to the upstream server and ngrok's edge will set an HTTP cookie on their browser session to keep them logged in so that the authentication flow is not repeated.

Configuration, customization, and use of the OAuth module is documented in the OAuth documentation section.

Request Headers

Supported on types: http, https

The Request Headers module allows you to add and remove headers from HTTP requests before they are sent to your upstream server.

Changes made to request headers will not be visible to other modules; they will only be seen by your upstream server.

Header addition and removal functions similarly for request and response headers. See HTTP Headers for more details.

Response Headers

Supported on types: http, https

The Response Headers module allows you to add and remove headers from HTTP responses before they are returned to the client. This is especially useful for enforcing the use of security headers on all responses returned by your application.

Changes made to response headers will not be visible to other modules; they will only be seen by the client.

Header addition and removal functions similarly for request and response headers. See HTTP Headers for more details.

TLS Termination

The TLS Termination module allows you to configure whether ngrok terminates TLS traffic at its edge or forwards the TLS traffic through unterminated, in which case the TLS traffic will need to be terminated by your application server (or by the ngrok agent).

If the TLS Termination module is not specified, the default behavior is to terminate all TLS traffic at the ngrok edge.

If the TLS Termination module is enabled and TLS termination has been disabled, then you must have the ngrok agent start a tls tunnel to receive traffic. Furthermore, if TLS termination is disabled, no other http or https modules (e.g. Compression, OAuth, etc) will be supported on this endpoint configuration.

If you update a configuration to change whether it terminates TLS traffic or not, all tunnels running with that configuration will immediately begin to fail requests. All tunnels started with that configuration will need to be stopped and then restarted with their protocol changed (either https -> tls or vice-versa.

Webhook Validation

Supported on types: http, https

The webhook validation module allows ngrok to assert requests to your endoint originate from a supported webhook provider like Slack or Github.

If ngrok can't validate a request as coming from the configured provider it will reject the request with a 403 status.

IP Policies

IP policies are a reusable group of whitelisted IPs or IP ranges (in CIDR blocks) that can be applied on a per-tunnel basis via Endpoint Configurations. An endpoint configuration may specify one or more IP policies. IP policies may be attached to any number of endpoint configurations. If an endpoint configuration specifies multiple IP policies, a connection will be allowed if its source IP matches any policy. Formally, the endpoint configuration defines a computed union of all of its IP policies.

IP Policy Rules

Every IP policy consists of zero or more IP policy rules. Each rule specifies an IP address or IP address range in CIDR notation. Both IPv4 and IPv6 address notations are supported. An IP policy with no rules is valid and will match no IPs.

Interaction with IP Whitelist

IP policies are intended to replace and deprecate the previous primitive ngrok used for IP enforcement, the IP whitelist. Unlike IP policies which must be explicitly associated with tunnels via an endpoint configuration, The IP whitelist is an account-wide primitive that applies to all tunnels on your account.

We do not recommend using both IP policies and the IP whitelist together. But, if you do, a connection will only be allowed through if it matches both the IP whitelist and the configured IP policies. Formally, for a connection to be accepted, it must match the intersection of both the IP whitelist and IP policies configured for the matching endpoint configuration.

TLS Certificates

ngrok supports uploading your own TLS certificates which we will use to terminate traffic to a given reserved domain at the ngrok edge. You may wish to use this functionality in addition to our automatically provisioned certificates if you are using an EV cert or provisioning certificates from your own certificate authority. Uploading a certificate will not change any traffic, you must then attach the certificate to a reserved domain by setting the certificate_id property on the reserved domain with the ID of the certificate you'd like to use for TLS termination.

Certificate Bundles

When uploading a new certificate to ngrok via the API, the certificate_pem field expects 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.

Certificate bundles are a series of PEM-encoded X.509 certificates that have been concatenated together in a specific order. A bundle will look like the following:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
      

The first certificate in the bundle must be the leaf certificate. You can think of the leaf certificate as the one which is signed for your domain and the private key you will upload.

After the leaf are the intermediates certificates, if any. Each intermediate signs the certificate preceding it in the bundle. As an example, the first intermediate will have signed the leaf, and that signature is part of the leaf certificate itself. The final certificate is signed by the root certificate. You may also included the root certificate in the bundle as well, but it is not necessary or common practice to do so.

Private Keys

ngrok accepts the following formats for the private_key_pem field:

• RSA, in either PKCS#1 or PKCS#8 form.
• ECDSA, in either SEC 1 or PKCS#8 form.
• Ed25519, in PKCS#8 form.

All of the above (PKCS#1, PKCS#8, and SEC 1) are represented with ASN.1 DER (a binary format), encoded as PEM.

ngrok will not accept any private keys that are encrypted (e.g. with DES)..

OAuth Authentication

This documentation assumes familiarity with OAuth 2.0 workflows and terminology.

OAuth authentication uses configurable constraints to restrict endpoint access to only authorized users. Upstream servers behind an OAuth-protected endpoint can safely assume that requests are from users authenticated with the provider and authorized to use the endpoint.

Google

Creating your own application

Step-by-step instructions below follow Google's documentation on setting up OAuth 2.0 for a web application.

Build the consent screen

1. Create or select a project on the Google Cloud Platform Console.
2. Navigate to the project's OAuth consent screen.
3. Select whether your application is an internal or external app.
4. Fill out the application name and support email.
5. Add additional scopes required by your application, saving the full scope URI for later.
   • Possible scope URIs
   .
6. Ensure that the email and profile scopes are still selected.
7. Under Authorized domains, add ngrok.com and your application homepage domain.
8. Add links to your application homepage and privacy policy. The final consent screen should resemble:
9. Save the application.
   • Applications that require verification cannot complete the consent screen and are not supported by ngrok.

Create credentials for ngrok

1. Navigate to Credentials for your project.
2. Select "Create credentials" from the top menu and select "OAuth Client ID".
3. Choose "Web application" from the list of application types.
4. Name your secret, then set "Authorized Redirect URIs" to https://oauth.ngrok.com/oauth2/callback. The final credentials form should resemble:
5. Securely store the Client ID and secret from the final screen:

Update your endpoint configuration

1. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
2. Choose to use your own application with Google as the provider.
3. Include the client ID, secret, and scopes configured in your application.
4. Add the following scopes to your application if they are not already present:
   • https://www.googleapis.com/auth/userinfo.profile
   • https://www.googleapis.com/auth/userinfo.email

Additional application setup information

• Google OAuth 2.0 Web Server (prerequisite steps)
• GCP Help: Setting up OAuth 2.0
• Google OAuth 2.0 workflow

Headers provided by ngrok

ngrok strips the following headers from authorized requests and sets them with data from Google:

Microsoft

Creating your own application

Step-by-step instructions below closely follow Microsoft documentation to create a new application for ngrok within the Azure portal.

Register an application

1. Sign-in to the Azure portal then select or create a tenant for your application.
2. Search for "Azure Active Directory" and select it.
3. Select "App registrations" on the left hand navigation.
4. Select "New registration" at the top.
5. Enter a name for your application.
6. ngrok does not support single tenant applications. Choose supported account types from:
   • Accounts in any organizational directory (Any Azure AD directory - Multitenant)
   • Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
7. Choose a "Web" redirect URI and enter https://oauth.ngrok.com/oauth2/callback.
8. Register your application. The final form should resemble:

Configure your application

1. When viewing your application, choose "Overview" on the left hand navigation.
2. Store the "Application (client) ID" in the top information section for later.
3. Select "API permissions" on the left hand navigation.
4. Add additional scopes that your application requires and store them for later.
   • Scopes which require an application review by Microsoft are unsupported.
   • Scopes that require admin consent prevent tenants' users from authorizing until consent is granted.
5. Ensure User.Read or a more permissive scope (e.g. User.Read.All) is configured for ngrok. Example minimal configuration:
6. Choose "Certificates and Secrets" on the left hand navigation.
7. Select "New Client Secret" at the bottom, name the secret, set an expiration, and hit create.
8. Creation is asynchronous. When complete, save the secret from the "Value" column (blurred below) for later:

Update your endpoint configuration

1. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
2. Choose to use your own application with Microsoft as the provider.
3. Include the scopes, client ID, and client secret for your application.

Additional application setup information

• Creating an Azure AD tenant
• Permissions and consent (restricted permissions)
• Graph API User object properties (id, displayName, and mail/userPrincipalName)

Headers provided by ngrok

ngrok strips the following headers from authorized requests and sets them with data from Microsoft:

GitHub

Creating your own OAuth application

1. Follow GitHub's documentation until the final step of submitting the registration form.
2. Set the Authorization callback URL to https://oauth.ngrok.com/oauth2/callback.
3. Submit the form. A working example registration:
4. Save the client ID and client secret from the application overview:
5. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
6. Choose to use your own application with GitHub as the provider.
7. Include the client ID and secret from earlier.
8. Add any scopes your application requires.
   • Include the read:user scope (or more permissive, like user) for ngrok.
9. Add any team or organization constraints by the their mention handle(s), excluding the @ prefix.
   • For example, the ngrok organization's mention handle is @ngrok, so the organization constraint would be ngrok. Similarly, the @ngrok/developers team would be matched by the constraint ngrok/developers.
   • If a constraint is specified, the read:org scope is required. A more permissive scope, such as org, also works.
   • Organizations must allow third-party access to your app.

Headers provided by ngrok

ngrok strips the following headers from authorized requests and sets them with data from GitHub:

Using Organization and Teams

To authorize users based on organization or team membership, the organization must allow third party access. There are multiple ways to grant access:

• Organizations may allow unrestricted third-party access from settings.
• Owners can grant access to an application during authorization.
• Members can request access as part of authorization.
• Members can request access from settings.

The ngrok managed application can authorize users based on organization or team. For organizations concerned about membership privacy, your own application should always be used. When granting third-party access to the managed application, anyone using the managed application may constrain based on your organization's membership.

Header presence and constraint ordering

Organization and team headers are present only when an organization or team constraint matches. For example, an endpoint constrained solely on the ngrok organization will always have authorized users with the ngrok organization header. An endpoint without any organization or team constraints will receive no organization or team header.

ngrok authorizes against users' first 200 memberships of each constraint in chronological order of the team or organization's creation. Headers are filled from the first user data match in order:

1. From any team membership, check the parent organization.
2. Check team membership.
3. Check organization membership.

Facebook

Creating your own application

Register an application

For additional assistance, see the Facebook app registration documentation.

1. Visit the App Dashboard, log in, and convert your account into a developer account if necessary.
2. Select "Add a New App" or "Create App."
3. Choose a user-visible name and contact email.
4. Submit the form. A valid example app:

Configure your application

1. After creation, you should see a list of products to add. If you don't, view your application from the dashboard and scroll down to "Add a product."
2. Select "Set Up" for Facebook Login.
3. On the left hand navigation, select Facebook Login then choose "Settings" below it.
4. Add to "Valid OAuth Redirect URI" https://oauth.ngrok.com/oauth2/callback
5. Save the Facebook Login settings page. Final configuration should match:
6. Select Settings on the left hand navigation, then choose advanced.
7. Fill out additional settings for your application.
   • ngrok does not support Server IP whitelisting.
8. Enable "Require App Secret". See documentation for how to call Facebook Graph API with this feature.
9. Save settings. A minimally complete security section of advanced settings:
10. Visit basic settings on the left hand navigation.
11. At the top, save your App ID and App Secret for later.
12. Fill out the privacy policy URL. This URL must accessible when entered for verification.
13. Select a category for your application.
14. Hit save changes. A minimally complete basic settings:
15. Select the toggle for "In development" at the top of the page and confirm switching to live mode.
16. Your application should now show as live:

Update your endpoint configuration

1. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
2. Choose to use your own application with Facebook as the provider.
3. Include the app id and app secret that were stored earlier.
4. Add any scopes required by your application.
   • Scopes which require a Facebook app review are unsupported.
   • ngrok will enforce that users accept all permissions before completing authorization.
5. Add the email scope if it is not already present.

Additional application setup information

• Handling declined permissions
• App review
• App secret proof

Headers provided by ngrok

ngrok strips the following headers from authorized requests and sets them with data from Facebook's user API:

User permission revocation

Facebook allows revocation of any permission as part of the authorization flow. ngrok will enforce that users initially grant all configured permissions. However, at any time after endpoint authorization, users may selectively revoke permissions. If your application requires more than the default or email scope, you must follow Facebook's rules for handling revoked permissions without violating terms of use.

Managed Application Limitations

Managed OAuth applications are owned by ngrok and intended for quick use or testing. We highly recommend that you bring your own application. There are limitations on managed application since since many endpoints share them:

• User access tokens are not provided.
• Custom scopes are not allowed.
• At least 1 email address or 1 email domain must be specified.
• Common email domains are not allowed (e.g. gmail.com, yahoo.com).

Request Modifications

Paths

Upstream servers behind endpoints protected by OAuth should not expect to receive any paths beginning with /oauth2/. Although more paths may be added, the following paths are currently used by ngrok:

Cookies

ngrok uses cookies to secure the authorization workflow, store user credentials, and cache authorized user data for headers. Cookie values should be considered opaque and not modified. Cookies names are prefixed with ngrok. by default. ngrok may overwrite, modify, hide, or delete prefixed cookies with the names below as part of every request:

Constraint Changes and Sessions

OAuth endpoint configuration uses a cookie-based session. Consider the following when changing authorization constraints:

• Cookies are client-side and available only when users make requests.
• Users may successfully authorize, then visit again after any amount of time.
• Once authorized, reauthorization occurs after the currently configured authorization check interval or when the endpoint configuration changes.
• Sessions are tied to the OAuth client ID and OAuth provider from which they were created.
• Sessions are not shared between domain names.

Authorization Check Interval

Authorization check interval controls the frequency of the refresh phase of the OAuth workflow. In order to prevent abuse, refreshes have minimum frequency of once per 3 minutes.

When configuring an authorization check interval, note that long intervals will result in delayed authorization against changed provider data. This has security considerations, especially when revoking permissions. For example, with an authorization check interval of 1 day, the following is possible:

1. Day 1 08:00: user makes a request and successfully authorizes.
2. Day 1 10:00: the authorized GitHub organization removes the user.
3. Day 1 11:00: user successfully accesses the tunnel.
4. Day 2 08:30: user accesses the tunnel, reauthorizes, and is denied access.

• Updating the authorization check interval to less than two hours.
  • The default interval is 3 minutes.
• Changing the OAuth provider or provider's client ID.
• Modifying the endpoint configuration.
• Redirecting the user to /oauth2/authorize.

Detailed Auth Workflow

OAuth authentication is best separated into a three phase workflow: capture, callback, and refresh.

Capture

Requests were not previously authorized enter the capture phase and begin OAuth2. ngrok redirects the user to the provider with a secret state. The state is used to store the initial request URI, or capture URI, with additional security data. State expires 30 minutes from capture and will allow users to retry on expiration, discarding the original capture URI in order to prevent replays.

Methods other than GET also trigger capture; discarding the request body and method in the process. After successful authentication and authorization, users are redirected with a 302 and perform a GET against the capture URI.

Callback

Callback occurs as the final user-facing phase. There are up to three redirects made: the provider initiated redirect to the common callback forwarder, a redirect back to the initial domain, and a final redirect to the initial capture URI.

As endpoint configurations may be used across many domains, the common callback forwarder serves as a secure proxy back to the originating domain. Except in cases where the state query parameter was modified or discarded, this redirect is transparent to the user.

On the originating domain at /oauth2/callback, the request state is verified, errors are handled, and OAuth is completed. Errors from the provider are displayed to the user with instructions for how to continue. If no errors occur, a session is written to the session cookie, by default ngrok.session, and users are redirected to the capture URI.

Refresh

Users that complete provider authorization always complete at least one data refresh. Afterward, this phase is repeated based on authorization check interval. Refresh populates headers and performs authorization with data from the provider.

If endpoint authorization fails with data from a refresh, granted OAuth credentials from the provider are retained. Unauthorized users are notified to contact the owner of the application to request access. Subsequent requests repeat the refresh phase until the maximum session lifetime is reached, the grant expires, or endpoint authorization is updated to allow them.

HTTP Headers

The Request Headers and Response Headers modules use the same semantics for header additions and removals.

Headers to add are specified as key/value pairs. Headers to remove are specified as a list of header names. Header names for both additions and removals will be canonicalized per the Changes to HTTP Traffic.

If an added header already exists, the header will appear multiple times; the original header value will not be overwritten.

If a header is specified for both addition and removal, the original value will first be removed and the new value used in its place.

Header Templates

Variables can be interpolated into a header value using JSONPath expressions surrounded by ${} syntax. For example, using ${.ngrok.request_id} as a header value will cause it to be filled in with the ngrok-generated Request ID.

At this time, the object used for variable lookup contains the following values:

{
    "ngrok": {
      // ngrok-generated Request Id
      "request_id": "...",
      // original client IP
      "client_ip": "...",
      "geo": {
        // two-letter ISO country code based on the client IP
        "country_code": "...",
        // approximate latitude based on the client IP
        "latitude": "...",
        // approximate longitude based on the client IP
        "longitude": "...",
        // the radius in kilometers around the latitude and longitude
        // where the client IP is likely to originate from
        "lat_long_radius_km": "..."
      }
    }
} 

The ngrok.com HTTP API

We expose an HTTP API that grants programmatic access to all of ngrok's resources.

A basic understanding of ngrok and its features is strongly encouraged before using this API: the ngrok.com HTTP API.

Errors

When something goes wrong, we report an error code: in the agent, our REST API, or at our edge.

You can see a comprehensive list of those errors in our error index.