Skip to main content

Add Headers

Overview​

The Add Headers policy action enables the addition of headers to both inbound requests and outbound responses.

Example​

actions:
  - type: add-headers
    config:
      headers:
        is-ngrok: "1"
        country: ${.ngrok.geo.country_code}

Behavior​

When executed as an inbound policy, this action will add headers on an incoming http request before reaching the upstream server with the configured headers. When executed as an outbound policy, the configured headers are added to the response from the upstream server.

Reference​

Supported Directions​

  • Inbound
  • Outbound

Configuration​

Type
add-headers
Parameter Description
headersMap<string, string>Headers to be added to the either the request or response.

Variable Interpolation

You may interpolate variables into header values. Variables are interpolated into headers with JSONPath expressions surrounded by ${} syntax.

For example, to include geographical data about the client IP that initiated the request, you may construct a header value like so.

actions:
  - type:
      type: add-headers
    config:
      headers:
        country: ${.ngrok.geo.country_code}

Consult the Variables Reference for the available variables.

Variables​

ngrok makes variables available for interpolation into headers.

Some variables will only be populated with values if you have configured the corresponding module for your endpoint, otherwise they will be empty. For example, the variable ${.basic_auth.username} is only available if you have enabled the basic auth module on your endpoint.

Backend Variables​

${.backend.connection_reused}True if ngrok reused a TCP connection to transmit the HTTP request to the upstream service.
${.backend.dial_duration}The time to establish a connection from ngrok to the agent.
${.backend.id}This is the ngrok ID of the backend that serviced this request. This is empty if the endpoint is not handled by an Edge.

Basic Auth Variables​

These variables are only populated when using the Basic Auth module.

${.basic_auth.decision}allow if the request successfully authenticated via the Basic Auth module, block otherwise.
${.basic_auth.username}If the request successfully authenticated via the Basic Auth module, this is the username that authenticated.

Circuit Breaker Variables​

These variables are only available when using the Circuit Breaker module.

${.circuit_breaker.decision}Whether the HTTP request was sent to the upstream service. allow if the breaker was closed, block if the breaker was open, allow_while_open if the request was allowed while the breaker is open.

Compression Variables​

These variables are only populated when using the Compression module.

${.compression.algorithm}The compression algorithm used to encode responses from the endpoint. Either gzip, deflate, or none.
${.compression.bytes_saved}The difference between the size of the raw response and the size of the response as compressed by ngrok.

Connection Variables​

${.conn.bytes_in}The number of bytes arriving at an endpoint from the frontend.
${.conn.bytes_out}The number of bytes leaving an endpoint to the frontend.
${.conn.client_ip}The source IP of the TCP connection to the ngrok edge.
${.conn.duration}The total duration (in seconds) of the TCP connection between the ngrok endpoint and the agent.
${.conn.end_ts}The timestamp when the TCP connection to the ngrok edge is closed.
${.conn.id}The ngrok ID for this TCP connection.
${.conn.server_ip}The IP address of the server that received the request.
${.conn.server_name}The hostname associated with this connection.
${.conn.server_port}The port that the connection for this request came in on.
${.conn.start_ts}The timestamp when the TCP connection to the ngrok edge is established.

Geo IP Variables​

The source of this data is subject to change. It is currently provided by MaxMind GeoIP.

${.ngrok.geo.country_code}This is the two-letter ISO country code based on the client IP.
${.ngrok.geo.lat_long_radius_km}This is the radius in kilometers around the latitude and longitude where the client IP is likely to originate.
${.ngrok.geo.latitude}This is the approximate latitude based on the client IP.
${.ngrok.geo.longitude}This is the approximate longitude based on the client IP.

HTTP Variables​

${.http.request_id}The unique ngrok-assigned ID of this request.
${.http.request.method}The request method, normalized to uppercase.
${.http.request.url.host}The host component of the request URL.
${.http.request.url.path}The path component of the request URL
${.http.request.url.query}The query string component of the request URL
${.http.request.url.raw}The full URL of the request including scheme, host, path, and query string.
${.http.request.url.scheme}The scheme component of the request URL.
${.http.request.user_agent}The value of the User-Agent header in the request received by ngrok edge.
${.http.request.version}The HTTP version used in the request.
${.http.response.status_code}The status code of the response returned by the ngrok edge.

IP Restrictions Variables​

These variables are only populated when using the IP Restrictions module.

${.ip_policy.decision}allow if IP Policy module permitted the request to the upstream service, block otherwise.
${.ip_policy.matching_rule}The rule that triggered an IP Policy match on the endpoint.

Mutual TLS​

These variables are only populated when using the Mutual TLS module.

${.tls.client_cert.serial_number}The serial number of the client's leaf TLS certificate in the Mutual TLS handshake.
${.tls.client_cert.subject.cn}The subject common name of the client's leaf TLS certificate in the Mutual TLS handshake.
${.tls.client_cert.subject}The subject of the client's leaf TLS certificate in the Mutual TLS handshake

ngrok Variables​

${.ngrok.client_ip}This is the original client IP of the request.
${.ngrok.request_id}This is the unique request ID generated by ngrok

OAuth Variables​

These variables are only populated when using the OAuth module.

${.oauth.app_client_id}The is the ID of the OAuth2 application used to handle this request.
${.oauth.decision}'allow' if the OAuth module permitted the request to the upstream service, 'block' otherwise.
${.oauth.user.email}This is the email address of the user that was authenticated.
${.oauth.user.id}The authenticated user's ID returned by the OAuth provider.
${.oauth.user.name}The authenticated user's name returned by the OAuth provider.

OpenID Connect Variables​

These variables are only populated when using the OpenID Connect module. These variables are identical to the OAuth Variables.

${.oauth.app_client_id}The is the ID of the OAuth application used to handle this request.
${.oauth.decision}allow if the OpenID Connect module permitted the request to the upstream service, block otherwise.
${.oauth.user.email}This is the email address of the user that was authenticated.
${.oauth.user.id}The authenticated user's ID returned by the OpenID Connect provider.
${.oauth.user.name}The authenticated user's name returned by the OpenID Connect provider.

SAML Variables​

These variables are only populated when using the SAML module.

${.ngrok.saml.subject}The SAML subject of the the authenticated user.

TLS Termination Variables​

These variables are only populated on requests to HTTPS endpoints.

${.tls.cipher_suite}The cipher suite selected during the TLS handshake.
${.tls.version}The version of the TLS protocol used between the client and the ngrok edge.

Webhook Verification Variables​

These variables are only populated when using the Webhook Verification module.

${.webhook_validation.decision}'allow' if the Webhook Verification module permitted the request to the upstream service, 'block' otherwise.