Skip to main content

Rule Gallery

Explore a curated collection of example configurations spanning from common to unconventional use cases for the Traffic Policy module.

A number of these examples come from a longer article about how ngrok makes policy management accessible to developers, including a simple Go-based application for testing these and other configurations.

See the following categories for specific expressions and actions:

Authentication​

Add JWT authentication and key-based rate limiting​

Building from our Auth0 guide, these rules also add rate limiting based on your consumers' JWTs.

# snippet
---
on_http_request:
  - expressions: []
    name: Add JWT authentication and rate limiting
    actions:
      - type: rate-limit
        config:
          name: Only allow 30 requests per minute
          algorithm: sliding_window
          capacity: 30
          rate: 60s
          bucket_key:
            - req.headers['x-api-key']
      - type: jwt-validation
        config:
          issuer:
            allow_list:
              - value: https://<YOUR-AUTH-PROVIDER>
          audience:
            allow_list:
              - value: <YOUR-NGROK-DOMAIN>
          http:
            tokens:
              - type: jwt
                method: header
                name: Authorization
                prefix: "Bearer "
          jws:
            allowed_algorithms:
              - RS256
            keys:
              sources:
                additional_jkus:
                  - https://<YOUR-AUTH-PROVIDER>/.well-known/jwks.json
on_http_response: []

Rate limiting​

Rate limit for specific endpoint​

This rule applies rate limiting of 30 requests per second to the endpoint /api/videos.

# snippet
---
on_http_request:
  - expressions:
      - req.url.contains('/api/specific_endpoint')
    actions:
      - type: rate-limit
        config:
          name: Only allow 30 requests per minute
          algorithm: sliding_window
          capacity: 30
          rate: 60s
          bucket_key:
            - conn.client_ip

Rate limit API consumers based on authentication status​

Create a low rate limit for unauthenticated (likely free) users, while allowing authenticated users a higher level of capacity.

# snippet
---
on_http_request:
  - expressions:
      - "!('Authorization' in req.headers)"
    name: Unauthorized rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 10 requests per minute
          algorithm: sliding_window
          capacity: 10
          rate: 60s
          bucket_key:
            - conn.client_ip
  - expressions:
      - ('Authorization' in req.headers)
    name: Authorized rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 100 requests per minute
          algorithm: sliding_window
          capacity: 100
          rate: 60s
          bucket_key:
            - conn.client_ip
on_http_response: []

Rate limit API consumers based on pricing tiers​

Using a naming scheme in your upstream servers, and API calls using a tier header, you can quickly customize access to your API based on any number of pricing tiers.

# snippet
---
on_http_request:
  - expressions:
      - "!('Tier' in req.headers)"
    name: Free rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 10 requests per minute
          algorithm: sliding_window
          capacity: 10
          rate: 60s
          bucket_key:
            - conn.client_ip
  - expressions:
      - getReqHeader('tier').exists(v, v.matches('(?i)bronze'))
    name: Bronze rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 100 requests per minute
          algorithm: sliding_window
          capacity: 100
          rate: 60s
          bucket_key:
            - conn.client_ip
  - expressions:
      - getReqHeader('tier').exists(v, v.matches('(?i)silver'))
    name: Bronze rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 1000 requests per minute
          algorithm: sliding_window
          capacity: 1000
          rate: 60s
          bucket_key:
            - conn.client_ip
  - expressions:
      - getReqHeader('tier').exists(v, v.matches('(?i)gold'))
    name: Gold rate limiting tier
    actions:
      - type: rate-limit
        config:
          name: Allow 10000 requests per minute
          algorithm: sliding_window
          capacity: 10000
          rate: 60s
          bucket_key:
            - conn.client_ip
on_http_response: []

Block unwanted requests​

Disallow bots and crawlers with a robots.txt​

This rule returns a custom response with a robots.txt file to deny search engine or AI crawlers on all paths.

# snippet
---
on_http_request:
  - name: Add `robots.txt` to deny all bots and crawlers
    expressions:
      - req.url.contains('/robots.txt')
    actions:
      - type: custom-response
        config:
          status_code: 200
          content: "User-agent: *\r\nDisallow: /"
          headers:
            content-type: text/plain

You can also extend the expression above to create specific rules for crawlers based on their user agent strings, like ChatGPT-User and GPTBot.

# snippet
---
on_http_request:
  - name: Add `robots.txt` to deny specific bots and crawlers
    expressions:
      - req.url.contains('/robots.txt')
    actions:
      - type: custom-response
        config:
          status_code: 200
          content: "User-agent: ChatGPT-User\\r\\nDisallow: /"
          headers:
            content-type: text/plain

Block bots and crawlers by user agent​

In addition to, or instead of, denying bots and crawlers with a robots.txt file, you can also take action on only incoming requests that contain specific strings in the req.user_agent request variable.

You can extend the expression to include additional user agents by extending (chatgpt-user|gptbot) like so: (chatgpt-user|gptbot|anthropic|claude|any|other|user-agent|goes|here).

# snippet
---
on_http_request:
  - name: Block specific bots by user agent
    expressions:
      - req.user_agent.matches('(?i).*(chatgpt-user|gptbot)/\\d+.*')
    actions:
      - type: deny
        config:
          status_code: 404

Deny non-GET requests​

This rule denies all inbound traffic that is not a GET request.

# snippet
---
on_http_request:
  - expressions:
      - req.method != 'GET'
    actions:
      - type: deny

Custom response for unauthorized requests​

This rule sends a custom response with status code 401 and body Unauthorized for requests without an Authorization header.

# snippet
---
on_http_request:
  - expressions:
      - "!('authorization' in req.headers)"
    actions:
      - type: custom-response
        config:
          status_code: 401
          content: Unauthorized

Block traffic from specific countries​

Remain compliant with data regulations or sanctions by blocking requests originating from one or more countries using their respective ISO country codes.

# snippet
---
on_http_request:
  - expressions:
      - conn.geo.country_code in ['<COUNTRY-01>', '<COUNTRY-02>']
    name: Block traffic from unwanted countries
    actions:
      - type: custom-response
        config:
          status_code: 401
          content: Unauthorized request due to country of origin
on_http_response: []

Limit request sizes​

Prevent excessively large user uploads, like text or images, that might cause performance or availability issues for your upstream service.

# snippet
---
on_http_request:
  - expressions:
      - req.method == 'POST' || req.method == 'PUT'
      - req.content_length >= 1000
    name: Block POST/PUT requests of excessive length
    actions:
      - type: custom-response
        config:
          status_code: 400
          content: "Error: content length"
on_http_response: []

Other​

User agent filtering​

We deliver tailored content to Microsoft Edge users by examining the User-Agent header for the case-insensitive string (?i)edg/ succeeded by digits \d. To see how this works in practice, explore the following regex101 demonstration.

To ensure correct decoding from YAML/JSON, it's necessary to properly escape the \d sequence. In YAML, if your string is not enclosed in quotes, use a single escape: \\d. However, when your string is wrapped in quotes, either in YAML or JSON, you need to double-escape: \\\\d for accurate decoding.

# snippet
---
on_http_request:
  - expressions:
      - "'user-agent' in req.headers"
      - size(req.headers['user-agent'].filter(x, x.matches('(?i).*Edg/\\d+.*')))
        > 0
    actions:
      - type: custom-response
        config:
          status_code: 200
          content: Hello Edge User!

Deprecate an API version​

By include a X-Api-Version header in your API reference or developer documentation, you can quickly return a helpful error message, which encourages them to explore usage of the new version.

# snippet
---
on_http_request:
  - expressions:
      - "'2' in req.headers['X-Api-Version']"
    name: Deprecate API v2
    actions:
      - type: custom-response
        config:
          status_code: 400
          content: '{"error":{"message":"Version 2 of the API is no longer supported. Use
            Version 3 instead."}}'
on_http_response: []

Manipulate request headers​

Add new headers to requests to give your upstream service more context about the consumer, which in turn allows for richer functionality, such as localized languages and pricing.

# snippet
---
on_http_request:
  - expressions: []
    name: Add headers to requests
    actions:
      - type: add-headers
        config:
          headers:
            is-ngrok: "1"
            country: ${.ngrok.geo.country_code}
on_http_response: []

Add compression​

Quickly ensure all JSON responses are compressed en route to your API consumer. If your upstream service already handles compression, ngrok skips this step.

# snippet
---
on_http_request: []
on_http_response:
  - expressions: []
    name: Add compression
    actions:
      - type: compress-response
        config:
          algorithms:
            - gzip
            - br
            - deflate
            - compress

Enforce TLS version​

Prevent obsolete and potentially vulnerable browsers, SDKs, or CLI tools like curl from attempting to access your API.

# snippet
---
on_http_request:
  - expressions:
      - conn.tls.version < '1.3'
    name: Reject requests using old TLS versions
    actions:
      - type: custom-response
        config:
          status_code: 401
          content: "Unauthorized: TLS version too old"
on_http_response: []

Log unsuccessful events​

Connect your API to ngrok's event logging system for smarter troubleshooting of your API gateway and upstream services.

# snippet
---
on_http_request: []
on_http_response:
  - expressions:
      - res.status_code < '200' && res.status_code >= '300'
    name: Log unsuccessful requests
    actions:
      - type: log
        config:
          metadata:
            message: Unsuccessful request
            edge_id: <YOUR-NGROK-DOMAIN>
            success: false

Routing requests based on request path​

You can route traffic from one domain to multiple services (ports) based on the path sent in each request.

In your Agent configuration file, you can modify both the forwardInternal and URL Rewrite Traffic Policy Actions to route requests to different upstream ports based on the URL path. For example you may want to route public traffic to a URL such as https://mypublic.ngrok.app/... to http://localhost:80/....

The following example:

  • Creates a public endpoint using an ngrok reserved domain – "mypublic.ngrok.app"
  • Create an internal endpoint – "service1.internal"
  • Uses the forwardInternal action to forward requests that have /service1 in the path to a different port.
  • Removes the added path from the request before sending it to the upstream service using the URL Rewrite action.
    • This path does not have to exist on the upstream service, as a virtual service1 path will exist on the public ngrok endpoint.
# snippet
---
version: "3"
agent:
  authtoken: your-authtoken
endpoints:
  - name: httpexample
    url: https://mypublic.ngrok.app
    upstream:
      url: localhost:80
    traffic_policy:
      on_http_request:
        - expressions:
            - req.url.path.startsWith('/service1')
          actions:
            - type: forward-internal
              config:
                url: https://service1.internal:443
  - name: example-internal-1
    url: service1.internal
    upstream:
      url: localhost:81
    traffic_policy:
      on_http_request:
        - expressions:
            - req.url.path.startsWith('/service1')
          actions:
            - type: url-rewrite
              config:
                from: /service1/?([.*]+)?
                to: /$1