Skip to main content

Traffic Policy Actions Reference

Add Headers​

The Add Headers Traffic Policy action enables you to add headers to an HTTP request before it is sent upstream or an HTTP response before it is sent back to the client.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

add-headers

Configuration Fields​

  • headersobjectCEL

    Map of header key to header value to be added.

    Minimum 1, Maximum 10.

    Supports CEL Interpolation in header values.

Behavior​

When configured in the on_http_request phase, this action will add the specified headers to incoming http requests before reaching the upstream server. When configured in the on_http_response phase, the specified headers are added to the http response from the upstream server.

Addition Only​

This action will only add headers to the request or response. If the header already exists it will append another header with the same key unless it is the host header, see Special Cases.

To replace or remove headers use the remove-headers action then add the header with the desired value.

Case Sensitivity​

Header keys added through this action are normalized to lowercase per the HTTP/2 specification.

Ordering​

Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action after them in your traffic policy document.

Special Cases​

  • Adding the host header override the existing value instead of appending another header.
  • You may not add or remove the user-agent header.
  • You may not use this action to add the ngrok-skip-browser-warning header to skip the ngrok browser warning on free accounts. For more information, check out the free plan limits guide.

Examples​

Adding Client IP Headers to all HTTP requests​

The following Traffic Policy configuration will add the client IP address to all HTTP requests.

Example Traffic Policy Document​
Loading…

For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org and we are adding the following header to all requests:

  • x-client-ip with the value ${conn.client_ip} to demonstrate the use of CEL interpolation to include the client IP address.

Example Request​

Loading…
Loading…

Adding headers to an HTTP response​

The following Traffic Policy configuration will add headers to the response from the upstream service when the method is GET and the URL starts with /status/200.

Example Traffic Policy Document​
Loading…

For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org and we will be adding two headers:

  • x-custom-header with the value my-custom-value
  • x-string-interpolation-example with the value started at ${conn.ts.start} to demonstrate the use of CEL interpolation to include the request connection start time.

Example Request​

Loading…
Loading…

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.

  • actions.ngrok.add_headers.headers_addedobject

    Map of headers that were added by the action.

Basic Auth​

The Basic Auth Traffic Policy action enables you to enforce HTTP Basic Auth on your endpoints. Requests with a valid username and password will be sent to your upstream service, all others will be rejected with a 401 Unauthorized response.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

basic-auth

Configuration Fields​

  • credentialsarray of stringsRequired

    A list of up to 10 allowed username:password credential pairs.

    Password must be at least 8 characters and no more than 128 characters.

  • realmstring

    The HTTP realm of the request as per RFC 7235.

    Default is ngrok.

  • enforcebool

    Default true. If false, continue to the next action even if basic authentication failed. This is useful for handling fall-through, debugging, and testing purposes.

Behavior​

The basic-auth action enforces HTTP Basic Authentication on incoming requests, as specified in RFC 7235. When a request is received, the action verifies the request by validating against a known set of user:password credentials. If the verification is successful, the action allows the request to continue through the action chain and finally to your application; if verification fails, the request will be terminated with a 401 Unauthorized response.

Additional Restrictions​

You can specify up to 10 username:password pairs. The password must be at least 8 characters and no more than 128 characters. Including multiple colons in the username:password pair will result in the first colon being treated as the delimiter between the username and password. Realm cannot exceed 128 characters, and cannot contain non-ASCII characters.

Verification Process​

  • HTTP Authentication: The action validates incoming HTTP requests to confirm they contain the required Authorization header, in the form of Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of username and password joined by a single colon :.
  • Request Handling: If the authentication is successful, the request is forwarded to the next action. If the authentication fails, it will return to user a 401 response, which will prompt the user to provide a correct set of credentials.
  • Configurable Enforcement: By default, authentication failures result in 401s. However, setting enforce: false allows unauthenticated requests to proceed, while logging the authentication result. This option is for debugging and testing.

Secret Handling and Encryption​

All secrets used for basic authentication are encrypted at config validation. When ngrok processes a request, the secret is decrypted.

Examples​

Basic Example​

The following Traffic Policy configuration is an example configuration of the basic-auth action.

Example Traffic Policy Document​

Loading…

Example Request​

First, base64 encode the username:password pair. user:password1 becomes dXNlcjpwYXNzd29yZDE=

Loading…
Loading…

In this example, we are sending a request to our API with a valid set of credentials in the Authorization header with the Basic prefix and getting back a 200 OK response.

You can try it without the header, and you will receive a 401 Unauthorized prompt instead.

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.

  • actions.ngrok.basic_auth.credentials.presentedbool

    Whether there were Basic Auth credentials presented in the Authorization header.

  • actions.ngrok.basic_auth.credentials.usernamestring

    The username of the credentials presented.

  • actions.ngrok.basic_auth.credentials.authorizedbool

    Whether the presented basic auth credentials were authorized for this request.