Skip to main content

URL Rewrite

Overview​

The URL Rewrite Traffic Policy action enables you to modify the incoming request URL using regular expressions before it reaches the upstream server, without changing the URL seen by the client.

This action is useful for routing users without exposing internal system details.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Action Type​

url-rewrite

Configuration Fields​

ParameterTypeDescription
fromstringRequired. A regular expression string to match inside of the URL. Supports CEL Interpolation.
tostringRequired. A regular expression string to replace the from match with. Supports CEL Interpolation.
formatstringDetermines interpolation format in to/from fields. Default ngrok.

Supported Phases​

  • on_http_request

Supported Schemes​

  • https
  • http

Behavior​

This action replaces all matches of thefrom regular expression in the request URL with theto replacement value.

Matching​

Matching is done against the full URL, including the scheme, userinfo, host, and port, not just the path.

To match requests that start with /products you must use CEL Interpolation and write ^${req.url.authority}/products or use an expression like req.url.path.startsWith('/products') in the policy rule expressions field.

CEL Interpolation​

You can access Traffic Policy variables and embed CEL expressions in this actions configuration values using CEL Interpolation in the form of ${expression}. Check out the examples below to see how CEL Interpolation works.

Note: All CEL Interpolation will occur before regular expressions are evaluated.

For a complete list of variables and how to write expressions, see Expressions and Variables documentation.

Examples​

Rewrite using Paths​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products to /products.php.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path == '/products'"
    actions:
      - type: "url-rewrite"
        config:
          from: "/products"
          to: "/products.php"

This configuration will rewrite any request to /products to /products.php without changing the URL seen by the client. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products
HTTP/2 200 OK
Example Server Logs​
GET /product.php               200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php, and the response is served from products.php while the client remains unaware of the URL rewrite.

Rewrite using Regular Expressions​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products/* to /products.php.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path.startsWith('/products')"
    actions:
      - type: "url-rewrite"
        config:
          from: "/products/?([.*]+)?"
          to: "/products.php?query=$1"

This configuration will rewrite any request to /products/* to /products.php?query=$1 without changing the URL seen by the client. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products/123
HTTP/2 200 OK
Example Server Logs​
GET /product.php?query=123          200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php?query=123, and the response is served from products.php while the client remains unaware of the URL rewrite.

Rewrite using CEL Interpolation​

The following Traffic Policy configuration demonstrates how to use the url-rewrite action to transparently rewrite the request URL from /products/* to /products.php using a global policy rule (no expression) by leveraging CEL Interpolation.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "url-rewrite"
        config:
          from: "${req.url.authority}/products/?([.*]+)?"
          to: "/products.php?query=$1"

This configuration will rewrite any request urls that start with /products/* to /products.php?query=$1 without changing the URL seen by the client. It does this by leveraging CEL Interpolation to replace the from value with the request URL authority. This is useful for hiding away the underlying implementation details of your service.

Example Request​

$ curl -i https://example.ngrok.app/products/123
HTTP/2 200 OK
Example Server Logs​
GET /product.php?query=123          200 OK

Conclusion​

In this example, a request to /products is internally routed to /products.php?query=123, and the response is served from products.php while the client remains unaware of the URL rewrite.

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.

NameTypeDescription
actions.ngrok.url_rewrite.matches[]stringList of matched elements.
actions.ngrok.url_rewrite.urlstringThe resulting URL after it was re-written.
actions.ngrok.url_rewrite.error.codestringCode for an error that occurred during the invocation of an action.
actions.ngrok.url_rewrite.error.messagestringMessage for an error that occurred during the invocation of an action.