Skip to main content

Restrict IPs

Overview​

The Restrict IPs Traffic Policy action allows you to allow or deny traffic based on the source IP address of connections to your ngrok endpoints.

You can define rules using either Allow and Deny lists, or Reference IDs to existing ngrok IP Policies.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response, on_tcp_connect

Type​

restrict-ips

Configuration Fields​

  • enforcebooleanRequired

    Default true. If false, continue to the next action even if the IP is not permitted.

  • allowarray of strings

    A list of CIDRs that are allowed.

  • denyarray of strings

    A list of CIDRs that are denied.

  • ip_policiesarray of refs

    List of IP Policy identifiers to be checked if the source IP is allowed access.

Behavior​

Evaluation of Rules​

This action evaluates the configured rules against the layer 4 source IP (conn.client_ip) of a connection. HTTP headers like X-Forwarded-For are never used.

Allow and Deny Conditions​

A connection is allowed only if its source IP matches at least one of the allowed CIDRs and does not match any of the denied CIDRs.

Building CIDR Sets​

The set of allowed and denied CIDRs are built from:

  • The CIDRs specified in the allow and deny fields.
  • The CIDRs belonging to the ngrok IP Policies specified in the ip_policies field.

Denied Connection Handling​

If this action denies the connection:

  • An HTTP 403 response is returned.
  • The upstream server is never reached.
  • No further actions or policy rules in the policy configuration will be executed.

IPv6 Support​

This action supports IPv6 addresses for all IP rules. You may use standard abbreviated notations such as "::/0".

Don't forget to create IPv6 rules. It is easy to test with only IPv4 and then suddenly things don't work as expected because you forgot to create IPv6 rules.

Restricting Access with Allow and Deny Lists​

The following Traffic Policy configuration demonstrates how to restrict access to specific IP addresses using the restrict-ips action.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: true
          allow:
            - "1.1.1.1/32"
          deny:
            - "e680:5791:be4c:5739:d959:7b94:6d54:d4b4/128"

This configuration will ensure that only requests from the IP 1.1.1.1 are allowed, while requests from the IP e680:5791:be4c:5739:d959:7b94:6d54:d4b4 are denied.

Example Request​

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, you will receive an HTTP 403 response:

$ curl -i https://example.ngrok.app
HTTP/2 403

Restricting Access with IP Policies​

The following Traffic Policy configuration demonstrates how to restrict access using the restrict-ips action with IP Policies.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: true
          ip_policies:
            - "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"

This configuration will ensure that the IP Policies specified ipp_1yjqdrIBwgciY2I9zH2EelgBbJF are enforced against incoming traffic.

Example Request​

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, you will receive an HTTP 403 response:

$ curl -i https://example.ngrok.app
HTTP/2 403

Test Restricting IPs​

The following Traffic Policy configuration demonstrates how to test restricting IPs using the log action with the restrict-ips action and IP Policies.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: false
          ip_policies:
            - "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
      - type: "log"
        config:
          metadata:
            message: "Restrict IPs action would be ${actions.ngrok.restrict_ips.action} for
              ${conn.client_ip}."
            matched_cidr: "${actions.ngrok.restrict_ips.matched_cidr}"
            error_code: "${actions.ngrok.restrict_ips.error.code}"
            error_message: "${actions.ngrok.restrict_ips.error.message}"

This configuration will test the incoming client IP against the specified IP Policy ipp_1yjqdrIBwgciY2I9zH2EelgBbJF without enforcing it, then log the result using the log action.

Example Request​

The following request will be allowed and an event will be logged:

$ curl -i https://example.ngrok.app
HTTP/2 200

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.restrict_ips.actionstring

    The action taken for this request.

    • Possible values
    • allow - If the request was permitted.
    • deny - If the request was denied.

  • actions.ngrok.restrict_ips.matched_cidrstring

    The CIDR block that matched the incoming client's IP address. If no match was found, this value will be empty.

  • actions.ngrok.restrict_ips.error.codestring

    A machine-readable code describing an error that occurred during the action's execution.

  • actions.ngrok.restrict_ips.error.messagestring

    A human-readable message providing details about an error that occurred during the action's execution.