Redirect

Overview

The Redirect policy action enables transforming your URL using regular expressions and redirect through location header.

Example

YAML

actions:
  - type: redirect
    config:
      from: v0/user/([0-9]+).*
      to: v1/user?id=$1&$args
      status_code: 301
      headers:
        rewrite: "true"

JSON

{
  "actions": [
    {
      "type": "redirect",
      "config": {
        "from": "v0/user/([0-9]+).*",
        "to": "v1/user?id=$1&$args",
        "status_code": 301,
        "headers": {
          "rewrite": "true"
        }
      }
    }
  ]
}

Behavior

When executed this action will abort the request and replace all matches on the inbound URL with the configured replacements. Before regular expression replacement occurs, all named variables will be replaced with their corresponding values.

Reference

Supported Directions

• Inbound

Configuration

Type
redirect

Parameter		Description
from	string	A regular expression string to match inside of the URL.
to	string	A regular expression string to replace the from match with. Also contains special named variables outside of regular regex.
status_code	int	3xx status code used for redirecting, 302 by default.
headers	Map<string, string>	Headers to be added to the request.

Named Variables

Keyword	Description
$args	Replaces $args with a list of "&" delimited query parameters: "args1=value1&arg2=value2&...&argn=valuen"
$authority	Replaces $authority with the hostpost of the request url.
$query_string	Replaces $query_string with a list of "&" delimited query parameters: "args1=value1&arg2=value2&...&argn=valuen"
$is_args	Replaces $is_args with "?" if args are present, "" if not.
$uri	Replaces $uri with the request URI: path?query.
$arg_<name>	Replaces $arg_name with the value of query parameter name if it exists in the request, "" if not. name must only be comprised of digits, letters, and the "_" character. If there is more than one value assigned to name, only the first value will be substituted.
$scheme	Replaces $scheme with the scheme of the request, either http or https.
$host	Replaces $host with the host of the request url.
$port	Replaces $port with the port of the request url.
$user	Replaces $user with the user information of the request.
$is_user	Replaces $is_user with an "@" when user is not empty.

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.

YAML

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

JSON

{
  "actions": [
    {
      "type": {
        "type": "redirect"
      },
      "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.